OpenID Connect

OAuth ist Autorisierung, OIDC ist Authentifizierung

OAuth 2.0 beantwortet eine einzige Frage: Darf diese Anwendung im Namen dieses Benutzers handeln? Es stellt Access Tokens für APIs aus. Bewusst wird dabei nichts darüber ausgesagt, wer der Benutzer eigentlich ist. Diese Lücke führte über Jahre hinweg zu Verwirrung – OpenID Connect ist die Lösung dafür.

OpenID Connect ist eine schlanke Identitätsschicht auf Basis von OAuth 2.0. Es standardisiert den Login-Flow, definiert ein ID token, das die Identität bestätigt, und stellt Metadaten bereit, damit Clients ohne Rätselraten konfiguriert werden können. Wenn Sie auf „Mit Google anmelden“ oder einen Enterprise-SSO-Button klicken, nutzen Sie OIDC.

Die praktische Faustregel: Wenn Sie wissen müssen, wer der Benutzer ist, verwenden Sie OIDC. Wenn eine App etwas im Namen des Benutzers tun soll, verwenden Sie OAuth. Die meisten Logins benötigen beides, weshalb die beiden Standards normalerweise gemeinsam eingesetzt werden.

Das ID Token

Das Herzstück von OIDC ist das ID Token: ein JWT, das vom Identity Provider signiert wurde. Es enthält die Claims, die Ihre Anwendung benötigt, um einen Login zu bestätigen.

• sub — die stabile, eindeutige Kennung für den Benutzer.
• iss — der Issuer, damit Sie wissen, welcher Provider das Token signiert hat.
• aud — die Client ID, für die es ausgestellt wurde; ein Token für eine andere App muss abgelehnt werden.
• exp und iat — wann es abläuft und wann es ausgestellt wurde.
• nonce — spiegelt den von Ihnen gesendeten Wert wider, um das Token an diesen Login-Versuch zu binden.
• email, name, picture — Profil-Claims, sofern die angeforderten Scopes dies zulassen.

Das ID Token ist für Ihren Client gedacht. Es ist nicht die Anmeldedaten, die Sie an nachgelagerte APIs senden — das ist die Aufgabe des Access Tokens. Die strikte Trennung dieser beiden vermeidet einen häufigen Designfehler.

Discovery

Jeder konforme Provider veröffentlicht ein Discovery-Dokument:

https://accounts.example.com/.well-known/openid-configuration

Darin werden die Endpunkte für Authorization, Token, Userinfo und JWKS sowie die unterstützten Scopes und Algorithmen aufgelistet. Clients rufen dieses Dokument beim Start ab und konfigurieren sich selbst, sodass nichts hard-coded ist und Änderungen am Provider automatisch übernommen werden.

Der Authorization Code Flow mit PKCE

Der empfohlene Flow hält die Credentials aus dem Browser fern. Der Browser verarbeitet lediglich einen kurzlebigen Code.

1. Der Client generiert einen zufälligen code_verifier, hasht diesen zu einem code_challenge und leitet den Browser mit scope=openid an den Provider weiter.
2. Der Benutzer authentifiziert sich beim Provider – dies ist die einzige Stelle, an der ein Passwort oder ein zweiter Faktor eingegeben wird.
3. Der Provider leitet mit einem Authorization code zurück.
4. Das Backend tauscht den Code zusammen mit dem Verifier gegen ein ID Token und ein Access Token ein.
5. Der Client validiert das ID Token und erstellt eine Session.

PKCE (Proof Key for Code Exchange) bindet den Code an den Client, der ihn angefordert hat. Ein während der Übertragung abgefangener Code ist ohne den Verifier nutzlos. Sende immer state, um CSRF zu verhindern, und nonce, um das ID Token an die Anfrage zu binden.

Scopes und Claims

Scopes legen fest, welche Claims Sie erhalten können.

• openid — erforderlich; ohne diesen Scope ist die Anfrage reines OAuth und kein OIDC.
• profile — Name, Profilbild und andere Profilfelder.
• email — die E-Mail-Adresse des Benutzers und ob diese verifiziert ist.
• offline_access — fordert einen Refresh Token an, damit die App zu einem späteren Zeitpunkt agieren kann.

Fordern Sie nur das Minimum an, das Sie tatsächlich benötigen. Jeder zusätzliche Scope bedeutet mehr zu schützende Daten und führt bei einigen Providern zu einer höheren Hürde bei der Zustimmung des Benutzers.

Der userinfo-Endpunkt

Das ID-Token enthält oft nur die grundlegendsten Informationen. Für weitere Profildaten rufen Sie den userinfo-Endpunkt mit dem Access-Token auf:

const userinfo = await client.userinfo(tokenSet.access_token);
// { sub, name, email, email_verified, picture, ... }

Betrachten Sie die sub aus userinfo als maßgeblich und stellen Sie sicher, dass sie mit der sub im ID-Token übereinstimmt. Vertrauen Sie einer E-Mail-Adresse niemals als stabile Kennung – Nutzer ändern diese gelegentlich.

Validierung des ID-Tokens

Die Validierung ist der Schritt, der das gesamte Verfahren sicher macht – und gleichzeitig der Schritt, der am häufigsten falsch implementiert wird. Das Dekodieren des Payloads ist keine Verifizierung; jeder kann ein Token mit beliebigen Claims erstellen.

Bevor Sie einem Claim vertrauen:

1. Signatur — verifizieren Sie diese mit dem öffentlichen Schlüssel des Providers vom JWKS-Endpoint unter Verwendung eines erlaubten Algorithmus.
2. Issuer — iss muss dem erwarteten Provider entsprechen.
3. Audience — aud muss Ihre Client-ID sein.
4. Expiry — exp muss in der Zukunft liegen (unter Berücksichtigung eines geringen Clock Skews).
5. Nonce — muss mit dem Wert übereinstimmen, den Sie für diesen Login gesendet haben.

Nutzen Sie eine gepflegte Library wie openid-client und überlassen Sie ihr diese fünf Schritte. Implementieren Sie das JWT-Parsing für die Authentifizierung niemals selbst.

Sessions nach dem Login

OIDC authentifiziert einmalig beim Login. Es verwaltet nicht die Session deiner Anwendung. Erstelle nach der Validierung des ID tokens deine eigene Session – einen Cookie oder einen Token –, die auf sub basiert.

Behalte diese drei Dinge strikt getrennt:

• Das ID token ist für deinen Client bestimmt und beweist die Identität.
• Das access token dient dem Aufruf von APIs.
• Deine Session ist die Art und Weise, wie deine App den Benutzer über mehrere Requests hinweg erkennt.

Werden diese vermischt, führt dies dazu, dass Provider-Tokens im Browser landen oder ein ID token als API-Credential verwendet wird – beides sind Fehler.

Logout

Der lokale Logout kommt zuerst: Löschen Sie Ihre Session, damit der Benutzer aus Ihrer App abgemeldet wird. Dies liegt immer in Ihrer Kontrolle und ist stets zuverlässig.

Der federierte Logout erfolgt nach dem Best-Effort-Prinzip. Sie können mit einem id_token_hint auf den End-Session-Endpoint des Providers weiterleiten, aber nicht jeder Provider unterstützt dies und die Weiterleitung wird möglicherweise nicht abgeschlossen. Gestalten Sie Ihren Prozess so, dass das Löschen der eigenen Session ausreichend ist, und verlassen Sie sich niemals darauf, dass der Provider den Benutzer abmeldet.

Wann man OIDC einsetzen sollte

OIDC ist die richtige Wahl, wenn:

• Sie die Speicherung von Passwörtern komplett vermeiden möchten.
• Sie Enterprise SSO oder „Anmelden mit…“-Buttons benötigen.
• Ihre Anwendung eine von mehreren Apps ist, die sich einen Login teilen sollen.
• Sie MFA und die Kontowiederherstellung einem spezialisierten Anbieter überlassen möchten.

OIDC ist aufwendiger als ein einfaches Passwort-Formular. Für ein kleines internes Tool mit einer Handvoll Nutzern könnten Session Auth und Password Hashing einfacher und völlig ausreichend sein.

Best Practices

• Verwenden Sie immer den Authorization Code Flow mit PKCE.
• Senden und verifizieren Sie sowohl state als auch nonce.
• Validieren Sie das ID-Token vollständig – Signatur, Issuer, Audience und Ablaufdatum.
• Nutzen Sie Discovery anstelle von hartcodierten Endpunkten.
• Fordern Sie nur die minimal notwendigen Scopes an.
• Trennen Sie Ihre Session von den Provider-Tokens.
• Speichern Sie Client Secrets auf dem Backend, niemals im Browser.

Häufige Fehler

• OAuth als Authentifizierung zu betrachten und die Identität aus einem Access Token abzuleiten.
• Das ID Token zu dekodieren, ohne dessen Signatur zu verifizieren.
• Die aud- oder iss-Prüfungen zu überspringen, sodass Tokens von anderen Apps akzeptiert werden.
• Den Implicit Flow zu verwenden und Tokens in der URL offenzulegen.
• Die E-Mail-Adresse als Primary Key des Benutzers zu verwenden.
• Provider-Tokens an die eigenen APIs zu senden, als wären sie Session-Credentials.
• Zu vergessen, dass der Logout zuerst die eigene Session beenden muss.

Wie geht es weiter?

Falls Sie es noch nicht gelesen haben, beginnen Sie mit OAuth 2.0, um das Autorisierungsprotokoll zu verstehen, auf dem OIDC aufbaut, und mit dem JWT-Guide für das Token-Format. Sobald der Login erfolgreich war, zeigt der Guide zu Session Auth, wie der Benutzer angemeldet bleibt, und RBAC & Permissions behandelt, was diese tun dürfen.