Referenz zu Ansprüchen in Zugriffstoken

Die Zugriffstoken sind JSON-Webtoken (JWT). JWTs enthalten die folgenden Teile:

  • Header: Enthält Informationen dazu, wie Sie das Token überprüfen können. Dazu zählen auch Informationen zum Typ des Tokens und zu seiner Signierungsmethode.
  • Nutzlast: Enthält alle wichtigen Daten über den Benutzer oder die Anwendung, der bzw. die den Dienst aufzurufen versucht.
  • Signatur: Dies ist das Rohmaterial, das zum Überprüfen des Tokens verwendet wird.

Jedes Teil ist durch einen Punkt (.) getrennt und wird separat Base64-codiert.

Ansprüche sind nur enthalten, wenn ein Wert zum Füllen des Anspruchs vorhanden ist. Eine Anwendung sollte nicht vom Vorhandensein eines Anspruchs abhängig sein. Beispiele hierfür sind pwd_exp (nicht jeder Mandant erfordert das Ablaufen von Kennwörtern) und family_name (Flows für Clientanmeldeinformationen erfolgen im Auftrag von Anwendungen, die keine Namen haben). Das Zugriffstoken enthält immer ausreichende Ansprüche für die Zugriffsauswertung.

Einige Ansprüche werden verwendet, damit sich Microsoft Identity Platform Token zur Wiederverwendung sichern kann. Die Beschreibung als Opaque gibt an, dass diese Ansprüche nicht für die öffentliche Nutzung vorgesehen sind. Solche Ansprüche können eventuell in einem Token enthalten sein, und neue Ansprüche können ohne vorherige Ankündigung hinzugefügt werden.

Headeransprüche

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

Nutzlastansprüche

Anspruch Format BESCHREIBUNG Überlegungen zur Autorisierung
acrs JSON-Array von Zeichenfolgen Gibt die Authentifizierungskontext-IDs der Vorgänge an, zu deren Ausführung der Bearer berechtigt ist. Authentifizierungskontext-IDs können verwendet werden, um eine Anforderung für eine Step-up-Authentifizierung aus Ihrer Anwendung und Ihren Diensten auszulösen. Wird häufig zusammen mit dem xms_cc-Anspruch verwendet.
aud Zeichenfolge, ein Anwendungs-ID-URI oder eine GUID Gibt das Zielpublikum für das Token an. In v2.0-Token entspricht dieser Wert immer der Client-ID der API. In v1.0-Token kann es sich dabei um die Client-ID oder den in der Anforderung verwendeten Ressourcen-URI handeln. Der Wert kann davon abhängen, wie der Client das Token angefordert hat. Dieser Wert muss überprüft werden, und das Token muss abgelehnt werden, wenn der Wert nicht der gewünschten Zielgruppe entspricht.
iss Zeichenfolge, URI eines Sicherheitstokendiensts (STS) Gibt den STS an, der das Token und den Microsoft Entra-Mandanten authentifizierter Benutzer*innen erstellt und zurückgibt. Wenn das ausgegebene Token ein v2.0-Token ist (siehe Anspruch ver), endet der URI auf /v2.0. Die GUID, die angibt, dass der Benutzer ein Consumer-Benutzer eines Microsoft-Kontos ist, lautet 9188040d-6c67-4c5b-b112-36a304b66dad. Die Anwendung kann den GUID-Teil des Anspruchs verwenden, um die Mandanten einzuschränken, die sich bei der Anmeldung anmelden können (sofern zutreffend).
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 befindet sich nicht im se Mandanten wie der Aussteller (z. B. Gäste). Verwenden Sie den Wert von iss, wenn der Anspruch nicht vorhanden ist. Für persönliche Konten, die in einem Organisationskontext verwendet werden (etwa ein persönliches Konto, zu dem ein Microsoft Entra-Mandant eingeladen wurde), kann der idp-Anspruch „live.com“ oder ein STS-URI sein, der den Microsoft-Kontomandanten 9188040d-6c67-4c5b-b112-36a304b66dad enthält.
iat Integer, ein UNIX-Zeitstempel Gibt an, wann die Authentifizierung für dieses Token erfolgt ist.
nbf Integer, ein UNIX-Zeitstempel Gibt die Zeit an, nach der das JWT verarbeitet werden kann.
exp Integer, ein UNIX-Zeitstempel Gibt die Ablaufzeit an, vor der das JWT nicht für die Bearbeitung akzeptiert werden kann. Eine Ressource kann das Token vor diesem Zeitpunkt ebenfalls ablehnen. Die Ablehnung kann bei einer erforderlichen Änderung der Authentifizierung oder beim Widerrufen eines Tokens auftreten.
aio Nicht transparente Zeichenfolge Dabei handelt es sich um einen internen Anspruch, der von Microsoft Entra ID verwendet wird, um Daten für die Wiederverwendung von Token aufzuzeichnen. Ressourcen sollten diesen Anspruch nicht verwenden.
acr Zeichenfolge, eine 0 oder 1, nur in v1.0-Token vorhanden Der Wert 0 für den Anspruch „Authentifizierungskontextklasse“ gibt an, dass die Endbenutzerauthentifizierung nicht den Anforderungen von ISO/IEC 29115 entsprach.
amr JSON-Array von Zeichenfolgen, nur in v1.0-Token vorhanden Gibt die Authentifizierungsmethode des Betreffs des Tokens an.
appid Zeichenfolge, eine GUID, nur in v1.0-Token vorhanden Die Anwendungs-ID des Clients, der das Token verwendet. Die Anwendung kann als sie selbst oder im Auftrag eines Benutzers agieren. Die Anwendungs-ID stellt in der Regel ein Anwendungsobjekt dar, kann jedoch auch ein Dienstprinzipalobjekt in Microsoft Entra ID darstellen. appid kann bei Autorisierungsentscheidungen verwendet werden.
azp Zeichenfolge, eine GUID, nur in v2.0-Token vorhanden Ein Ersatz für appid. Die Anwendungs-ID des Clients, der das Token verwendet. Die Anwendung kann als sie selbst oder im Auftrag eines Benutzers agieren. Die Anwendungs-ID stellt in der Regel ein Anwendungsobjekt dar, kann jedoch auch ein Dienstprinzipalobjekt in Microsoft Entra ID darstellen. azp kann bei Autorisierungsentscheidungen verwendet werden.
appidacr Zeichenfolge, eine 0, 1 oder 2, nur in v1.0-Token vorhanden Gibt die Authentifizierungsmethode des Clients an. Bei einem öffentlichen Client ist der Wert 0. Wenn Sie die Client-ID und den geheimen Clientschlüssel verwenden, ist der Wert 1. Wenn Sie ein Clientzertifikat für die Authentifizierung verwenden, lautet der Wert 2.
azpacr Zeichenfolge, eine 0, 1 oder 2, nur in v2.0-Token vorhanden Ein Ersatz für appidacr. Gibt die Authentifizierungsmethode des Clients an. Bei einem öffentlichen Client ist der Wert 0. Wenn Sie die Client-ID und den geheimen Clientschlüssel verwenden, ist der Wert 1. Wenn Sie ein Clientzertifikat für die Authentifizierung verwenden, lautet der Wert 2.
preferred_username Zeichenfolge, nur in v2.0-Token vorhanden Der primäre Benutzername, der den Benutzer darstellt. Bei dem Wert kann es sich um eine E-Mail-Adresse, eine Telefonnummer oder einen generischen Benutzernamen ohne bestimmtes Format handeln. Verwenden Sie den Wert für Hinweise auf den Benutzernamen und als Benutzername auf der Benutzeroberfläche. Um diesen Anspruch zu empfangen, verwenden Sie den Umfang profile. Da dieser Wert veränderlich ist, darf er nicht verwendet werden, um Autorisierungsentscheidungen zu treffen.
name String Ein lesbarer Wert, der den Antragsteller des Tokens angibt. Der Wert kann variieren, er ist veränderlich und dient nur zu Anzeigezwecken. Um diesen Anspruch zu empfangen, verwenden Sie den Umfang profile. Verwenden Sie diesen Wert nicht, um Autorisierungsentscheidungen zu treffen.
scp Zeichenfolge, eine durch Leerzeichen getrennte Liste von Bereichen Die von der Anwendung verfügbar gemachte Gruppe von Bereichen, für die die Clientanwendung eine Einwilligung angefordert (und empfangen) hat. Wird nur für Benutzertoken verwendet. Die Anwendung sollte überprüfen, ob diese Bereiche gültige, von der Anwendung verfügbar gemachte Bereiche sind, und Autorisierungsentscheidungen basierend auf dem Wert der Bereiche treffen.
roles Array von Zeichenfolgen, eine Liste der Berechtigungen Die von der Anwendung verfügbar gemachte Gruppe von Berechtigungen, für die der anfordernden Anwendung bzw. dem anfordernden Benutzer die Berechtigung zum Aufrufen gewährt wurde. Der Flow für Clientanmeldeinformationen verwendet diese Gruppe von Berechtigungen anstelle von Benutzerbereichen für Anwendungstoken. Bei Benutzertoken enthält diese Gruppe von Werten die Rollen, die dem Benutzer für die Zielanwendung zugewiesen wurden. Diese Werte können zum Verwalten des Zugriffs verwendet werden, zum Beispiel zum Erzwingen der Autorisierung für den Zugriff auf eine Ressource.
wids Array von RoleTemplateID-GUIDs Dieser Anspruch gibt die mandantenweiten Rollen an, die diesem oder dieser Benutzer*in im Artikel Integrierte Rollen in Microsoft Entra aus dem Rollenbereich zugewiesen wurden. Die groupMembershipClaims-Eigenschaft des Anwendungsmanifests konfigurieren diesen Anspruch anwendungsspezifisch. Legen Sie den Anspruch auf All oder DirectoryRole fest. Ist in Token, die über den impliziten Flow abgerufen wurden, aufgrund von Beschränkungen der Tokenlänge u. U. nicht enthalten. Diese Werte können zum Verwalten des Zugriffs verwendet werden, zum Beispiel zum Erzwingen der Autorisierung für den Zugriff auf eine Ressource.
groups JSON-Array von GUIDs Enthält die Objekt-IDs, die die Gruppenmitgliedschaften des Antragstellers darstellen. Die groupMembershipClaims-Eigenschaft des Anwendungsmanifests konfiguriert den Gruppenanspruch anwendungsspezifisch. Mit dem Wert null werden alle Gruppen ausgeschlossen. Beim Wert SecurityGroup sind nur Mitglieder von Active Directory-Sicherheitsgruppen enthalten. Beim Wert All sind sowohl Sicherheitsgruppen als auch Microsoft 365-Verteilerlisten enthalten.

Informationen zur Verwendung des Anspruchs groups mit impliziter Gewährung finden Sie unter Anspruch hasgroups. Wenn bei anderen Flows die Anzahl der Gruppen, denen Benutzer*innen angehören, über 150 für SAML bzw. 200 für JWT liegt, fügt Microsoft Entra ID den Anspruchsquellen einen Überschreitungsanspruch hinzu. Die Anspruchsquellen verweisen auf den Microsoft Graph-Endpunkt, der die Liste der Gruppen für den Benutzer enthält.
Diese Werte können zum Verwalten des Zugriffs verwendet werden, zum Beispiel zum Erzwingen der Autorisierung für den Zugriff auf eine Ressource.
hasgroups Boolean Sofern vorhanden, ist dieser Wert immer true und gibt an, ob der Benutzer mindestens einer Gruppe angehört. Wird anstelle des Anspruchs groups 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 hinaus (derzeit sechs oder mehr Gruppen) erweitert. Gibt an, dass der Client die Gruppen (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) des Benutzers über die Microsoft Graph-API bestimmen soll.
groups:src1 JSON-Objekt Enthält einen Link zur vollständigen Gruppenliste für den Benutzer, wenn Tokenanforderungen zu groß für das Token sind. 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" }
sub String Der dem Token zugeordnete Prinzipal. Beispielsweise der Benutzer einer Anwendung. Dieser Wert ist unveränderlich und sollte nicht neu zugewiesen oder wiederverwendet werden. Der Antragsteller ist ein paarweiser Bezeichner, der nur für eine bestimmte Anwendungs-ID gilt. Wenn sich ein Benutzer bei zwei verschiedenen Anwendungen mit zwei verschiedenen Client-IDs anmeldet, erhalten diese Anwendungen zwei unterschiedliche Werte für den Antragstelleranspruch. Die Verwendung der beiden unterschiedlichen Werte hängt von Architektur- und Datenschutzanforderungen ab. Siehe auch den Anspruch oid, der innerhalb eines Mandanten für alle Anwendungen immer gleich bleibt. Dieser Wert kann für die Durchführung von Autorisierungsüberprüfungen verwendet werden, z. B. wenn das Token verwendet wird, um auf eine Ressource zuzugreifen. Er kann auch als Schlüssel in Datenbanktabellen verwendet werden.
oid Zeichenfolge, eine GUID Der unveränderliche Bezeichner für den Anforderer, d. h. die überprüfte Identität des Benutzers oder Dienstprinzipals. Mit dieser ID wird der Anforderer anwendungsübergreifend eindeutig identifiziert. Zwei verschiedene Anwendungen, die den gleichen Benutzer anmelden, erhalten den gleichen Wert in Anspruch oid. Dies bedeutet, dass oid beim Senden von Abfragen an Microsoft-Onlinedienste wie Microsoft Graph verwendet werden kann. Microsoft Graph gibt diese ID als id-Eigenschaft für ein bestimmtes Benutzerkonto zurück. Weil es oid mehreren Anwendungen erlaubt, Prinzipale zu korrelieren, verwenden Sie den Umfang profile, um diesen Anspruch für Benutzer zu erhalten. Wenn ein einzelner Benutzer in mehreren Mandanten vorhanden ist, enthält der Benutzer in jedem Mandanten eine andere Objekt-ID. Auch wenn sich der Benutzer bei jedem Konto mit den gleichen Anmeldeinformationen anmeldet, sind die Konten unterschiedlich. Dieser Wert kann für die Durchführung von Autorisierungsüberprüfungen verwendet werden, z. B. wenn das Token verwendet wird, um auf eine Ressource zuzugreifen. Er kann auch als Schlüssel in Datenbanktabellen verwendet werden.
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. Um diesen Anspruch zu erhalten, muss die Anwendung den Bereich profile anfordern. Dieser Wert sollte in Kombination mit anderen Ansprüchen bei Autorisierungsentscheidungen berücksichtigt werden.
unique_name Zeichenfolge, nur in v1.0-Token vorhanden Ein lesbarer Wert, der Aufschluss über den Antragsteller des Tokens gibt. Dieser Wert kann innerhalb eines Mandanten unterschiedlich sein und sollte nur zu Anzeigezwecken verwendet werden.
uti String Tokenbezeichneranspruch, entspricht jti in der JWT-Spezifikation. Eindeutiger, tokenspezifischer Bezeichner, bei dem die Groß-/Kleinschreibung beachtet wird.
rh Nicht transparente Zeichenfolge Ein interner Anspruch, der von Azure zum erneuten Überprüfen von Token verwendet wird. Ressourcen sollten diesen Anspruch nicht verwenden.
ver Zeichenfolge, 1.0 oder 2.0 Gibt die Version des Zugriffstokens an.
xms_cc JSON-Array von Zeichenfolgen Gibt an, ob die Clientanwendung, die das Token erworben hat, In der Lage ist, Anspruchsaufforderungen zu verarbeiten. Dies wird häufig zusammen mit dem acrs-Anspruch verwendet. Dieser Anspruch wird häufig in Szenarien mit bedingtem Zugriff und fortlaufender Zugriffsevaluierung verwendet. Der Ressourcenserver oder die Dienstanwendung, für den/die das Token ausgestellt wurde, steuert das Vorhandensein dieses Anspruchs in einem Token. Ein Wert von cp1 im Zugriffstoken ist die autoritative Methode, um festzustellen, ob eine Clientanwendung eine Anspruchsaufforderung behandeln kann. Weitere Informationen finden Sie unter Anspruchsaufforderungen, Anspruchsanforderungen und Clientfunktionen.

Gruppenüberschreitungsanspruch

Microsoft Entra ID beschränkt die Anzahl der Objekt-IDs, die in den Gruppenanspruch einbezogen werden, um das Größenlimit des HTTP-Headers nicht zu überschreiten. Wenn Benutzer*innen Mitglied in mehr Gruppen sind, als es das Überschreitungslimit (150 für SAML-Token, 200 für JWT-Token und nur 6 bei Ausstellung über den impliziten Flow) zulässt, gibt Microsoft Entra ID den Gruppenanspruch im Token nicht aus. 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]"
        }   
    }
    ...
}

Verwenden Sie die im Ordner App-Erstellungsskripts verfügbare Datei BulkCreateGroups.ps1, um Überschreitungsszenarien zu testen.

Hinweis

Die zurückgegebene URL ist eine Azure AD Graph-URL (d. h. graph.windows.net). Anstatt auf diese URL zu vertrauen, sollten Dienste stattdessen den idtyp optionalen Anspruch verwenden (der angibt, ob es sich bei dem Token um eine App oder ein App+Benutzertoken handelt), um eine Microsoft Graph-URL zum Abfragen der vollständigen Liste von Gruppen zu erstellen.

Grundlegende v1.0-Ansprüche

Die v1.0-Token enthalten ggf. die folgenden Ansprüche, standardmäßig jedoch keine v2.0-Token. Zur Verwendung dieser Ansprüche für v2.0 fordert die Anwendung diese mithilfe optionaler Ansprüche an.

Anspruch Format BESCHREIBUNG
ipaddr String Die IP-Adresse, mit der sich der Benutzer authentifiziert hat.
onprem_sid Zeichenfolge, im SID-Format In Fällen, in denen der Benutzer über eine lokale Authentifizierung verfügt, gibt dieser Anspruch die SID an. Verwenden Sie diesen Anspruch für die Autorisierung in älteren Anwendungen.
pwd_exp Integer, ein UNIX-Zeitstempel Gibt an, wann das Kennwort des Benutzers abläuft.
pwd_url String Eine URL, an die Benutzer zum Zurücksetzen ihres Kennworts weitergeleitet werden können.
in_corp boolean Signalisiert, ob sich der Client über das Unternehmensnetzwerk anmeldet.
nickname String Anderer Name für den Benutzer, der vom Vor- oder Nachnamen abweicht.
family_name String Gibt den Nachnamen des Benutzers entsprechend der Definition im Benutzerobjekt an.
given_name String Gibt den Vornamen des Benutzers entsprechend der Definition im Benutzerobjekt an.
upn String Der Benutzername des Benutzers. Hierbei kann es sich um eine Telefonnummer, E-Mail-Adresse oder unformatierte Zeichenfolge handeln. Wird nur zu Anzeigezwecken und zum Bereitstellen von Hinweisen zum Benutzernamen in Szenarien mit erneuter Authentifizierung verwendet.

Anspruch „amr“

Identitäten können auf verschiedene Arten authentifiziert werden, die möglicherweise für die Anwendung relevant sind. Der amr-Anspruch ist ein Array, das mehrere Elemente (beispielsweise ["mfa", "rsa", "pwd"]) für eine Authentifizierung enthalten kann, bei der sowohl ein Kennwort als auch die Authenticator-App verwendet wurden.

Wert BESCHREIBUNG
pwd Kennwortauthentifizierung – entweder das Microsoft-Kennwort eines Benutzers oder der geheime Clientschlüssel einer Anwendung.
rsa Die Authentifizierung erfolgt basierend auf der Prüfung eines RSA-Schlüssels, beispielsweise mit der Microsoft Authenticator-App. Dieser Wert gibt zudem die Verwendung eines selbst signierten JWT mit einem im Besitz eines Diensts befindlichen X509-Zertifikat an.
otp Einmalkennung mit einer E-Mail oder SMS.
fed Gibt die Verwendung einer Verbundauthentifizierungsassertion an (z. B. JWT oder SAML).
wia Integrierte Windows-Authentifizierung
mfa Gibt die Verwendung der Multi-Faktor-Authentifizierung an. Schließt andere Authentifizierungsmethoden ein, wenn dieser Anspruch vorhanden ist.
ngcmfa Entspricht mfa und wird zum Bereitstellen bestimmter erweiterter Anmeldeinformationstypen verwendet.
wiaormfa Der Benutzer hat sich mit Windows oder MFA-Anmeldeinformationen authentifiziert.
none Gibt keine abgeschlossene Authentifizierung an.

Nächste Schritte