Kostenlos testen

OAuth2 API Referenz

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.


Endpunkt

https://<hostname:port>/oauth

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


Anwendung registrieren

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:

  • Name: der Anwendungsname
  • Beschreibung: eine optionale Beschreibung der Anwendung, wofür sie verwendet wird, usw.
  • Erlaubte Zugriffstypen: die erlaubten Zugriffstypen, die die Anwendung verwenden darf. Zum Beispiel "sogenannter Autorisierungscode" und "Erneuerungstoken" sind typisch für einen standardmäßigen interaktiven Autorisierungsfluss. Details zu den verschiedenen Zugriffstypen finden Sie in der OAuth2-Spezifikation.
  • Weiterleitungs-URIs: einer oder mehrere Weiterleitungs-URIs, die als Ziel nach der Zugriffsgewährung für Autorisierungscodes erlaubt sind.

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.


OAuth2-Zugriffstoken erhalten

Die folgenden Schritte beschreiben, wie Ihre Anwendung mit dem Server interagiert, um die Zustimmung des Benutzers zu erhalten und Zugriffstoken zu erhalten.

Schritt 1: Leiten Sie den Benutzer zur Autorisierungsseite mit Autorisierungsparametern für Ihre Anwendung weiter

https://<hostname:port>/oauth/authorize?
                            response_type=code&
                            client_id=Ihre_Client-ID&
                            redirect_uri=https://ihre-anwendung.com/oauth2/callback&
                            state=Zustandswert
                        
Abfrageparameter
  • client_id: die Client-ID für Ihre Anwendung. Nach der Registrierung Ihrer Anwendung auf der API-Seite in den Organisationseinstellungen erhalten. Erforderlich.
  • redirect_uri: der URI, zu dem der Server den Benutzer nach Abschluss des Autorisierungsflusses weiterleitet. Der Wert muss genau einem der autorisierten Weiterleitungs-URIs entsprechen, die für Ihre Anwendung auf der API-Seite in den Organisationseinstellungen registriert sind. Wenn dieser Wert nicht mit einem autorisierten Weiterleitungs-URI für die bereitgestellte client_id übereinstimmt, erhalten Sie einen Weiterleitungs-URI-Abgleichsfehler.
  • state: ein Wert, den Ihre Anwendung verwendet, um den Zustand zwischen der Autorisierungsanfrage und der Antwort des Servers aufrechtzuerhalten. Dies wird genau so wie bereitgestellt als Abfrageparameter an redirect_uri angehängt.

Schritt 2: Der Server fordert die Zustimmung des Benutzers an

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.

Schritt 3: Behandeln Sie die Antwort des Servers auf Ihren redirect_uri

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.

Beispielantwort für Autorisierungscode:
https://ihre-anwendung.com/oauth2/callback?code=XXXXXXXXXXXXXXXX
Beispielantwort für Fehler:
https://ihre-anwendung.com/oauth2/callback?error=access_denied

Schritt 4: Tauschen Sie den Autorisierungscode gegen Zugriffstoken aus

Ihre Anwendung kann dann den Autorisierungscode gegen Zugriffstoken über den nachstehenden Token-Endpunkt austauschen.



Ein Zugriffstoken anfordern

Um ein Zugriffstoken anzufordern, rufen Sie die Methode token auf und übergeben Sie Anmeldeinformationen des Kontos zur Authentifizierung.

POST /oauth/token

POST-Felder

  • grant_type: der angeforderte Zugriffstyp, wie "Autorisierungscode" oder "Passwort". Erforderlich.
  • client_id: die OAuth2-Client-ID. "Anchor" kann für Anwendungen mit nur Passwörtern verwendet werden. Erforderlich.
  • client_secret: das OAuth2-Client-Geheimnis. Erforderlich, sofern nicht der integrierte "Anchor"-Client mit nur Passwörtern verwendet wird.
  • code: (für "Autorisierungscode"-Zugriffe) der Autorisierungscode.
  • redirect_uri: (für "Autorisierungscode"-Zugriffe) der URL.
  • Benutzername: (für "Passwort"-Zugriffe) der Benutzername für das zu authentifizierende Konto.
  • Passwort: (für "Passwort"-Zugriffe) das Passwort für das zu authentifizierende Konto.
  • Authentifizierungscode: (für "Passwort"-Zugriffe) der zweistufige Bestätigungscode für das zu authentifizierende Konto. Erforderlich, wenn das Konto die zweistufige Bestätigung aktiviert hat.
  • GUID: die GUID, die dem Client zugewiesen ist, oder leer, falls noch keine zugewiesen wurde.
  • DNS-Name: ein beschreibender Name für den Client, wie der Hostname oder der Gerätehersteller und -modell.
  • OS-Typ: der Clientsystemtyp, wie "win", "osx", "android", "ios" oder "winphone".
  • OS-Version: die Clientsystemversion, wie "4.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.
  • access_token: (für "Autorisierungscode"-Zugriffe) ein Zugriffstoken aus der vorherigen Zugriffstokenanforderung.
  • 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>
...

Are you in the right place?

Please select your preferred language: