Teilen über

Optionale Anspruchsreferenz

  • Artikel

Sie können optionale Ansprüche verwenden, um:

  • Wählen Sie Ansprüche aus, die in Token für Ihre Anwendung eingeschlossen werden sollen.
  • Ändern Sie das Verhalten bestimmter Ansprüche, die die Microsoft Identity Platform in Token zurückgibt.
  • Fügen Sie benutzerdefinierte Ansprüche für Ihre Anwendung hinzu und greifen Sie auf sie zu.

Optionale Ansprüche werden zwar sowohl im v1.0- als auch in v2.0-Formattoken und SAML-Token unterstützt, stellen aber den größten Teil ihres Werts bereit, wenn sie von v1.0 auf v2.0 wechseln. In der Microsoft Identity Platform werden kleinere Tokengrößen verwendet, um eine optimale Leistung durch Clients sicherzustellen. Daher sind mehrere Ansprüche, die früher in den Zugriffs- und ID-Token enthalten sind, nicht mehr in v2.0-Token vorhanden und müssen speziell auf Anwendungsbasis angefordert werden.

Kontoart v1.0-Token v2.0-Token
Persönliches Microsoft-Konto N/A Abgestützt
Microsoft Entra-Konto Abgestützt Abgestützt

optionale Anspruchssätze v1.0 und v2.0

Der Satz optionaler Ansprüche, die standardmäßig für zu verwendende Anwendungen verfügbar sind, wird in der folgenden Tabelle aufgeführt. Sie können benutzerdefinierte Daten in Erweiterungsattributen und Verzeichniserweiterungen verwenden, um optionale Ansprüche für Ihre Anwendung hinzuzufügen. Wenn Sie dem Zugriffstoken Ansprüche hinzufügen, gelten die Ansprüche für Zugriffstoken, die für der Anwendung angefordert wurden (eine Web-API), und keine Ansprüche, die von der Anwendung angefordert werden. Unabhängig davon, wie der Client auf Ihre API zugreift, sind die richtigen Daten im Zugriffstoken vorhanden, das für die Authentifizierung bei Ihrer API verwendet wird.

Anmerkung

Die meisten dieser Ansprüche können in JWTs für v1.0- und v2.0-Token enthalten sein, jedoch keine SAML-Token, mit Ausnahme der Angabe in der Spalte "Tokentyp". Verbraucherkonten unterstützen eine Teilmenge dieser Ansprüche, die in der Spalte "Benutzertyp" gekennzeichnet sind. Viele der aufgeführten Ansprüche gelten nicht für Verbraucherbenutzer (sie haben keinen Mandanten, daher hat tenant_ctry keinen Wert).

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 Mitglied des Mandanten ist, wird der Wert 0. Wenn sie ein Gast sind, ist der Wert 1.
acrs Authentifizierungskontext-IDs JWT Microsoft Entra-ID Gibt die Authentifizierungskontext-IDs der Vorgänge an, die der Bearer ausführen kann. Authentifizierungskontext-IDs können verwendet werden, um eine Anforderung für eine schrittweise Authentifizierung innerhalb Ihrer Anwendung und Dienste auszulösen. Wird häufig zusammen mit dem xms_cc Anspruch verwendet.
auth_time Zeitpunkt, zu dem sich der Benutzer zuletzt authentifiziert hat. JWT
ctry Land/Region des Benutzers JWT Dieser Anspruch wird zurückgegeben, wenn er vorhanden ist und der Wert des Felds ein Standardcode mit zwei Buchstaben ist, z. B. FR, JP, SZ usw.
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 (die Benutzer innerhalb des Mandanten) muss sie über diesen optionalen Anspruch angefordert werden oder nur auf v2.0 mit dem OpenID-Bereich. Dieser Wert ist nicht garantiert korrekt und kann im Laufe der Zeit stummgeschaltet werden . 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 die Berechtigung für den Zugriff auf diese Datenverfügt. Wenn Sie den E-Mail-Anspruch für die Autorisierung verwenden, empfehlen wir, eine Migration durchzuführen, um zu einem sichereren Anspruchzu wechseln. 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 Ihre UX vorab ausfüllen.
fwd IP-Adresse JWT Fügt die ursprüngliche Adresse des anfordernden Clients hinzu (in einem VNET).
groups Optionale Formatierung für Gruppenansprüche JWT, SAML Der groups Anspruch wird mit der Einstellung "GroupMembershipClaims" im Anwendungsmanifestverwendet, das ebenfalls festgelegt werden muss.
idtyp Tokentyp JWT-Zugriffstoken Spezial: nur in Nur-App-Zugriffstoken Der Wert wird app, wenn es sich bei dem Token um ein nur-App-Token handelt. Dieser Anspruch ist die genaueste Methode für eine API, um festzustellen, ob es sich bei einem Token um ein App-Token oder um ein App+Benutzertoken handelt.
login_hint Anmeldehinweis JWT MSA, Microsoft Entra ID Ein undurchsichtiger, zuverlässiger Anmeldehinweisanspruch, der base64-codiert ist. Ändern Sie diesen Wert nicht. Dieser Anspruch ist der beste Wert, der für den login_hint OAuth-Parameter in allen Flüssen zum Abrufen von SSO verwendet werden soll. Es kann zwischen Anwendungen übergeben werden, um sie im Hintergrund zu unterstützen – Anwendung A kann sich bei einem Benutzer anmelden, den login_hint Anspruch lesen und dann den Anspruch und den aktuellen Mandantenkontext an Anwendung B in der Abfragezeichenfolge oder im Fragment senden, wenn der Benutzer einen Link auswählt, der sie zur Anwendung B führt. Um Racebedingungen und Zuverlässigkeitsprobleme zu vermeiden, enthält der login_hint Anspruch, den aktuellen Mandanten für den Benutzer nicht und standardmäßig den Heimmandanten des Benutzers bei Verwendung enthält. In einem Gastszenario, in dem der Benutzer von einem anderen Mandanten stammt, muss eine Mandanten-ID in der Anmeldeanforderung bereitgestellt werden. und übergeben Sie dasselbe an Apps, mit der Sie zusammenarbeiten. Dieser Anspruch ist für die Verwendung mit der vorhandenen login_hint-Funktionalität Ihres SDK vorgesehen, die jedoch verfügbar gemacht wird.
tenant_ctry Land/Region des Ressourcenmandanten JWT Identisch mit ctry, außer auf Mandantenebene durch einen Administrator festgelegt. Muss auch ein standardwert mit zwei Buchstaben sein.
tenant_region_scope Region des Ressourcenmandanten JWT
upn UserPrincipalName JWT, SAML Ein Bezeichner für den Benutzer, der mit dem parameter username_hint verwendet werden kann. Kein dauerhafter Bezeichner für den Benutzer und sollte nicht zur Autorisierung oder zur eindeutigen Identität von Benutzerinformationen verwendet werden (z. B. als Datenbankschlüssel). Verwenden Sie stattdessen die Benutzerobjekt-ID (oid) als Datenbankschlüssel. Weitere Informationen finden Sie unter Sichere Anwendungen und APIs durch Validieren von Ansprüchen. Benutzer, die sich mit einer alternativen Anmelde-ID anmelden sollten ihren Benutzerprinzipalnamen (User Principal Name, UPN) nicht anzeigen. Verwenden Sie stattdessen die folgenden ID-Tokenansprüche zum Anzeigen des Anmeldestatus für den Benutzer: preferred_username oder unique_name für v1-Token und preferred_username für v2-Token. Obwohl dieser Anspruch automatisch enthalten ist, können Sie ihn als optionalen Anspruch angeben, um andere Eigenschaften anzufügen, um sein Verhalten im Gastbenutzerfall zu ändern. Sie sollten den login_hint Anspruch für login_hint Verwendung verwenden – lesbare Bezeichner wie UPN sind unzuverlässig.
verified_primary_email Stammen aus der PrimaryAuthoritativeEmail des Benutzers JWT
verified_secondary_email Stammen aus der SecondaryAuthoritativeEmail des Benutzers JWT
vnet VNET-Spezifikationsinformationen. JWT
xms_cc Clientfunktionen JWT Microsoft Entra-ID Gibt an, ob die Clientanwendung, die das Token erworben hat, Anspruchsaufforderungen verarbeiten kann. Es wird häufig zusammen mit Anspruch acrsverwendet. Dieser Anspruch wird häufig in Szenarien für den bedingten Zugriff und die Auswertung des kontinuierlichen Zugriffs verwendet. Der Ressourcenserver oder die Dienstanwendung, für die das Token ausgegeben wird, steuert das Vorhandensein dieses Anspruchs in einem Token. Ein Wert von cp1 im Zugriffstoken ist die autoritative Methode, um zu ermitteln, dass eine Clientanwendung in der Lage ist, eine Forderungsaufforderung zu verarbeiten. Weitere Informationen finden Sie unter Anspruchsanforderungen, Anspruchsanforderungen und Clientfunktionen.
xms_edov Boolescher Wert, der angibt, ob der E-Mail-Domänenbesitzer des Benutzers überprüft wurde. JWT Eine E-Mail wird als Domäne überprüft, wenn sie zum Mandanten gehört, in dem sich das Benutzerkonto befindet, und der Mandantenadministrator hat die Überprüfung der Domäne durchgeführt. Außerdem muss die E-Mail aus einem Microsoft-Konto (MSA), einem Google-Konto oder zur Authentifizierung mithilfe des OTP-Flusses (One-Time Passcode) verwendet werden. Facebook- und SAML/WS-Fed-Konten keine überprüften Domänen haben. Damit dieser Anspruch im Token zurückgegeben wird, ist das Vorhandensein des email Anspruchs erforderlich.
xms_pdl Bevorzugter Datenspeicherort JWT Bei Multi-Geo-Mandanten ist der bevorzugte Datenspeicherort der aus drei Buchstaben bestehende Code, der die geografische Region anzeigt, in der sich der Benutzer befindet. Weitere Informationen finden Sie in der Microsoft Entra Connect-Dokumentation zu bevorzugten Datenspeicherorten.
xms_pl Bevorzugte Sprache des Benutzers JWT Die bevorzugte Sprache des Benutzers, falls festgelegt. Stammen aus ihrem Heimmandanten, in Gastzugriffsszenarien. Formatierte LL-CC ("en-us").
xms_tpl Bevorzugte Sprache des Mandanten JWT Die bevorzugte Sprache des Ressourcenmandanten, falls festgelegt. Formatierte LL ("en").
ztdid Zero-Touch-Bereitstellungs-ID JWT Die für Windows AutoPilotverwendete Geräteidentität.

Warnung

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

v2.0-spezifische optionale Anspruchssätze

Diese Ansprüche sind immer in v1.0-Token enthalten, jedoch nicht in v2.0-Token enthalten, es sei denn, sie werden 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 der Client angemeldet ist.
onprem_sid Lokale Sicherheits-ID
pwd_exp Kennwortablaufzeit Die Anzahl der Sekunden nach dem Zeitpunkt im iat Anspruch, zu dem das Kennwort abläuft. Dieser Anspruch ist nur enthalten, wenn das Kennwort bald abläuft (gemäß der Definition von "Benachrichtigungstagen" in der Kennwortrichtlinie).
pwd_url Kennwort-URL ändern Eine URL, die der Benutzer besuchen kann, um sein Kennwort zu ändern. Dieser Anspruch ist nur enthalten, wenn das Kennwort bald abläuft (gemäß der Definition von "Benachrichtigungstagen" in der Kennwortrichtlinie).
in_corp Innerhalb des Unternehmensnetzwerks Signalisiert, ob sich der Client aus dem Unternehmensnetzwerk anmeldet. Wenn sie nicht vorhanden sind, ist der Anspruch nicht enthalten. Basierend auf den vertrauenswürdigen IPs Einstellungen in MFA.
family_name Nachname Stellt den Nachnamen, den Nachnamen oder den Familiennamen des Benutzers bereit, wie im Benutzerobjekt definiert. Beispiel: "family_name":"Miller". Unterstützt in MSA und Microsoft Entra ID. Erfordert den profile Bereich.
given_name Vorname Stellt den ersten oder "angegebenen" Namen des Benutzers bereit, wie für das Benutzerobjekt festgelegt. Beispiel: "given_name": "Frank". Unterstützt in MSA und Microsoft Entra ID. Erfordert den profile Bereich.
upn Benutzerprinzipalname Ein Bezeichner für den Benutzer, der mit dem parameter username_hint verwendet werden kann. Kein dauerhafter Bezeichner für den Benutzer und sollte nicht zur Autorisierung oder zur eindeutigen Identität von Benutzerinformationen verwendet werden (z. B. als Datenbankschlüssel). Weitere Informationen finden Sie unter Sichere Anwendungen und APIs durch Validieren von Ansprüchen. Verwenden Sie stattdessen die Benutzerobjekt-ID (oid) als Datenbankschlüssel. Benutzer, die sich mit einer alternativen Anmelde-ID anmelden sollten ihren Benutzerprinzipalnamen (User Principal Name, UPN) nicht anzeigen. Verwenden Sie stattdessen den folgenden preferred_username Anspruch zum Anzeigen des Anmeldestatus für den Benutzer. Erfordert den profile Bereich.

v1.0-spezifische optionale Anspruchssätze

Einige der Verbesserungen des v2-Tokenformats sind für Apps verfügbar, die das v1-Tokenformat verwenden, da sie die Sicherheit und Zuverlässigkeit verbessern. Diese Verbesserungen gelten nur für JWTs, nicht FÜR SAML-Token.

JWT-Anspruch Name Beschreibung Notizen
aud Publikum Immer in JWTs vorhanden, aber in v1-Zugriffstoken kann es auf verschiedene Weise ausgegeben werden – jeder appID-URI, mit oder ohne einen nachgestellten Schrägstrich und die Client-ID der Ressource. Diese Randomisierung kann beim Ausführen der Tokenüberprüfung schwer zu codieren sein. Verwenden Sie additionalProperties für diesen Anspruch, um sicherzustellen, dass sie immer auf die Client-ID der Ressource in v1-Zugriffstoken festgelegt ist. Nur JWT-Zugriffstoken
preferred_username Bevorzugter Benutzername Stellt den bevorzugten Benutzernamenanspruch innerhalb von v1-Token bereit. Dieser Anspruch erleichtert Apps das Bereitstellen von Benutzernamenhinweisen und das Anzeigen von lesbaren Anzeigenamen, unabhängig vom Tokentyp. Es wird empfohlen, diesen optionalen Anspruch anstelle von upn oder unique_namezu verwenden. v1-ID-Token und Zugriffstoken

additionalProperties optionaler Ansprüche

Einige optionale Ansprüche können so konfiguriert werden, dass sie die Art und Weise ändern, wie der Anspruch zurückgegeben wird. Diese additionalProperties werden hauptsächlich verwendet, um die Migration lokaler Anwendungen mit unterschiedlichen Datenerwartungen zu unterstützen. Beispielsweise hilft include_externally_authenticated_upn_without_hash bei Clients, die keine Hashmarken (#) im UPN verarbeiten können.

Eigenschaftenname additionalProperty Name Beschreibung
upn Kann sowohl für SAML- als auch für JWT-Antworten und für v1.0- und v2.0-Token verwendet werden.
include_externally_authenticated_upn Enthält den Gast-UPN, der im Ressourcenmandanten gespeichert ist. Beispiel: foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Identisch mit der zuvor aufgeführten Ausnahme, mit der Ausnahme, dass die Hashmarken (#) 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 die ID-Token der Version, wobei der aud Anspruch immer die Client-ID ist. Verwenden Sie diese Konfiguration, um sicherzustellen, dass Ihre API die Benutzergruppenüberprüfung 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 das Zugriffstoken besitzen.
use_guid Gibt die Client-ID der Ressource (API) im GUID-Format als aud Anspruch immer aus, anstatt davon abhängig zu sein. Wenn beispielsweise eine Ressource dieses Flag festlegt und die Client-ID 00001111-aaaa-2222-bbbb-3333cccc4444ist, erhält jede App, die ein Zugriffstoken für diese Ressource anfordert, ein Zugriffstoken mit aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Ohne diesen Anspruchssatz kann eine API Token mit einem aud Anspruch von api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField oder einem anderen Wert abrufen, der als App-ID-URI für diese API und die Client-ID der Ressource festgelegt wurde.
idtyp Dieser Anspruch wird verwendet, um den Tokentyp (App, Benutzer, Gerät) abzurufen. Standardmäßig wird sie nur für Nur-App-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 das Zugriffstoken besitzen.
include_user_token Gibt den idtyp Anspruch für das Benutzertoken aus. Ohne diese optionale zusätzliche Eigenschaft für den Idtyp-Anspruchssatz ruft eine API nur den Anspruch für App-Token ab.

beispiel für additionalProperties

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

Dieses optionalClaims-Objekt bewirkt, dass das id-Token, das an den Client zurückgegeben wird, einen upn Anspruch mit den informationen zum anderen Heimmandanten und Ressourcenmandanten enthält. Der upn Anspruch wird nur im Token geändert, wenn der Benutzer ein Gast im Mandanten ist (der einen anderen IDP für die Authentifizierung verwendet).

Siehe auch

Nächste Schritte