Benutzerdefinierter ID-Token

Einführung

ID-Token (ID token) ist ein spezieller Token-Typ, der durch das OpenID Connect (OIDC)-Protokoll definiert ist. Er dient als Identitätsnachweis, der vom Autorisierungsserver (Logto) nach erfolgreicher Authentifizierung eines Benutzers ausgestellt wird und Ansprüche (Claims) über die Identität des authentifizierten Benutzers enthält.

Im Gegensatz zu Zugangstokens, die zum Zugriff auf geschützte Ressourcen verwendet werden, sind ID-Token speziell dafür konzipiert, die authentifizierte Benutzeridentität an Client-Anwendungen zu übermitteln. Sie sind JSON Web Tokens (JWTs), die Ansprüche über das Authentifizierungsereignis und den authentifizierten Benutzer enthalten.

Wie ID-Token-Ansprüche funktionieren

In Logto werden ID-Token-Ansprüche in zwei Kategorien unterteilt:

1. Standard-OIDC-Ansprüche: Durch die OIDC-Spezifikation definiert, werden diese Ansprüche vollständig durch die während der Authentifizierung angeforderten Berechtigungen (Scopes) bestimmt.
2. Erweiterte Ansprüche: Von Logto erweiterte Ansprüche, die zusätzliche Identitätsinformationen enthalten und durch ein Dual-Bedingungsmodell (Berechtigung + Umschalter) gesteuert werden.

Standard-OIDC-Ansprüche

Standardansprüche werden vollständig durch die OIDC-Spezifikation geregelt. Ihre Aufnahme in den ID-Token hängt ausschließlich von den Berechtigungen ab, die deine Anwendung während der Authentifizierung anfordert. Logto bietet keine Option, einzelne Standardansprüche zu deaktivieren oder selektiv auszuschließen.

Die folgende Tabelle zeigt die Zuordnung zwischen Standardberechtigungen und den entsprechenden Ansprüchen:

Berechtigung	Ansprüche
openid	sub
profile	name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
email	email, email_verified
phone	phone_number, phone_number_verified
address	address

Wenn deine Anwendung beispielsweise die Berechtigungen openid profile email anfordert, enthält der ID-Token alle Ansprüche aus den Berechtigungen openid, profile und email.

Erweiterte Ansprüche

Über die Standard-OIDC-Ansprüche hinaus erweitert Logto zusätzliche Ansprüche, die identitätsspezifische Informationen für das Logto-Ökosystem enthalten. Diese erweiterten Ansprüche folgen einem Dual-Bedingungsmodell, um im ID-Token enthalten zu sein:

1. Berechtigungsbedingung: Die Anwendung muss während der Authentifizierung die entsprechende Berechtigung anfordern.
2. Konsolen-Umschalter: Der Administrator muss die Aufnahme des Anspruchs in den ID-Token über die Logto-Konsole aktivieren.

Beide Bedingungen müssen gleichzeitig erfüllt sein. Die Berechtigung dient als Zugriffsdeklaration auf Protokollebene, während der Umschalter als Sichtbarkeitskontrolle auf Produktebene fungiert — ihre Verantwortlichkeiten sind klar und nicht austauschbar.

Verfügbare erweiterte Berechtigungen und Ansprüche

Berechtigung	Ansprüche	Beschreibung	Standardmäßig enthalten
custom_data	custom_data	Benutzerdefinierte Daten am Benutzerobjekt
identities	identities, sso_identities	Verknüpfte soziale und SSO-Identitäten des Benutzers
roles	roles	Zugewiesene Rollen des Benutzers	✅
urn:logto:scope:organizations	organizations	Organisations-IDs des Benutzers	✅
urn:logto:scope:organizations	organization_data	Organisationsdaten des Benutzers
urn:logto:scope:organization_roles	organization_roles	Organisationsrollen-Zuweisungen des Benutzers	✅

Konfiguration in der Logto-Konsole

Um erweiterte Ansprüche im ID-Token zu aktivieren:

1. Navigiere zu Konsole > Benutzerdefiniertes JWT.
2. Aktiviere die Umschalter für die Ansprüche, die du im ID-Token aufnehmen möchtest.
3. Stelle sicher, dass deine Anwendung während der Authentifizierung die entsprechenden Berechtigungen anfordert.

Verwandte Ressourcen

Benutzerdefiniertes Zugangstoken

OpenID Connect Core – ID-Token