Für Entwickler

OAuth 2.0 und OpenID Connect

Verwende Authorization Code mit S256-PKCE, prüfe OIDC-Antworten und verwalte Tokens korrekt.

3 Min. LesezeitStand: 18. Oktober 2026

Discovery und Endpunkte#

Der Issuer lautet https://account.julianverse.de. Die Live-Discovery liefert die aktuellen Protokollmetadaten.

Zweck Pfad am Issuer
Discovery /.well-known/openid-configuration
Autorisierung /oauth/authorize
Tokenausgabe und Erneuerung /oauth/token
Benutzerinformationen /oauth/userinfo
Öffentliche Signaturschlüssel /oauth/jwks
Tokenwiderruf /oauth/revoke

Die Discovery nennt zusätzlich Dienst-Scopes und Introspection. Diese sind nicht automatisch für selbst registrierte Browser-Apps nutzbar. Das Browser-SDK ist der einfachste Einstieg in die bestehende Integration.

Scopes auswählen#

openid aktiviert die OIDC-Anmeldung. profile erlaubt freigegebene Profilangaben. email ist für entsprechend registrierte Clients verfügbar. sync erlaubt den Zugriff auf ausdrücklich freigegebene Datenarten der eigenen App.

Die Selbstregistrierung erstellt öffentliche Clients mit openid profile sync. Ein angeforderter Scope ersetzt weder die Zustimmung zur App noch die Freigabe einzelner Sync-Datenarten. Spezielle Scopes wie boards und owncloud gehören zu den dafür eingerichteten Diensten.

Der Codeflow#

  1. Erzeuge für jeden Anmeldeversuch kryptografisch zufällige Werte für state, nonce und den PKCE-code_verifier.
  2. Berechne code_challenge = BASE64URL(SHA256(code_verifier)) ohne Padding. Verwende code_challenge_method=S256.
  3. Leite den Browser zur Autorisierung. redirect_uri muss exakt registriert sein.
  4. Prüfe im Callback den zurückgegebenen state gegen den gespeicherten Wert und behandle auch OAuth-Fehler.
  5. Tausche den einmaligen code zusammen mit dem ursprünglichen code_verifier am Token-Endpunkt.
  6. Prüfe bei Verwendung eines ID-Tokens Signatur, iss, aud, exp und nonce mit einer geeigneten OIDC-Bibliothek.

Eine schematische Autorisierungsanfrage enthält:

GET /oauth/authorize?
  response_type=code&
  client_id=DEINE_CLIENT_ID&
  redirect_uri=DEINE_EXAKTE_CALLBACK_URL&
  scope=openid%20profile%20sync&
  state=ZUFALLSWERT&
  nonce=WEITERER_ZUFALLSWERT&
  code_challenge=DEINE_S256_CHALLENGE&
  code_challenge_method=S256

Die Zeilenumbrüche dienen der Erklärung. Erzeuge die tatsächliche URL mit URL und URLSearchParams, damit Werte korrekt kodiert werden. Die PKCE-Regeln beschreibt RFC 7636.

Code gegen Tokens tauschen#

Öffentliche Clients senden kein Secret. Der Request-Body ist URL-kodiert:

POST /oauth/token HTTP/1.1
Host: account.julianverse.de
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=DEINE_CLIENT_ID&code=ERHALTENER_CODE&redirect_uri=DEINE_KODIERTE_CALLBACK_URL&code_verifier=DEIN_VERIFIER

PKCE ist auch bei vom Betreiber registrierten vertraulichen Clients vorgeschrieben. Ein Client-Secret eines solchen Clients bleibt ausschließlich auf dessen Server. Implicit- und Password-Grant werden nicht angeboten.

Identität und API-Zugriff#

Rufe Userinfo mit Authorization: Bearer ACCESS_TOKEN auf. Identifiziere ein Konto über iss zusammen mit sub, nicht anhand eines Anzeigenamens oder einer E-Mail-Adresse. Access-Tokens sind API-Zugangsdaten; ein ID-Token ist kein Ersatz für das Bearer-Token der Sync-API.

Erneuerung und Widerruf#

Access-Tokens gelten zehn Minuten. Refresh-Tokens rotieren bei Verwendung und gelten höchstens 30 Tage. Ersetze einen verwendeten Refresh-Token durch seinen Nachfolger; Wiederverwendung kann die gesamte Tokenfamilie sperren. Führe Erneuerungen nicht parallel mit derselben Refresh-Version aus.

Der Widerruf der zugehörigen Account-Sitzung sperrt ihre App-Tokens. Front- und Backchannel-Logout sind nicht implementiert. Eine eigene serverseitige App muss deshalb auch ihre eigene Sitzung beenden beziehungsweise die gültige Anmeldung prüfen.

Browser- und Callback-Verhalten#

Das mitgelieferte Panel verwendet ein Popup und hält Zugriffstokens im Arbeitsspeicher. App und Callback müssen dieselbe Origin haben; der Callback benötigt Zugriff auf sein öffnendes Fenster. Eine restriktive Cross-Origin-Opener-Policy kann diesen Ablauf unterbrechen.

Liefere Callbacks als HTML mit Cache-Control: no-store und Referrer-Policy: no-referrer aus und nimm sie von Zugriffslogs und Service-Worker-Caches aus. Auf fremden Domains können Browser die Cookie-Erneuerung blockieren. Dann ist eine erneute Anmeldung per Klick nötig; lokale Inhalte sollen erhalten bleiben.

Markdown herunterladen