Benutzerdefinierter ID-Token

Einführung

ID-Token ist eine spezielle Art von Token, die durch das OpenID Connect (OIDC)-Protokoll definiert ist. Er dient als Identitätsnachweis, der vom Aussteller (Logto) nach erfolgreicher Authentifizierung eines Benutzers ausgegeben wird und Ansprüche über die Identität des authentifizierten Benutzers enthält.

Im Gegensatz zu Zugangstokens, die zum Zugriff auf geschützte Ressourcen verwendet werden, sind ID-Tokens 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 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 Möglichkeit, 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, auth_time, acr, amr (Authentifizierungskontext-Ansprüche werden einbezogen, wenn sie in der Sitzung vorhanden sind; siehe Step-up-Authentifizierung)
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ätsinformationen enthalten, die spezifisch für das Logto-Ökosystem sind. 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 Protokoll-Ebene für die Zugriffsdeklaration, während der Umschalter als Produkt-Ebene für die Sichtbarkeitskontrolle dient — 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 auf dem 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

So aktivierst du erweiterte Ansprüche im ID-Token:

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