Teilen über

Referenz auf optionale Ansprüche

  • Artikel

Sie können optionale Ansprüche zu folgenden Zwecken verwenden:

  • Auswählen von Ansprüchen, die in Token für Ihre Anwendung aufgenommen werden sollen
  • Ändern des Verhaltens bestimmter Ansprüche, die von Microsoft Identity Platform in Token zurückgegeben werden.
  • Hinzufügen und Zugreifen auf benutzerdefinierte Ansprüche für Ihre Anwendung

Optionale Ansprüche werden zwar von Token der Formate v1.0 und v2.0 sowie von SAML-Token unterstützt, aber den größten Wert besitzen sie bei der Umstellung von v1.0 auf v2.0. In der Microsoft Identity Platform werden geringere Tokengrößen verwendet, um die optimale Leistung von Clients zu gewährleisten. Daher sind mehrere Ansprüche, die zuvor in den Zugriffs- und ID-Token enthalten waren, nicht mehr in v2.0-Token vorhanden und müssen für einzelne Anwendungen speziell angefordert werden.

Kontotyp v1.0-Token v2.0-Token
Persönliches Microsoft-Konto – Unterstützt
Microsoft Entra-Konto Unterstützt Unterstützt

Gruppe optionaler Ansprüche in v1.0 und v2.0

Die Gruppe optionaler Ansprüche, die standardmäßig zur Verwendung in Anwendungen bereitstehen, sind in der folgenden Tabelle aufgeführt. Mit benutzerdefinierten Daten in Erweiterungsattributen und Verzeichniserweiterungen können Sie optionale Ansprüche für Ihre Anwendung hinzufügen. Beim Hinzufügen von Ansprüchen zum Zugriffstoken gilt der Anspruch für Zugriffstoken, die für die Anwendung (eine Web-API) und nicht von der Anwendung angefordert werden. Unabhängig vom Client, der auf Ihre API zugreift, sind so die richtigen Daten im Zugriffstoken vorhanden, die zum Authentifizieren bei Ihrer API verwendet werden.

Hinweis

Die Mehrzahl dieser Ansprüche kann in JWTs für v1.0- und v2.0-Token, jedoch nicht in SAML-Token eingeschlossen werden. Ausnahmen stellen die Ansprüche dar, die einen entsprechenden Hinweis in der Spalte „Tokentyp“ enthalten. Consumerkonten unterstützen eine Teilmenge dieser Ansprüche, die in der Spalte als „Benutzertyp“ gekennzeichnet sind. Viele der aufgelisteten Ansprüche gelten nicht für Consumerbenutzende (sie besitzen keinen Mandanten, daher weist tenant_ctry keinen Wert auf).

In der folgenden Tabelle sind die optionalen Anspruchssätze v1.0 und v2.0 aufgeführt.

Name BESCHREIBUNG Tokentyp Benutzertyp Notizen
acct Benutzerkontostatus im Mandanten. JWT, SAML Wenn der Benutzer dem Mandanten angehört, lautet der Wert 0. Bei einem Gastbenutzer lautet der Wert 1.
acrs Authentifizierungskontext-IDs JWT Microsoft Entra ID 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.
auth_time Zeitpunkt der letzten Authentifizierung des Benutzers. JWT
ctry Land/Region des Benutzers JWT Der Anspruch wird zurückgegeben, wenn er vorhanden ist und der Wert des Felds ein standardmäßiger aus zwei Buchstaben bestehender Länder-/Regionscode (wie z. B. FR, JP oder SZ usw.) ist.
email Die gemeldete E-Mail-Adresse für diesen Benutzer JWT, SAML MSA, Microsoft Entra ID Dieser Wert ist standardmäßig enthalten, wenn der Benutzer ein Gast im Mandanten ist. Für verwaltete Benutzer (Benutzer innerhalb des Mandanten) muss er über diese optionale Anforderung oder – nur in v2.0 – mit dem OpenID-Bereich angefordert werden. Dieser Wert ist nicht garantiert korrekt und kann im Laufe der Zeit veränderlich sein. Verwenden Sie ihn niemals zur Autorisierung oder zum Speichern von Daten für einen Benutzer. Weitere Informationen finden Sie unter Überprüfen, ob der Benutzer über Berechtigungen für den Zugriff auf diese Daten verfügt. Wenn Sie den E-Mail-Anspruch für die Autorisierung verwenden, empfehlen wir, eine Migration durchzuführen, um zu einem sichereren Anspruch zu wechseln. Wenn Sie in Ihrer App eine adressierbare E-Mail-Adresse benötigen, fordern Sie diese Daten direkt vom Benutzer an, und nutzen Sie diese Angabe als Vorschlag oder Vorauswahl in Ihrer UX.
fwd IP-Adresse JWT Fügt die ursprüngliche Adresse des anfordernden Clients hinzu (wenn in einem VNET).
groups Optionale Formatierung für Gruppenansprüche JWT, SAML Der Anspruch groups wird mit der Einstellung „GroupMembershipClaims“ im Anwendungsmanifest verwendet, das ebenfalls festgelegt sein muss.
idtyp Tokentyp JWT-Zugriffstoken Besonderheit: Nur in Nur-App-Zugriffstoken Der Wert lautet app, wenn es sich beim Token um einen reinen App-Token handelt. Dieser Anspruch ist der genaueste Weg, damit durch eine API bestimmt werden kann, ob ein Token ein App-Token oder ein App- und Benutzertoken ist.
login_hint Anmeldehinweis JWT MSA, Microsoft Entra ID Ein nicht transparenter, zuverlässiger Anmeldehinweis, der Base64-codiert ist. Ändern Sie diesen Wert nicht. Dieser Anspruch eignet sich am besten für die Nutzung als OAuth-Parameter login_hint in allen Flows, um das einmalige Anmelden (SSO) zu ermöglichen. Er kann auch zwischen Anwendungen übergeben werden, um das SSO im Hintergrund zu unterstützen. Anwendung A kann z. B. einen Benutzer anmelden, den login_hint-Anspruch lesen und ihn dann zusammen mit dem aktuellen Mandantenkontext als Abfragezeichenfolge oder als Fragment an Anwendung B senden, wenn der Benutzer einen Link auswählt, der ihn zu Anwendung B führt. Um Racebedingungen und Zuverlässigkeitsprobleme zu vermeiden, enthält der login_hint-Anspruch nicht den aktuellen Mandanten des Benutzers, sondern verwendet standardmäßig den Startmandanten des Benutzers. In einem Gastszenario, in dem der Benutzende von einem anderen Mandanten stammt, muss in der Anmeldeanforderung ein Mandantenbezeichner angegeben werden. und das gleiche an Anwendungen übergeben, mit denen Sie zusammenarbeiten. Dieser Anspruch ist für die Verwendung mit der login_hint-Funktionalität Ihres SDK vorgesehen, wurde jedoch verfügbar gemacht.
sid Sitzungs-ID, die zur sitzungsbezogenen Abmeldung des Benutzenden verwendet wird JWT Persönliche und Microsoft Entra-Konten.
tenant_ctry Land/Region des Ressourcenmandanten JWT Wie ctry, aber auf Mandantenebene von einem Administrator festgelegt. Muss ebenfalls ein Standardwert mit zwei Buchstaben sein.
tenant_region_scope Region des Ressourcenmandanten JWT
upn UserPrincipalName JWT, SAML Ein Bezeichner für den Benutzenden, der mit dem Parameter username_hint verwendet werden kann. Kein dauerhafter Bezeichner für den Benutzer. Sollte nicht zur Autorisierung oder zur eindeutigen Identifizierung von Benutzerinformationen verwendet werden (beispielsweise als Datenbankschlüssel). Verwenden Sie stattdessen die Benutzerobjekt-ID (oid) als Datenbankschlüssel. Weitere Informationen finden Sie unter Sichern von Anwendungen und APIs durch Überprüfen von Ansprüchen. Benutzern, die sich mit einer alternativen Anmelde-ID anmelden, sollte ihr Benutzerprinzipalname (User Principal Name, UPN) nicht angezeigt werden. Verwenden Sie stattdessen die folgenden ID-Tokenansprüche, um den Anmeldezustand für Benutzer anzuzeigen: preferred_username oder unique_name für v1-Token, preferred_username für v2-Token. Obwohl dieser Anspruch automatisch hinzugefügt wird, können Sie ihn als einen optionalen Anspruch angeben, um zusätzliche Eigenschaften zum Ändern des Verhaltens im Fall eines Gastbenutzenden anzufügen. Sie sollten den login_hint-Anspruch für login_hint nutzen, denn lesbare Bezeichner wie UPN sind nicht zuverlässig.
verified_primary_email Wird aus der „PrimaryAuthoritativeEmail“ des Benutzers abgerufen JWT
verified_secondary_email Wird aus der „SecondaryAuthoritativeEmail“ des Benutzers abgerufen JWT
vnet Informationen zum VNET-Spezifizierer JWT
xms_cc Clientfunktionen JWT Microsoft Entra ID 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.
xms_edov Boolescher Wert, der angibt, ob der Besitzer der E-Mail-Domäne der Benutzer*innen überprüft wurde. JWT Die Domäne einer E-Mail gilt als überprüft, wenn die Domäne zu dem Mandanten gehört, in dem sich das Benutzerkonto befindet, und der Mandantenadministrator die Domäne überprüft hat. Außerdem muss die E-Mail von einem Microsoft-Konto (MSA) oder einem Google-Konto stammen oder für die Authentifizierung mithilfe des OTP-Flows (One-Time Passcode) verwendet werden. Facebook- und SAML/WS-Fed-Konten haben keine verifizieten Domänen. Damit dieser Anspruch im Token zurückgegeben werden kann,muss der Anspruch email vorhanden sein.
xms_pdl Bevorzugter Datenspeicherort JWT Für Multi-Geo-Mandanten ist der bevorzugte Datenspeicherort ein aus drei Buchstaben bestehender Code, der die geografische Region anzeigt, in der sich der Benutzer befindet. Weitere Informationen finden Sie unter Microsoft Entra Connect-Dokumentation zum bevorzugten Datenspeicherort.
xms_pl Bevorzugte Benutzersprache JWT Die bevorzugte Sprache des Benutzers, falls festgelegt. Wird in Szenarios mit Gastzugriff aus dem Basismandanten abgerufen. Sie wird im Format Sprachkürzel-Länderkürzel angegeben (z. B. en-us).
xms_tpl Bevorzugte Mandantensprache JWT Die bevorzugte Sprache des Ressourcenmandanten, falls festgelegt. Sie wird in Form des Sprachkürzels angegeben (z. B.: en).
ztdid ID der Bereitstellung ohne manuelles Eingreifen JWT Die Geräteidentität, die für Windows AutoPilotverwendet wird.

Warnung

Verwenden Sie niemals die Anspruchswerte email oder upn, um zu ermitteln oder zu speichern, ob Benutzer*innen in einem Zugriffstoken Zugriff auf Daten haben sollen. Veränderliche Anspruchswerte wie diese können sich im Laufe der Zeit ändern, wodurch sie unsicher und unzuverlässig für die Autorisierung werden.

v2.0-spezifischer optionaler Anspruchssatz

Diese Ansprüche sind in v1.0-Token immer enthalten, jedoch nie in v2.0-Token, sofern nicht angefordert. Diese Ansprüche gelten nur für JWTs (ID-Token und Zugriffstoken).

JWT-Anspruch Name BESCHREIBUNG Notizen
ipaddr IP-Adresse Die IP-Adresse, von der aus sich der Client angemeldet hat.
onprem_sid Lokale Sicherheits-ID
pwd_exp Kennwortablaufzeit Die Anzahl der Sekunden nach dem Zeitpunkt im iat-Anspruch, an dem das Kennwort abläuft. Dieser Anspruch ist nur enthalten, wenn das Kennwort in Kürze abläuft (definiert über „Benachrichtigungstage“ in der Kennwortrichtlinie).
pwd_url Kennwortänderungs-URL Eine URL, die der Benutzer besuchen kann, um sein Kennwort zu ändern. Dieser Anspruch ist nur enthalten, wenn das Kennwort in Kürze abläuft (definiert über „Benachrichtigungstage“ in der Kennwortrichtlinie).
in_corp Innerhalb des Unternehmensnetzwerks Signalisiert, ob sich der Client aus dem Unternehmensnetzwerk anmeldet. Andernfalls ist der Anspruch nicht enthalten. Basierend auf den Einstellungen für vertrauenswürdige IP-Adressen in der MFA.
family_name Last Name (Nachname) Gibt den Nachnamen des Benutzers entsprechend der Definition im Benutzerobjekt an. Beispiel: "family_name":"Miller". Unterstützt in MSA und Microsoft Entra ID. Erfordert den Bereich profile.
given_name Vorname Gibt den Vornamen des Benutzers entsprechend der Definition im Benutzerobjekt an. Beispiel: "given_name": "Frank". Unterstützt in MSA und Microsoft Entra ID. Erfordert den Bereich profile.
upn Benutzerprinzipalname Ein Bezeichner für den Benutzenden, der mit dem Parameter username_hint verwendet werden kann. Kein dauerhafter Bezeichner für den Benutzer. Sollte nicht zur Autorisierung oder zur eindeutigen Identifizierung von Benutzerinformationen verwendet werden (beispielsweise als Datenbankschlüssel). Weitere Informationen finden Sie unter Sichern von Anwendungen und APIs durch Überprüfen von Ansprüchen. Verwenden Sie stattdessen die Benutzerobjekt-ID (oid) als Datenbankschlüssel. Benutzern, die sich mit einer alternativen Anmelde-ID anmelden, sollte ihr Benutzerprinzipalname (User Principal Name, UPN) nicht angezeigt werden. Verwenden Sie stattdessen den folgenden preferred_username-Anspruch, um den Anmeldezustand dem Benutzer anzuzeigen. Erfordert den Bereich profile.

v1.0-spezifische optionale Ansprüche

Einige der Verbesserungen des v2-Tokenformats sind für Apps verfügbar, die das v1-Tokenformat verwenden, da sie eine Optimierung der Sicherheit und Zuverlässigkeit ermöglichen. Diese verbesserungen gelten nur für JWTs, nicht für SAML-Token.

JWT-Anspruch Name BESCHREIBUNG Notizen
aud Zielgruppe Ist in JWTs immer vorhanden, aber in v1-Zugriffstoken kann der Anspruch auf unterschiedliche Weise ausgegeben werden: als appID-URI mit oder ohne nachstehenden Schrägstrich oder als Client-ID der Ressource. Diese Randomisierung lässt sich bei der Tokenüberprüfung im Code nur schwer berücksichtigen. Verwenden Sie für diesen Anspruch additionalProperties, um sicherzustellen, dass er in v1-Zugriffstoken immer auf die Client-ID der Ressource festgelegt ist. Nur v1-JWT-Zugriffstoken
preferred_username Bevorzugter Benutzername Stellt den bevorzugten Benutzernamensanspruch innerhalb von v1-Token bereit. Dieser Anspruch erleichtert es Apps, Hinweise zu Benutzernamen bereitzustellen und lesbare Anzeigenamen unabhängig von Ihrem Tokentyp anzuzeigen. Es wird empfohlen, diesen optionalen Anspruch anstelle etwa von upn oder unique_name zu verwenden. v1-ID-Token und Zugriffstoken

additionalProperties von optionalen Ansprüchen

Einige optionale Ansprüche können so konfiguriert werden, dass sie auf andere Art zurückgegeben werden. Diese additionalProperties unterstützen in erster Linie die Migration lokaler Anwendungen mit unterschiedlichen Datenerwartungen. So ist include_externally_authenticated_upn_without_hash beispielsweise hilfreich bei Clients, die keine Hashmarks (#) im UPN verarbeiten können.

Eigenschaftenname additionalProperty-Name BESCHREIBUNG
upn Kann für SAML- und JWT-Antworten und für v1.0- und v2.0-Token verwendet werden.
include_externally_authenticated_upn Bezieht den Gast-UPN ein, wie er im Ressourcenmandanten gespeichert ist. Beispiel: foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Wie zuvor aufgelistet, außer dass die Hashzeichen (#) durch Unterstriche (_) ersetzt werden, z. B. foo_hometenant.com_EXT_@resourcetenant.com.
aud In v1-Zugriffstoken wird dieser Anspruch verwendet, um das Format des aud-Anspruchs zu ändern. Dieser Anspruch hat keine Auswirkungen auf v2-Token oder ID-Token einer beliebigen Version, bei denen der aud-Anspruch immer die Client-ID ist. Verwenden Sie diese Konfiguration, um sicherzustellen, dass Ihre API die Validierung der Zielgruppe einfacher durchführen kann. Wie alle optionalen Ansprüche, die sich auf das Zugriffstoken auswirken, muss die Ressource in der Anforderung diesen optionalen Anspruch festlegen, da Ressourcen Besitzer des Zugriffstokens sind.
use_guid Gibt die Client-ID der Ressource (API) im GUID-Format immer als aud-Anspruch aus, statt sie als nicht laufzeitabhängig festzulegen. Ein Beispiel: Wenn eine Ressource dieses Flag festlegt und die Client-ID 00001111-aaaa-2222-bbbb-3333cccc4444 lautet, erhält jede Anwendung, die ein Zugriffstoken für diese Ressource anfordert, ein Zugriffstoken mit aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Wenn dieser Anspruch nicht festgelegt ist, könnte eine API Token mit dem aud-Anspruch von api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField oder einem anderen Wert, der als App-ID-URI für diese API festgelegt wurde, und die Client-ID der Ressource abrufen.
idtyp Dieser Anspruch wird verwendet, um den Tokentyp (App, Benutzer, Gerät) abzurufen. Standardmäßig wird er nur für App-exklusive Token ausgegeben. Wie alle optionalen Ansprüche, die sich auf das Zugriffstoken auswirken, muss die Ressource in der Anforderung diesen optionalen Anspruch festlegen, da Ressourcen Besitzer des Zugriffstokens sind.
include_user_token Gibt den idtyp-Anspruch für das Benutzertoken aus. Wenn diese optionale zusätzliche Eigenschaft für den idtyp-Anspruch nicht festgelegt ist, ruft eine API nur den Anspruch für App-Token ab.

additionalProperties-Beispiel

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Dieses optionalClaims-Objekt bewirkt, dass das an den Client zurückgegebene ID-Token einen upn-Anspruch mit den anderen Informationen zum Home- und zum Ressourcenmandanten enthält. Der upn-Anspruch wird im Token nur dann geändert, wenn der Benutzer ein Gastbenutzer im Mandanten ist (und einen anderen Identitätsanbieter für die Authentifizierung verwendet).

Siehe auch

Nächste Schritte