Authentifizierung

Einige unserer APIs sind nur für identifizierte User nutzbar. Die Authentifizierung erfolgt nach dem OAuth 2.0 Standard und wird über eine eigene, von der API unabhängige, Plattform (Identity-Service) durchgeführt. Zu Beginn der API Nutzung wird über die zur Verfügung gestellten Zugangsdaten von dieser Plattform ein Zugangstoken (Access-Token) erzeugt. Dieser Token ist dann bei jedem Request im HTTP Header Authorization mitzusenden.

Access-Token

Beim Access-Token handelt es sich um einen sog. JSON Web Token (JWT).
Dieser Token kann über Standard Bibliotheken oder auch Online (jwt.io) ausgelesen werden.

Zugangsdaten

Um einen gültigen Access-Token zu erhalten werden Zugangsdaten bestehend aus

client_id (entspricht dem Username),
client_secret (entspricht dem Password),
scopes (= spezielle Berechtigungen), sowie
die Adresse unseres Identity-Services url_to_authentication_service

benötigt. client_id und client_secret erhalten Sie einmalig zu Beginn der Laufzeit des Vertrages. Für unsere verschiedenen APIs (Services) nutzen wir individuelle URLs unseres Identiy-Services. Sie erhalten die url_to_authentication_service zusammen mit den Zugangsdaten.

Scopes sind Berechtigungen, die eine feinere Kontrolle des Zugangs der Anwendung erlauben. Die möglichen Scopes sind in der jeweiligen API Dokumentation ersichtlich und bei jedem Endpunkt angegeben:

Ein Scope

Eine Interaktion mit der API mit nur lesenden Zugriffen benötigt beispielsweise nur lesende Rechte. Zum Erzeugen oder ändern von Ressourcen werden meist auch schreibende Rechte benötigt.

Empfehlung

Geben Sie einer Anwendung nur jene Scopes, die benötigt werden!

Code-Snippets

cURL

AUTH_URL="<url to authentication service>"
CLIENT_ID="<client_id>"
CLIENT_SECRET="<client_secret>"
SCOPES="<scopes space separated>"

curl $AUTH_URL \
   --header 'Accept: application/json, text/plain, */*' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=client_credentials'  \
   --data-urlencode 'client_id='$CLIENT_ID \
   --data-urlencode 'client_secret='$CLIENT_SECRET \
   --data-urlencode 'scope='"$SCOPES"

Python 3.6+

import requests

auth_url = "<URL to authentication service>"
client_id = "<client_id>"
client_secret = "<client_secret>"
scopes = ["<scope1>", "<scope2>", ]

payload = {
    "client_id": f"{client_id}",
    "client_secret": f"{client_secret}",
    "grant_type": "client_credentials",
    "scope": " ".join(scopes)
}
headers = {
  'Accept': 'application/json, text/plain, */*',
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", auth_url, headers=headers, data=payload)

print(response.json())
print(response.text)

Beispiel Erzeugung und Nutzung

Erzeuge Access-Token mit Lese- und Schreibberechtigungen (= Scopes) foo:read und foo:write.

$ curl --request POST \
$   --location ":url_to_authentication_service:" \
$   --header "Content-Type: application/x-www-form-urlencoded" \
$   -d "client_id=:your client_id:&client_secret=:your client_secret:&grant_type=client_credentials&scope=foo%3Aread%20foo%3Awrite" 
---> 100%

{
  "access_token": "eyJhbGciOiJSU...baVQ",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "email foo:read foo:write profile"
}

Den Wert des Feldes access_token kopiert man nun aus dieser Antwort und setzt diesen JWT als String im HTTP Header Authorization zusammen mit Bearer ein:

$ curl --request GET --location "https://api_url/v1/foo/" \
$  --header "Authorization: Bearer :access_token:" \      <--- HIER EINSETZEN
...

Gültigkeitsdauer

Der Access-Token ist 300 Sekunden lang gültig und wird für mehrere Requests verwendet.