Referenz der ID-Tokenansprüche

  • Artikel

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:innen (unter demselben Mandanten wie die Ressource) über den optionalen Anspruch email 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. 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