Referenz der ID-Tokenansprüche

Artikel
10/25/2023

Die ID-Token sind JSON-Webtoken (JWT). Die ID-Token v1.0 und v2.0 tragen unterschiedliche Informationen. Die Version basiert auf dem Endpunkt, von dem aus die Anforderung erfolgt ist. Obwohl vorhandene Anwendungen wahrscheinlich den Azure AD-Endpunkt v1.0 verwenden, sollten den neuen v2.0-Endpunkt verwenden.

v1.0: https://login.microsoftonline.com/common/oauth2/authorize
v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Alle in den folgenden Abschnitten aufgeführten JWT-Ansprüche werden in v1.0- und v2.0-Token angezeigt, sofern nicht anders angegeben. ID-Token bestehen aus einem Header, einer Nutzlast und einer Signatur. Der Header und die Signatur werden verwendet, um die Authentizität des Tokens zu überprüfen, während die Nutzlast die Informationen über den von Ihrem Client angeforderten Benutzer enthält.

Headeransprüche

Die folgende Tabelle zeigt die Header-Ansprüche, die in den ID-Token vorhanden sind.

Anspruch	Format	BESCHREIBUNG
`typ`	Zeichenfolge – immer „JWT“	Gibt an, dass das Token ein JWT-Token ist.
`alg`	String	Gibt den Algorithmus an, mit dem das Token signiert wurde. Zum Beispiel: „RS256“
`kid`	String	Gibt den Fingerabdruck für den öffentlichen Schlüssel an, mit dem die Signatur des Tokens überprüft werden kann. Wird in v1.0- und v2.0-ID-Token ausgegeben.
`x5t`	String	Hat dieselbe Funktion (hinsichtlich Verwendung und Wert) wie `kid`. `x5t` ist ein Legacyanspruch, der aus Kompatibilitätsgründen nur in v1.0-ID-Token ausgegeben wird.

Nutzlastansprüche

Die folgende Tabelle zeigt die Ansprüche, die (sofern nichts anderes angegeben ist) in den meisten ID-Token standardmäßig enthalten sind. Allerdings kann Ihre App dieoptionalen Ansprüche verwenden, um zusätzliche Ansprüche in dem ID-Token anzufordern. Optionale Ansprüche können von dem groups Anspruch bis zu den Informationen des Benutzernamens reichen.

Anspruch	Format	Beschreibung
`aud`	Die Zeichenfolge einer App-ID-GUID	Identifiziert den vorgesehenen Empfänger des Tokens. In `id_tokens` ist die Zielgruppe die Anwendungs-ID Ihrer App, die Ihrer App im Azure-Portal zugewiesen ist. Dieser Wert sollte überprüft werden. Das Token sollte abgelehnt werden, wenn es nicht mit der Anwendungs-ID Ihrer App übereinstimmt.
`iss`	Die Zeichenfolge einer Aussteller-URI	Sie identifiziert den Aussteller oder den „Autorisierungsserver“, der das Token erstellt und zurückgibt. Sie identifiziert auch den Mandanten, für den der Benutzer authentifiziert wurde. Wenn das Token vom v2.0-Endpunkt ausgegeben wurde, endet der URI mit `/v2.0`. Die GUID, die angibt, dass der Benutzer ein Consumer-Benutzer eines Microsoft-Kontos ist, lautet `9188040d-6c67-4c5b-b112-36a304b66dad`. Ihre App sollte ggf. den GUID-Teil des Anspruchs verwenden, um die Mandanten einzuschränken, die sich bei der App anmelden können.
`iat`	int, ein UNIX-Zeitstempel	Gibt an, wann die Authentifizierung für den Token erfolgt ist.
`idp`	Zeichenfolge, in der Regel ein STS-URI	Der Identitätsanbieter, der den Antragsteller des Tokens authentifiziert hat. Dieser Wert ist identisch mit dem Wert des Ausstelleranspruchs, es sei denn, das Benutzerkonto ist nicht im gleichen Mandanten wie der Aussteller vorhanden (etwa Gäste). Wenn der Anspruch nicht vorhanden ist, bedeutet dies, dass stattdessen der Wert `iss` verwendet werden kann. Für in einem Organisationskontext verwendete persönliche Konten (etwa ein zu einem Mandanten eingeladenes persönliches Konto) kann der `idp`-Anspruch „live.com“ oder ein STS-URI sein, der den Microsoft-Kontomandanten `9188040d-6c67-4c5b-b112-36a304b66dad` enthält.
`nbf`	Integer, ein UNIX-Zeitstempel	Gibt die Zeit an, vor der das JWT nicht für die Bearbeitung akzeptiert werden darf.
`exp`	Integer, ein UNIX-Zeitstempel	Gibt den Ablaufzeitpunkt an, zu bzw. nach dem das JWT nicht für die Bearbeitung akzeptiert werden kann. Unter bestimmten Umständen kann eine Ressource das Token vor diesem Zeitpunkt ablehnen. Das kann zum Beispiel geschehen, wenn eine Änderung der Authentifizierung erforderlich ist oder ein Tokenwiderruf erkannt wurde.
`c_hash`	String	Der Codehash ist nur dann in ID-Token enthalten, wenn das ID-Token zusammen mit einem OAuth 2.0-Autorisierungscode ausgestellt wird. Mit seiner Hilfe kann die Authentizität eines Autorisierungscodes überprüft werden. Um zu verstehen, wie diese Überprüfung durchgeführt wird, finden Sie Informationen in der OpenID Connect-Spezifikation. Dieser Anspruch wird bei ID-Tokens vom /token-Endpunkt nicht zurückgegeben.
`at_hash`	String	Der Zugriffstokenhash ist nur in ID-Token enthalten, wenn das ID-Token vom `/authorize`-Endpunkt zusammen mit einem OAuth 2.0-Zugriffstoken ausgestellt wird. Mit seiner Hilfe kann die Authentizität eines Zugriffstokens überprüft werden. Um zu verstehen, wie diese Überprüfung durchgeführt wird, finden Sie Informationen in der OpenID Connect-Spezifikation. Dieser Anspruch wird für ID-Token vom `/token`-Endpunkt nicht zurückgegeben.
`aio`	Nicht transparente Zeichenfolge	Ein interner Anspruch, der verwendet wird, um Daten für die Wiederverwendung von Token aufzuzeichnen. Sollte ignoriert werden.
`preferred_username`	String	Der primäre Benutzername, der den Benutzer darstellt. Dabei kann es sich um eine E-Mail-Adresse, eine Telefonnummer oder einen generischen Benutzernamen ohne bestimmtes Format handeln. Der Wert kann geändert werden und sich im Laufe der Zeit ändern. Da er geändert werden kann, kann dieser Wert nicht verwendet werden, um Autorisierungsentscheidungen zu treffen. Er kann aber für Hinweise auf den Benutzernamen und auf der Benutzeroberfläche als Benutzername verwendet werden. Der Bereich `profile` ist erforderlich, um diesen Anspruch zu empfangen. Er ist nur in v2.0-Token vorhanden.
`email`	String	Standardmäßig für Gastkonten vorhanden, die über eine E-Mail-Adresse verfügen. Ihre App kann den E-Mail-Anspruch für verwaltete Benutzer (unter demselben Mandanten wie die Ressource) über den `email`optionalen Anspruch anfordern. Dieser Wert ist nicht zwangsläufig korrekt und kann sich im Laufe der Zeit ändern. Verwenden Sie ihn niemals zur Autorisierung oder zum Speichern von Daten für Benutzer. Wenn Sie eine adressierbare E-Mail-Adresse in Ihrer App benötigen, fordern Sie diese Daten direkt vom Benutzer an, indem Sie diesen Anspruch als Vorschlag verwenden oder vorab in Ihre Benutzeroberfläche einfügen. Auf dem v2.0-Endpunkt kann Ihre App auch den OpenID Connect-Bereich `email` anfordern. Sie müssen nicht sowohl den optionalen Anspruch als auch den Bereich abrufen, um den Anspruch zu erhalten.
`name`	String	Der `name`-Anspruch gibt einen visuell lesbaren Wert an, der den Antragsteller des Tokens identifiziert. Der Wert ist nicht zwingend eindeutig, er kann aber geändert werden und dient nur zu Anzeigezwecken. Der Bereich `profile` ist erforderlich, um diesen Anspruch zu empfangen.
`nonce`	String	Die Nonce stimmt mit dem Parameter überein, der in der ursprünglichen authorize-Anforderung an den IDP enthalten ist. Wenn diese Angaben nicht übereinstimmen, sollte Ihre Anwendung das Token ablehnen.
`oid`	Zeichenfolge, eine GUID	Der unveränderliche Bezeichner für ein Objekt, in diesem Fall ein Benutzerkonto. Diese ID identifiziert den Benutzer anwendungsübergreifend eindeutig: Zwei verschiedene Anwendungen, die den gleichen Benutzer anmelden, erhalten den gleichen Wert im `oid`-Anspruch. Microsoft Graph gibt diese ID als `id`-Eigenschaft für ein Benutzerkonto zurück. Da mit `oid` mehrere Apps Benutzer korrelieren können, ist der `profile`-Bereich erforderlich, um diesen Anspruch zu erhalten. Wenn ein einzelner Benutzer in mehreren Mandanten vorhanden ist, enthält der Benutzer in jedem Mandanten eine andere Objekt-ID. Sie werden als unterschiedliche Konten betrachtet, obwohl sich der Benutzer bei jedem Konto mit den gleichen Anmeldeinformationen anmeldet. Der `oid`-Anspruch ist eine GUID und kann nicht wiederverwendet werden.
`roles`	Array von Zeichenfolgen	Die Rollen, die dem sich anmeldenden Benutzer zugewiesen wurden.
`rh`	Nicht transparente Zeichenfolge	Ein interner Anspruch, der zum erneuten Überprüfen von Token verwendet wird. Sollte ignoriert werden.
`sub`	String	Der Betreff der Informationen im Token. Beispielsweise der Benutzer einer Anwendung. Dieser Wert ist unveränderlich und kann nicht erneut zugewiesen oder wiederverwendet werden. Der Antragsteller ist ein paarweiser Bezeichner und er gilt für eine bestimmte Anwendungs-ID. Wenn sich ein Benutzer bei zwei verschiedenen Apps mit zwei verschiedenen Client-IDs anmeldet, erhalten diese Apps zwei unterschiedliche Werte für den Antragstelleranspruch. Sie können – abhängig von den Architektur- und Datenschutzanforderungen – zwei Werte haben oder nicht.
`tid`	Zeichenfolge, eine GUID	Stellt den Mandanten dar, bei dem sich der Benutzer anmeldet. Bei Geschäfts-, Schul- oder Unikonten ist die GUID die unveränderliche Mandanten-ID der Organisation, bei der sich der Benutzer anmeldet. Für Anmeldungen beim persönlichen Microsoft-Kontomandanten (Dienste wie Xbox, Teams for Life oder Outlook) ist der Wert `9188040d-6c67-4c5b-b112-36a304b66dad`.
`unique_name`	String	Ist nur in v1.0-Token vorhanden. Ein lesbarer Wert, der Aufschluss über den Antragsteller des Tokens gibt. Dieser Wert ist innerhalb eines Mandanten nicht zwingend eindeutig. Er sollte daher nur zu Anzeigezwecken verwendet werden.
`uti`	String	Tokenbezeichneranspruch, entspricht `jti` in der JWT-Spezifikation. Eindeutiger, tokenspezifischer Bezeichner, bei dem die Groß-/Kleinschreibung beachtet wird.
`ver`	Zeichenfolge, 1.0 oder 2.0	Gibt die Version des ID-Tokens an.
`hasgroups`	Boolean	Ist immer auf TRUE festgelegt (sofern vorhanden) und gibt an, dass der Benutzer mindestens einer Gruppe angehört. Wird anstelle des Gruppenanspruchs für JWTs in Flows mit impliziter Gewährung verwendet, wenn der Anspruch für vollständige Gruppen das URI-Fragment über die URL-Längenbeschränkung (derzeit sechs oder mehr Gruppen) erweitert. Gibt an, dass der Client die Gruppen des Benutzers über die Microsoft Graph-API bestimmen soll (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	JSON-Objekt	Für Tokenanforderungen ohne Längenbeschränkung (siehe `hasgroups`), die aber dennoch zu groß für das Token sind, ist ein Link zur Liste der vollständigen Gruppen für den Benutzer enthalten. Für JWTs als verteilter Anspruch, für SAML als neuer Anspruch anstelle des Anspruchs `groups`. JWT-Beispielwert: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Weitere Informationen finden Sie unter Gruppenüberschreitungsanspruch.

Verwenden von Ansprüchen zum zuverlässigen Identifizieren eines Benutzers

Beim Identifizieren eines Benutzers ist es wichtig, Informationen zu verwenden, die im Zeitverlauf konstant und eindeutig sind. Ältere Anwendungen verwenden manchmal Felder wie die E-Mail-Adresse, eine Telefonnummer oder den UPN. All diese Felder können sich im Laufe der Zeit ändern und sie können auch im Laufe der Zeit wiederverwendet werden. Das kann z. B. vorkommen, wenn ein Mitarbeiter seinen Namen ändert oder wenn ein Mitarbeiter die E-Mail-Adresse eines früheren Mitarbeiters erhält, der nicht mehr im Unternehmen tätig ist. Ihre Anwendung darf keine für Menschen lesbaren Daten verwenden, um Benutzer zu identifizieren. Für Menschen lesbar bedeutet ganz allgemein, dass jemand diese Informationen lesen und ändern könnte. Verwenden Sie stattdessen die Ansprüche, die vom OIDC-Standard bereitgestellt werden, oder die von Microsoft bereitgestellten Erweiterungsansprüche sub und oid.

Verwenden Sie zum ordnungsgemäßen Speichern von Informationen pro Benutzer nur sub oder oid (die als GUIDs eindeutig sind) und bei Bedarf tid für das Routing oder Sharding. Wenn Sie Daten dienstübergreifend freigeben müssen, eignet sich oid und tid am besten, da alle Apps dieselben Ansprüche oid und tid für einen Benutzer erhalten, der in einem Mandanten agiert. Der sub-Anspruch ist ein paarweiser Wert, der eindeutig ist. Der Wert basiert auf einer Kombination des Tokenempfängers, des Mandanten und des Benutzers. Daher erhalten zwei Apps, die ID-Token für einen Benutzer anfordern, unterschiedliche sub-Ansprüche, aber dieselben oid-Ansprüche für diesen Benutzer.

Hinweis

Verwenden Sie den idp-Anspruch nicht zum Speichern von Informationen zu einem Benutzer, um Benutzer über Mandanten hinweg zu korrelieren. Dies funktioniert nicht, da die Ansprüche oid und sub für einen Benutzer in verschiedenen Mandanten unterschiedlich sind. Dies ist so konzipiert, um sicherzustellen, dass Anwendungen Benutzer nicht mandantenübergreifend nachverfolgen können.

Gastszenarien, in denen ein Benutzer einem Mandanten angehört und sich in einem anderen authentifiziert, sollten den Benutzer wie einen neuen Benutzer des Diensts behandeln. Ihre Dokumente und Berechtigungen in einem Mandanten sollten nicht in einem anderen Mandanten gelten. Diese Einschränkung ist wichtig, um versehentliche Datenlecks zwischen Mandanten und die Erzwingung von Datenlebenszyklen zu verhindern. Beim Entfernen eines Gasts aus einem Mandanten sollte auch dessen Zugriff auf die Daten entfernt werden, die er in diesem Mandanten erstellt hat.

Gruppenüberschreitungsanspruch

Um sicherzustellen, dass die Tokengröße die Grenzwerte für HTTP-Header nicht überschreitet, ist die Anzahl der im groups-Anspruch enthaltenen Objekt-IDs eingeschränkt. Wenn ein Benutzer Mitglied mehrerer Gruppen als die zulässige Überschreitungsgrenze (150 für SAML-Token, 200 für JWT-Token) ist, ist der Gruppenanspruch nicht im Token enthalten. Stattdessen ist ein Überschreitungsanspruch im Token enthalten, der der Anwendung anzeigt, dass die Microsoft Graph-API abgefragt werden soll, um die Gruppenmitgliedschaft des Benutzers abzurufen.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

Nächste Schritte

Hier erfahren Sie mehr über ID-Token, die in Microsoft Entra ID verwendet werden.