OAuth2 API Referenz

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.

---

Voraussetzung

https://<hostname:port>/oauth

Alle Anfragen an die OAuth2-API müssen über HTTPS erfolgen. Nicht-HTTPS-Anfragen werden abgelehnt.

---

POST /oauth/token

POST Fields

• grant_type: der angeforderte Grant-typ, in diesem Fall "Passwort". Benötigt.
• client_id: die OAuth2-Client-ID, "anchor" nur zu diesem Zeitpunkt. Benötigt.
• username: der Benutzername für das zu authentifizierende Konto. Benötigt.
• password: das Passwort für das zu authentifizierende Konto. Benötigt.
• auth_code: den zweistufigen Verifizierungscode für das zu authentifizierende Konto. Es ist nur erforderlich, wenn die Zwei-Faktor-Authentifizierung des Kontos aktiviert ist.
• guid: die dem Client zugeordnete oder leere GUID, falls diese noch nicht zugeordnet wurde.
• dns_name: einen beschreibenden Namen für den Client, wie beispielsweise den Hostnamen oder den Gerätehersteller und das Modell.
• os_type: den Typ des Client-Systems, wie z.B. "win", "osx", "android", "ios" oder "winphone".
• os_version: die Version des Client-Systems, z.B. "4.2.2.2".

Beispiel

Anfrage

POST /oauth/token
grant_type=password&client_id=anchor&username=user@example.com&password=example

Rückmeldung

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.

Zwei-Faktor-Authentifizierung

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

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 Fields

• grant_type: der angeforderte Grant-typ, "refresh_token" in diesem Fall Benötigt.
• client_id: die OAuth2-Client-ID, "anchor" nur zu diesem Zeitpunkt.Benötigt.
• refresh_token: ein Aktualisierungs-Token aus der vorherigen Zugriffstokenanforderung. Benötigt.
• guid: die dem Client zugeordnete oder leere GUID , falls diese noch nicht zugeordnet wurde. Typischerweise sollte dies die GUID sein, die der Server bei der Anforderung des Initial Access Token zugewiesen hat.
• dns_name: einen beschreibenden Namen für den Client, wie beispielsweise der Hostname oder der Gerätehersteller und das Modell.
• os_type: den Typ des Client-Systems, wie z.B. "win", "osx", "android", "ios" oder "winphone".
• os_version: die Version des Client-Systems, z.B. "5.1.0".

Beispiel

Anfrage

POST /oauth/token
grant_type=refresh_token&client_id=anchor&refresh_token=<refresh_token>

Rückmeldung

HTTP status code: 200
Response body:
{
    "access_token": "<access_token>",
    "expires_in": 3600,
    "guid": "<guid>",
    "token_type": "Bearer",
    "refresh_token": "<refresh_token>",
    "scope": "full"
}

---

Zugriff widerrufen

Um ein Zugriffstoken zu invalidieren, rufen Sie die Methode revoke auf.

POST /oauth/revoke

POST Fields

• client_id: die dem Token zugeordnete OAuth2-Client-ID, "anchor" nur zu diesem Zeitpunkt. Benötigt.
• token: das zu widerrufende Token. Benötigt.
• token_type_hint: die Art des übermittelten Token, "access_token" oder "refresh_token".

Beispiel

Anfrage

POST /oauth/revoke
client_id=anchor&token=<token>&token_type_hint=access_token

Rückmeldung

HTTP status code: 200

Für gültige Anfragen ist die Antwort immer HTTP 200. Der "Response Body" wird ignoriert.

---

Authentifizierung von Anfragen

Sobald ein Zugriffstoken erhalten wurde, kann er zur Authentifizierung von Anforderungen verwendet werden, indem er im Autorisierungskopf (authentification header) übergeben wird.

Beispiel einer Anfrage

GET /api/2/files/1
Authorization: Bearer <access_token>
...