Die leitzcloud API (v2+) erfordert eine Authentifizierung über OAuth2. Sie unterstützt Autorisierungscode, Erneuerungstoken und Passwort-Zugriffe.
Dieses Dokument wird nicht auf die Details der OAuth2-Spezifikation eingehen, sondern sich stattdessen auf einfache Schritte zur Verwendung mit leitzcloud konzentrieren. Die Implementierung von OAuth2 in leitzcloud basiert auf RFC 6749.
https://<hostname:port>/oauth
Alle Anfragen an die OAuth2-API müssen über HTTPS erfolgen. Nicht-HTTPS-Anfragen werden abgelehnt.
Beginnen Sie damit, eine neue Anwendung für Ihre Organisation zu registrieren, oder bitten Sie Ihren Organisationsadministrator, die Registrierung abzuschließen. Besuchen Sie die "API"-Seite in den Einstellungen der Organisation und klicken Sie auf "OAuth2-Client registrieren".
Geben Sie die folgenden Details für Ihre Anwendung an:
Nach Abschluss wird eine eindeutige, zufällige Client-ID und ein Client-Geheimnis generiert. Diese müssen in der registrierten Anwendung in der Regel konfiguriert werden, bevor sie sich authentifizieren kann.
Die folgenden Schritte beschreiben, wie Ihre Anwendung mit dem Server interagiert, um die Zustimmung des Benutzers zu erhalten und Zugriffstoken zu erhalten.
https://<hostname:port>/oauth/authorize?
response_type=code&
client_id=Ihre_Client-ID&
redirect_uri=https://ihre-anwendung.com/oauth2/callback&
state=Zustandswert
Der Benutzer erhält eine Autorisierungsseite, auf der er gebeten wird, Ihrer Anwendung den Zugriff auf sein Konto zu gestatten. Ihre Anwendung tut nichts weiter, sondern wartet darauf, dass der Server nach der Zustimmung oder Ablehnung der Anfrage zurückleitet.
Nachdem der Benutzer den Zustimmungsschritt abgeschlossen hat, leitet der Server zur bereitgestellten redirect_uri mit einem code oder Fehler-Abfrageparameter sowie Zustand, wenn bereitgestellt, weiter.
https://ihre-anwendung.com/oauth2/callback?code=XXXXXXXXXXXXXXXX
https://ihre-anwendung.com/oauth2/callback?error=access_denied
Ihre Anwendung kann dann den Autorisierungscode gegen Zugriffstoken über den nachstehenden Token-Endpunkt austauschen.
Um ein Zugriffstoken anzufordern, rufen Sie die Methode token auf und übergeben Sie Anmeldeinformationen des Kontos 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> ...