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.



Anforderung eines Access-Tokens

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

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>
...

Starten Sie Ihren Test


Erstellen Sie Ihren Account!

Mindestens 1 Großbuchstabe
Mindestens 1 Sonderzeichen
Mindestens 1 Zahl
Zwischen 10 und 25 Zeichen

Starten Sie Ihren Test


Erzählen Sie uns mehr!

Starten Sie Ihren Test


Überprüfen Sie Ihre Angaben.

Benutzername:
Name:
Unternehmen:
Telefon:
Straße, Nr.:
PLZ:
Ort:
Land:

Schritt 1 von 3


14 Tage kostenlos

Bis zu 10 Nutzer registrieren
Kostenlose Gastkonten
Voller Funktionsumfang
Persönliche Ansprechpartner
Keine Kreditkarte erforderlich
Test endet automatisch

Mit der LeitzCloud nutzen Sie eine sichere Freigabe- und Speicherlösung, die Sie bei der engen Zusammenarbeit mit Kollegen, Kunden und Partnern unterstützt!

Schritt 2 von 3


Voller Funktionsumfang

Sync Tool & Synced App
Hohe Uploadgeschwindigkeit
Online-Bearbeitung
Eigene Richtlinien
Dateiwiederherstellung
Revisionsverlauf
Gesicherte Freigaben
SSL- & 256-Bit-Verschlüsselung

Wir speichern Ihre Daten ausschließlich in eigenen Rechenzentren in Deutschland!

Schritt 3 von 3


Kostenloser Support

Persönliche Ansprechpartner
Online-Demonstration
Unterstützung bei der Einrichtung
Umfangreiche Wissensdatenbank

Beginnen Sie jetzt Ihre Arbeit in der LeitzCloud und speichern, verwalten und teilen Sie Ihre Daten einfach und sicher!