Referenz zu Ansprüchen in Zugriffstoken

Artikel
11/14/2023

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`. `x5t`ist 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.	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` werden Verzeichnisrollen und nur Mitglieder von Active Directory-Sicherheitsgruppen eingeschlossen. Beim Wert `All` sind sowohl Sicherheitsgruppen als auch Microsoft 365-Verteilerlisten enthalten. 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. 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.

Hinweis

Die Ansprüche roles, groups, scp und wids sind keine vollständige Liste der Möglichkeiten, wie eine Ressource einen Benutzer oder eine Anwendung autorisieren kann, oder eine vollständige Liste der Berechtigungen, die dem Aufrufer gewährt werden. Die Zielressource kann eine andere Methode verwenden, um den Zugriff auf die geschützten Ressourcen zu autorisieren.

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 ein Benutzender Mitglied in mehr Gruppen ist, als es die Überschreitung zulässt (150 für SAML-Tokens, 200 für JWT-Tokens), dann 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

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

Freigeben über