OAuth2-Autorisierungscode-Ablauf #

Diese Seite richtet sich an App-Entwickler, deren Benutzer sich mit ihrem eigenen Exponential-Konto anmelden, damit die App als der jeweilige Benutzer liest und schreibt. Sie geht den Ablauf so durch, wie der Code ihn implementiert, und nennt die Teile, die von dem abweichen, was aktuelle OAuth-Empfehlungen für mobile Apps erwarten.

Inhalt #

1. Der Ablauf im Überblick
2. Schritt 1: den Client registrieren
3. Schritt 2: die Autorisierungsseite
4. Schritt 3: den Code eintauschen
5. Schritt 4: die API aufrufen
6. Tokens erneuern
7. Grenzen der Implementierung

Der Ablauf im Überblick #

app  -> system browser: https://example.com/oauth/authorize?client_id=...&redirect_uri=...&response_type=code
user -> signs in on the site and allows the app
site -> redirect_uri?code=<code>&expires_in=<seconds>
back end -> POST /api/auth/v1/oauth/token (grant_type=authorization_code, client_id, client_secret, code, redirect_uri)
         <- {"access_token": "...", "refresh_token": "...", "expires_in": 3600}
app or back end -> GET /api/ezp/v2/... with Authorization: OAuth <access_token>

Weil der Token-Endpunkt das Client-Secret braucht, gehört der Austausch auf einen Server, den Sie betreiben (Ein Backend für Ihre App).

Schritt 1: den Client registrieren #

Ein Administrator öffnet Setup > oAuth-Verwaltung (/oauthadmin/list), Reiter Anwendungen, und legt eine Anwendung an. Sie erhält eine zufällige Client-Kennung und ein Secret sowie die Weiterleitungsadresse (Endpunkt) der Anwendung. Das Secret ist auf der Seite der Anwendung eingeklappt, bis Das Geheimnis zeigen gedrückt wird (Persönliche API-Schlüssel, Abschnitt 7).

Die Autorisierungsseite vergleicht die redirect_uri einer Anfrage exakt, Zeichen für Zeichen, mit dem registrierten Endpunkt (ezpRestClient::isEndPointValid()). Registrieren Sie die Adresse genau so, wie die App oder das Backend sie senden wird, und ohne Query-String: Die Website hängt ?code=... daran an.

Schritt 2: die Autorisierungsseite #

Öffnen Sie die Autorisierungsseite im Systembrowser (einem Browser-Tab innerhalb der App, keiner eingebetteten Web View, damit die App das Passwort des Benutzers nie sieht):

https://example.com/oauth/authorize?client_id=<client id>&redirect_uri=<redirect uri>&response_type=code

• Ein Besucher, der nicht angemeldet ist, wird zuerst zur Anmeldung aufgefordert und kehrt dann zur Seite zurück.
• Der Benutzer lässt die App zu. Seit 6.0.15 braucht der Benutzer dafür die Richtlinie OAuth / Authorize (oauth/authorize), optional nach Siteaccess beschränkt; ohne sie leitet die Website mit error=access_denied weiter (Richtlinie OAuth authorize). Geben Sie sie den Rollen der Personen, die die App benutzen.
• Fehler, bevor die Weiterleitungsadresse geprüft ist (unbekannter Client, falsche Adresse), antworten auf der Website mit 400 und leiten nicht weiter; spätere Fehler gehen als error=... an die Weiterleitungsadresse.
• Bei Erfolg leitet die Website an <redirect uri>?code=<code>&expires_in=<seconds> weiter.

Schritt 3: den Code eintauschen #

curl -s https://example.com/api/auth/v1/oauth/token \
     -d grant_type=authorization_code -d client_id='<client id>' -d client_secret='<client secret>' \
     -d code='<code>' -d redirect_uri='<redirect uri>'

Die Antwort trägt access_token, refresh_token und expires_in (den Wert von rest.ini [OAuthSettings] TokenTTL, standardmäßig 3600 Sekunden). Auch der Code selbst läuft nach TokenTTL ab.

Schritt 4: die API aufrufen #

Authorization: OAuth <access_token>

Die REST-Schicht akzeptiert für OAuth-Tokens auch Authorization: Bearer <access_token> sowie einen Formularparameter oauth_token eines POST-Bodys. Ein Query-Parameter oauth_token wird abgelehnt, außer die Website setzt rest.ini [OAuthSettings] AllowTokenInQuery=enabled: URLs werden von Servern und Proxys protokolliert. Verwenden Sie den Header.

Tokens erneuern #

Wenn ein Aufruf mit 401 antwortet oder die Zeit von expires_in verstrichen ist, fordern Sie ein neues Token an:

curl -s https://example.com/api/auth/v1/oauth/token \
     -d grant_type=refresh_token -d client_id='<client id>' -d client_secret='<client secret>' \
     -d refresh_token='<refresh token>'

Die Antwort hat dieselben drei Schlüssel. Speichern Sie das neue Refresh-Token anstelle des alten: Ein Refresh-Token gilt rest.ini [OAuthSettings] RefreshTokenTTL (standardmäßig 30 Tage) ab der Erneuerung, die es ausgestellt hat, und es funktioniert nicht mehr, sobald der Benutzer deaktiviert oder gesperrt ist. Erneuern Sie einmal; scheitert das, schicken Sie den Benutzer erneut über die Autorisierungsseite. Auch das Erneuern braucht das Client-Secret, also läuft es ebenfalls im Backend.

Grenzen der Implementierung #

Geprüft in kernel/private/rest/classes/controllers/oauth_token.php und kernel/private/modules/oauth/authorize.php:

Nichts davon ist für eine ältere OAuth2-Implementierung ungewöhnlich; es bedeutet nur, dass ein öffentlicher mobiler Client nicht direkt mit dem Token-Endpunkt sprechen sollte.

Verwandte Seiten #

• Ein Backend für Ihre App
• REST-API v1 und v2: OAuth2-Tokens
• OAuth und API-Schlüssel
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.