Die leitzcloud API (v2+) erfordert eine Authentifizierung über OAuth2. Derzeit unterstützt es das password und refresh token grant. Typen mit authorization code und client-credential werden in naher Zukunft hinzugefügt.
Dieses Dokument geht nicht auf die Details der OAuth2-Spezifikation ein, sondern konzentriert sich auf einfache Schritte zur Verwendung mit der leitzcloud. Die Implementierung von OAuth2 durch leitzcloud basiert auf den Komponenten RFC 6749.
https://<hostname:port>/oauth
Alle Anfragen an die OAuth2-API müssen über HTTPS erfolgen. Nicht-HTTPS-Anfragen werden abgelehnt.
Um ein Zugriffstoken anzufordern, rufen Sie die Methode token
auf und übergeben Sie die Zugangsdaten zur Authentifizierung.
POST /oauth/token
POST /oauth/token grant_type=password&client_id=anchor&username=user@example.com&password=example
HTTP status code: 200
Response body:
{
"access_token": "<access_token>",
"expires_in": 3600,
"guid": "<guid>",
"token_type": "Bearer",
"refresh_token": "<refresh_token>",
"scope": "full"
}
Die Antwort sollte gespeichert werden. Das Zugriffstoken wird an API-Methoden übergeben, die eine Authentifizierung erfordern. Zugriffstoken sind gültig für eine kurze Zeitspanne, normalerweise 1 Stunde, und der Aktualisierungs-Token wird verwendet, um einen neuen Zugriffstoken zu erhalten, wenn er abläuft. Der expires_in
Wert ist in Sekunden angegeben. Der token_type
und scope
werden immer "Bearer" bzw. "full" sein.
Die in der Antwort zurückgegebene guid
ist entweder die in der ursprünglichen Anfrage übergebene GUID, wenn sie auf dem Server gefunden wird, oder eine neue GUID, die dem Client zugewiesen wurde. Es sollte für die spätere Verwendung bei der Aktualisierung von Token gespeichert werden.
Wenn für ein Konto die Zwei-Faktor-Authentifizierung aktiviert ist, wird beim ersten Anruf Folgendes angezeigt:
HTTP status code: 401
Response body:
{
"error": "missing_totp",
"two_step_mode": "(email|sms|authenticator)"
}
In diesem Fall sollte der Benutzer zur Eingabe eines Zwei-Faktor-Authentifizierungscodes aufgefordert und die Anforderung mit dem angehängten Code wiederholt werden. Der leitzcloud-Server hat den Benachrichtigungsprozess bei der Zustellung von E-Mails oder SMS bereits ausgelöst.
POST /oauth/token grant_type=password&client_id=anchor&username=user@example.com&password=example&auth_code=<auth_code>
Wenn der Code gültig ist, wird ein Zugriffstoken zurückgegeben. Ansonsten gilt Folgendes:
HTTP status code: 401
Response body:
{
"error": "invalid_totp",
"two_step_mode": "(email|sms|authenticator)"
}
Wenn wiederholte fehlgeschlagene Authentifizierungsversuche auftreten, wird das Konto für einen kurzen Zeitraum daran gehindert, weitere Authentifizierungsversuche durchzuführen:
HTTP status code: 403
Response body:
{
"error": "account_locked"
}
Das Aktualisieren eines Zugriffstokens verwendet ebenfalls die gleiche Methode token
wie die erste Authentifizierungsanforderung. In diesem Fall wird der refresh_token
aus einer früheren Zugriffstokenanforderung anstelle von Kontoanmeldeinformationen übergeben.
POST /oauth/token
POST /oauth/token grant_type=refresh_token&client_id=anchor&refresh_token=<refresh_token>
HTTP status code: 200
Response body:
{
"access_token": "<access_token>",
"expires_in": 3600,
"guid": "<guid>",
"token_type": "Bearer",
"refresh_token": "<refresh_token>",
"scope": "full"
}
Um ein Zugriffstoken zu invalidieren, rufen Sie die Methode revoke
auf.
POST /oauth/revoke
POST /oauth/revoke client_id=anchor&token=<token>&token_type_hint=access_token
HTTP status code: 200
Für gültige Anfragen ist die Antwort immer HTTP 200. Der "Response Body" wird ignoriert.
Sobald ein Zugriffstoken erhalten wurde, kann er zur Authentifizierung von Anforderungen verwendet werden, indem er im Autorisierungskopf (authentification header) übergeben wird.
GET /api/2/files/1 Authorization: Bearer <access_token> ...