Authentifizierung und Autorisierung
- Philipp Frick
- Sebastian Schulz
Für die Verwendung der RESTful API muss eine Authentifizierung und Autorisierung per OAuth 2.0 stattfinden. Die Lebenszeiten der dafür notwendigen Tokens müssen in der entsprechenden Konfiguration gepflegt werden.
Konfiguration von OAuth 2.0
Folgende Konfigurationsoptionen werden aktuell für die Authentifizierung bereit gestellt:
Lebenszeit des Zugriffstokens
Lebenszeit des Aktualisierungstoken
Lebenszeit des Links für einen Brandbox-Backend-Login
Setzen Sie in der OAuth 2.0 Konfiguration folgende Werte:
Bezeichnung | Wert |
|---|---|
Zugriffstoken Gültigkeitsdauer (Sekunden) | 3600 |
Aktualisierungstoken Gültigkeitsdauer (Sekunden) | 30879000 |
Brandbox-Backend Token Gültigkeitsdauer (Sekunden) | 1800 |
Authentifizierung
Alle Zugriffe auf die Schnittstelle benötigen einen Zugriffstoken. Dieser lässt sich mit einer Authentifizierungsanfrage auf den Endpunkt accesstoken erhalten. Dazu kann entweder eine Benutzername/Passwort-Kombination oder ein Erneuerungstoken verwendet werden.
Da Erneuerungstokens mit dem Zugriffstoken ausgeliefert wird, muss eine initiale Authentifizierung mindestens einmalig immer mit einem brandbox-User erfolgen.
POST
Ressource
/rest/v5/accessToken
Parameter
Parameter | Wert |
|---|---|
grant_type | "password" für die Authentifizierung mit brandbox-User oder "refresh_token" für die Authentifizierung per Erneuerungstoken |
client_id | Mandanten-ID |
client_secret | "clientSecret" (fester Wert) |
username | Benutzername, nur bei grant_type "password" |
password | Passwort, nur bei grant_type "password" |
refresh_token | Erneuerungstoken, nur bei grant_type "refresh_token" |
Response
Key | Wert | Datentyp |
|---|---|---|
token_type | "Bearer" (fester Wert) | string |
expires_in | Gültigkeit in Sekunden | integer |
access_token | Zugriffstoken für die Autorisierung von Folge-Requests | string |
refresh_token | Erneuerungstoken für die Anforderung eines neuen Zugriffstokens | string |
Autorisierung
Mit Ausnahme der Authentifizierungsanfrage accesstoken erwarten alle Ressourcen einen Autorisierungs-Header, den einen gültigen Zugriffstoken enthält.
Hierzu muss ein HTTP-Request-Header Authorization gesendet werden, der einen gültigen Zugriffstoken enthält.
Bei fehlerhafter Autorisierung antwortet die API mit einem Response-Code 400 und entsprechender Fehlermeldung.