Authorization-Code-Flow

1. Start

Ihr Backend erzeugt einen zufälligen state und einen PKCE-code_verifier (43 bis 128 Zeichen, RFC 7636), speichert beide auf dem Server für diesen Browser und leitet den Browser weiter an:

<auth>/oauth/authorize
  ?response_type=code
  &client_id=<Ihre Client-ID>
  &redirect_uri=<eine Ihrer Redirect-URIs, exakt>
  &scope=openid
  &state=<state>
  &code_challenge=<BASE64URL(SHA256(code_verifier))>
  &code_challenge_method=S256

nonce ist optional und kommt im ID-Token zurück. prompt und max_age werden nicht unterstützt.

2. Anmeldung

<auth> schickt den Browser weiter zu den Anmeldeseiten, im Anmelde-Branding der Organisation und mit dem Namen Ihres Frontends. Die Person gibt zuerst ihre E-Mail-Adresse ein, dann ihr Passwort, oder sie registriert sich mit einem Bestätigungscode, der an diese Adresse geht. Wo das Frontend danach fragt, gibt sie ihre Mitgliedsnummer und ihre Angaben ein, um Mitglied zu werden. Dann führen die Anmeldeseiten die Mitgliedschaftsprüfung durch und genehmigen die Anfrage.

Wer im selben Browser noch von einem anderen Frontend der Organisation auf den Anmeldeseiten angemeldet ist, kommt ohne Passwort durch (bis zu 7 Tage ohne Nutzung, höchstens 30 Tage), aber die Mitgliedschaftsprüfung läuft erneut.

3. Callback

Der Browser kommt mit code und state zu Ihrer Redirect-URI zurück. Prüfen Sie, dass state der ist, den Sie für diesen Browser gespeichert haben, und tauschen Sie dann den Code aus Ihrem Backend ein:

POST <auth>/oauth/token
Authorization: Basic base64(<Client-ID>:<Client-Secret>)
apikey: <Publishable Key>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<dieselbe Redirect-URI>&code_verifier=<code_verifier>

Die Antwort enthält access_token, token_type (bearer), expires_in (3600), refresh_token und id_token.

4. Refresh

Erneuern Sie das Zugriffstoken, bevor es abläuft, aus Ihrem Backend:

POST <auth>/oauth/token
Authorization: Basic base64(<Client-ID>:<Client-Secret>)
apikey: <Publishable Key>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<Refresh-Token>

Jeder Refresh liefert ein neues Refresh-Token. Speichern Sie es, bevor Sie das neue Zugriffstoken verwenden, und führen Sie pro Sitzung nur einen Refresh gleichzeitig aus: Ein bereits verwendetes Refresh-Token wird nur 10 Sekunden lang noch einmal akzeptiert; danach gilt seine Verwendung als Diebstahl und beendet die ganze Sitzung.

Die Regeln und die Fallen dahinter

• Nur PKCE S256. Die Discovery nennt auch plain; verwenden Sie es nie.
• Scope genau openid. Die Anmeldeseiten weisen jeden anderen Scope mit einer Fehlerseite ab, und auch das Token wird verweigert. Eine Anfrage ohne Scope ist nicht openid: Der Auth-Server vermerkt sie als email, und sie wird abgewiesen. Fügen Sie kein offline_access hinzu: Sie erhalten auch ohne es ein Refresh-Token.
• state ist Pflicht, obwohl das Protokoll es offenlässt. Neben dem Schutz Ihres Callbacks erlaubt es den Anmeldeseiten, eine abgelaufene Anfrage neu zu starten: Eine Autorisierung lebt 10 Minuten, eine Registrierung mit ihrem E-Mail-Code kann länger dauern, und die Anmeldeseiten starten dann dieselbe Anfrage neu, sodass Sie Ihren Code trotzdem mit Ihrem eigenen state für Ihren eigenen code_verifier erhalten. Bewahren Sie state und Verifier mindestens 30 Minuten auf.
• HTTP Basic für den Client (client_secret_basic). Das Secret im Formularinhalt wird abgewiesen.
• Redirect-URIs sind exakt. Eine Anfrage, die die Anmeldeseiten nicht bedienen können (ein unbekanntes oder getrenntes Frontend, eine nicht eingetragene Redirect-URI, ein falscher Scope), endet dort auf einer neutralen Fehlerseite; nichts kommt zu Ihrer Redirect-URI zurück.

Lebensdauern