Bereitstellen optionaler Ansprüche für Ihre App

  • Artikel
  • 20 Minuten Lesedauer

Anwendungsentwickler können optionale Ansprüche in ihren Azure AD-Anwendungen verwenden, um anzugeben, welche Ansprüche in Token vorhanden sein sollen, die an ihre Anwendungen gesendet werden.

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

  • Auswählen zusätzlicher Ansprüche, 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

Die Listen der Standardansprüche finden Sie in der Anspruchsdokumentation unter Zugriffstoken und id_token.

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. Eines der Ziele von Microsoft Identity Platform ist eine geringere Tokengröße, 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.

Tabelle 1: Anwendbarkeit

Kontotyp v1.0-Token v2.0-Token
Persönliches Microsoft-Konto – Unterstützt
Azure AD-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 nachfolgend aufgeführt. Mit benutzerdefinierten Daten in Erweiterungsattributen und Verzeichniserweiterungen können Sie optionale Ansprüche für Ihre Anwendung hinzufügen. Informationen zum Verwenden von Verzeichniserweiterungen finden Sie weiter unten unter Verzeichniserweiterungen. 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 Consumerbenutzer (sie besitzen keinen Mandanten, daher weist tenant_ctry keinen Wert auf).

Tabelle 2: Gruppe optionaler Ansprüche in v1.0 und v2.0

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.
auth_time Zeitpunkt der letzten Authentifizierung des Benutzers. Siehe OpenID Connect-Spezifikation. JWT
ctry Land/Region des Benutzers JWT Azure AD gibt den optionalen Anspruch ctry zurück, 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) ist.
email Die gemeldete E-Mail-Adresse für diesen Benutzer JWT, SAML MSA, Azure AD 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 in Ihrer App eine adressierbare E-Mail-Adresse benötigen, fragen Sie diese Daten direkt vom Nutzer ab und nutzen Sie diese Angabe als Vorschlag oder Vorauswahl in Ihrer UX.
fwd IP-Adresse. JWT Fügt die ursprüngliche IPv4-Adresse des anfordernden Clients hinzu (wenn innerhalb eines VNET).
groups Optionale Formatierung für Gruppenansprüche JWT, SAML Weitere Informationen finden Sie weiter unten unter Gruppenansprüche. Weitere Informationen zu Gruppenansprüchen finden Sie unter Konfigurieren von Gruppenansprüchen. 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 ein Nur-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, Azure AD 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. Wenn Sie in einem Gastszenario arbeiten, in dem der Benutzer von einem anderen Mandanten stammt, müssen Sie in der Anmeldeanforderung einen Mandantenbezeichner angeben und diesen an die Apps ü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 Benutzers verwendet wird JWT Persönliche Konten und Azure AD-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 Benutzer, 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 Überprüfen, ob der Benutzer über Berechtigungen für den Zugriff auf diese Daten verfügt. 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 Gastbenutzer 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_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 Azure Active Directory Connect-Synchronisierung: Konfigurieren des bevorzugten Datenspeicherorts für Office 365-Ressourcen.
Zum Beispiel: APC für Asien-Pazifik.
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 für Windows Autopilot verwendete Geräteidentität

v2.0-spezifischer optionaler Anspruchssatz

Diese Ansprüche sind in Azure AD 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).

Tabelle 3: Nur in v2.0 enthaltene optionale Ansprüche

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 JWT-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.
„family_name“: „Miller“		 Wird in MSA und Azure AD unterstützt. Erfordert den Bereich profile.
given_name Vorname Gibt den Vornamen des Benutzers entsprechend der Definition im Benutzerobjekt an.
"given_name": "Frank"		 Wird in MSA und Azure AD unterstützt. Erfordert den Bereich profile.
upn Benutzerprinzipalname Ein Bezeichner für den Benutzer, 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 Überprüfen, ob der Benutzer über Berechtigungen für den Zugriff auf diese Daten verfügt. 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. Informationen zur Konfiguration des Anspruchs finden Sie weiter unten unter Zusätzliche Eigenschaften. 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 werden für die vom v2-Endpunkt angeforderten ID-Token oder Zugriffstoken für APIs, die das v2-Tokenformat verwenden, nicht wirksam. Diese verbesserungen gelten nur für JWTs, nicht für SAML-Token.

Tabelle 4: nur in v1.0 enthaltene optionale Ansprüche

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 die zusätzlichen Eigenschaften für diesen Anspruch, 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

Zusätzliche Eigenschaften optionaler Ansprüche

Einige optionale Ansprüche können so konfiguriert werden, dass sie auf andere Art zurückgegeben werden. Diese zusätzlichen Eigenschaften 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.

Tabelle 4: Werte zum Konfigurieren optionaler Ansprüche

Eigenschaftenname Name der zusätzlichen Eigenschaft 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. Zum Beispiel, foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash Wie oben, 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 bb0a297b-6a42-4a55-ac40-09a501456577 lautet, erhält jede App, die ein Zugriffstoken für diese Ressource anfordert, ein Zugriffstoken mit aud: bb0a297b-6a42-4a55-ac40-09a501456577.

Wenn dieser Anspruch nicht festgelegt ist, könnte eine API Token mit dem aud-Anspruch 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 der Client-ID der Ressource abrufen.

Beispiel für zusätzliche Eigenschaften

"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 zusätzlichen 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).

Konfigurieren optionaler Ansprüche

Wichtig

Zugriffstoken werden immer mit dem Manifest der Ressource und nicht des Clients generiert. In der Anforderung ...scope=https://graph.microsoft.com/user.read... ist die Ressource also die Microsoft Graph-API. Folglich wird das Zugriffstoken unter Verwendung des Microsoft Graph-API-Manifests und nicht des Clientmanifests erstellt. Eine Änderung des Manifests für Ihre Anwendung führt niemals dazu, dass Token für die Microsoft Graph-API anders aussehen. Um zu überprüfen, ob Ihre Änderungen an accessToken wirksam sind, fordern Sie ein Token für Ihre Anwendung, aber keine andere App an.

Sie können optionale Ansprüche für Ihre Anwendung über die Benutzeroberfläche oder das Anwendungsmanifest konfigurieren.

  1. Öffnen Sie das Azure-Portal.
  2. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.
  3. Wählen Sie unter Verwalten die Option App-Registrierungen aus.
  4. Wählen Sie in der Liste die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.

Konfigurieren optionaler Ansprüche über die Benutzeroberfläche:

Konfigurieren optionaler Ansprüche in der Benutzeroberfläche

  1. Wählen Sie unter Verwalten die Option Tokenkonfiguration aus.

  2. Wählen Sie Optionalen Anspruch hinzufügen aus.

  3. Wählen Sie den Tokentyp aus, den Sie konfigurieren möchten.

  4. Wählen Sie die hinzuzufügenden optionalen Ansprüche aus.

  5. Wählen Sie Hinzufügen.

Konfigurieren optionaler Ansprüche über das Anwendungsmanifest:

Zeigt, wie optionale Ansprüche mithilfe des Anwendungsmanifests konfiguriert werden.

  1. Wählen Sie unter Verwalten die Option Manifest aus. Ein webbasierter Manifest-Editor wird geöffnet, mit dem Sie das Manifest bearbeiten können. Optional können Sie Herunterladen wählen und das Manifest lokal bearbeiten und dann Hochladen verwenden, um es wieder auf Ihre Anwendung anzuwenden. Weitere Informationen zum Anwendungsmanifest finden Sie im Artikel Grundlegendes zum Azure AD-Anwendungsmanifest.

    Der folgende Eintrag im Anwendungsmanifest fügt ID-, Zugriffs- und SAML-Token die optionalen Ansprüche auth_time, ipaddr und upn hinzu.

    "optionalClaims": {
    "idToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "ipaddr",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "upn",
            "essential": false
        },
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": false
        }
    ]
}

  2. Wenn Sie fertig sind, wählen Sie Speichern aus. Nun werden die angegebenen optionalen Ansprüche in die Token für die Anwendung eingefügt.

Typ „OptionalClaims“

Deklariert die von einer Anwendung angeforderten optionalen Ansprüche. Eine Anwendung kann optionale Ansprüche so konfigurieren, dass sie in jedem der drei Tokentypen (ID-Token, Zugriffstoken, SAML 2-Token) zurückgegeben werden, die vom Sicherheitstokendienst empfangen werden können. Die Anwendung kann einen anderen Satz optionaler Ansprüche für die Rückgabe im jeweiligen Tokentyp konfigurieren. Die „OptionalClaims“-Eigenschaft der Anwendungsentität ist ein „OptionalClaims“-Objekt.

Tabelle 5: Eigenschaften des Typs „OptionalClaims“

Name type BESCHREIBUNG
idToken Sammlung (OptionalClaim) Die optionalen Ansprüche, die im JWT-ID-Token zurückgegeben werden.
accessToken Sammlung (OptionalClaim) Die optionalen Ansprüche, die im JWT-Zugriffstoken zurückgegeben werden.
saml2Token Sammlung (OptionalClaim) Die optionalen Ansprüche, die im SAML-Token zurückgegeben werden.

Typ „OptionalClaim“

Enthält einen optionalen Anspruch, der einer Anwendung oder einem Dienstprinzipal zugeordnet ist. Die „idToken“-, „accessToken“- und „saml2Token“-Eigenschaften des OptionalClaims-Typs ist eine Sammlung von „OptionalClaim“. Wenn durch einen bestimmten Anspruch unterstützt, können Sie auch das Verhalten von „OptionalClaim“ mithilfe des Felds „AdditionalProperties“ ändern.

Tabelle 6: Eigenschaften des Typs „OptionalClaim“

Name type BESCHREIBUNG
name Edm.String Der Name des optionalen Anspruchs.
source Edm.String Die Quelle (Verzeichnisobjekt) des Anspruchs. Es gibt vordefinierte Ansprüche und benutzerdefinierte Ansprüche aus Erweiterungseigenschaften. Wenn der Quellwert „null“ ist, ist der Anspruch ein vordefinierter optionaler Anspruch. Wenn der Quellwert „user“ ist, ist der Wert in der „name“-Eigenschaft die Erweiterungseigenschaft aus dem Benutzerobjekt.
essential Edm.Boolean Wenn der Wert „true“ ist, ist der vom Client angegebene Anspruch erforderlich, um eine reibungslose Autorisierung für die jeweilige vom Endbenutzer angeforderte Aufgabe sicherzustellen. Der Standardwert ist „FALSE“.
additionalProperties Sammlung (Edm.String) Zusätzliche Eigenschaften des Anspruchs. Wenn eine Eigenschaft in dieser Sammlung vorhanden ist, ändert sie das Verhalten des optionalen Anspruchs, der in der „name“-Eigenschaft angegeben ist.

Konfigurieren von optionalen Ansprüchen für die Verzeichniserweiterung

Neben den optionalen Standardansprüchen können Sie Token auch so konfigurieren, dass sie Microsoft Graph-Erweiterungen enthalten. Weitere Informationen finden Sie unter Hinzufügen von benutzerdefinierten Daten zu Ressourcen mithilfe von Erweiterungen.

Optionale Ansprüche unterstützen keine Schemaerweiterungen und offenen Erweiterungen, sondern nur Erweiterungsattribute und Verzeichniserweiterungen. Diese Funktion ist nützlich, um zusätzliche Benutzerinformationen anzufügen, die von Ihrer App verwendet werden können, z. B. einen zusätzlichen Bezeichner oder eine wichtige Konfigurationsoption, die vom Benutzer festgelegt wurde. Ein Beispiel finden Sie unten auf dieser Seite.

Verzeichniserweiterungen sind ein Feature, das auf Azure AD beschränkt ist. Wenn Ihr Anwendungsmanifest eine benutzerdefinierte Erweiterung erfordert und sich ein MSA-Benutzer bei Ihrer App anmeldet, werden diese Erweiterungen nicht zurückgegeben.

Formatierung der Verzeichniserweiterung

Verwenden Sie beim Konfigurieren der optionalen Ansprüche der Verzeichniserweiterung mithilfe des Anwendungsmanifests den vollständigen Namen der Erweiterung (im Format extension_<appid>_<attributename>). Die <appid> ist die entfernte Version der appId (oder Client-ID) der Anwendung, die den Anspruch anfordert.

Innerhalb des JWT werden diese Ansprüche mit dem folgenden Namensformat ausgegeben: extn.<attributename>

Innerhalb der SAML-Token werden diese Ansprüche mit dem folgenden URI-Format ausgegeben: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Konfigurieren von optionalen Gruppenansprüchen

Dieser Abschnitt behandelt die Konfigurationsoptionen unter den optionalen Ansprüchen, um die in Gruppenansprüchen verwendeten Gruppenattribute von der Standardgruppen-ObjectID in von lokalem Windows Active Directory synchronisierte Attribute zu ändern. Sie können optionale Gruppenansprüche für Ihre Anwendung über die Benutzeroberfläche oder das Anwendungsmanifest konfigurieren.

Wichtig

Azure AD begrenzt die Anzahl von Gruppen, die in einem Token ausgegeben werden, auf 150 für SAML-Assertionen und 200 für JWT, einschließlich geschachtelte Gruppen. Unter Konfigurieren von Gruppenansprüchen für Anwendungen mit Azure AD finden Sie weitere Informationen zu Grenzwerten für Gruppen und wichtigen Einschränkungen bei Gruppenansprüchen aus lokalen Attributen.

Konfigurieren optionaler Gruppenansprüche über die Benutzeroberfläche:

  1. Melden Sie sich beim Azure-Portal an.
  2. Wählen Sie nach der Authentifizierung Ihren Azure AD-Mandanten aus, indem Sie ihn in der rechten oberen Ecke der Seite auswählen.
  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.
  4. Wählen Sie unter Verwalten die Option App-Registrierungen aus.
  5. Wählen Sie in der Liste die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.
  6. Wählen Sie unter Verwalten die Option Tokenkonfiguration aus.
  7. Wählen Sie Anspruchsgruppen hinzufügen aus.
  8. Wählen Sie die zurückzugebenden Gruppentypen (Sicherheitsgruppen oder Verzeichnisrollen, Alle Gruppen und/oder Der Anwendung zugewiesene Gruppen) aus:
    • Die Option Der Anwendung zugewiesene Gruppen umfasst nur Gruppen, die der Anwendung zugewiesen sind. Die Option Der Anwendung zugewiesene Gruppen wird aufgrund der Einschränkung für die Anzahl von Gruppen im Token für große Organisationen empfohlen. Wenn Sie die der Anwendung zugewiesenen Gruppen ändern möchten, wählen Sie die Anwendung in der Liste Unternehmensanwendungen aus. Wählen Sie Benutzer und Gruppen und dann Benutzer/Gruppe hinzufügen aus. Wählen Sie aus Benutzern und Gruppen die Gruppe(n) aus, die Sie der Anwendung hinzufügen möchten.
    • Die Option Alle Gruppen umfasst SecurityGroup, DirectoryRole und DistributionListaber nicht Der Anwendung zugewiesene Gruppen.
  9. Optional: Wählen Sie die Eigenschaften des jeweiligen Tokentyps aus, um den Wert des Gruppenanspruchs so zu ändern, dass er lokale Gruppenattribute enthält, oder um den Anspruchstyp in eine Rolle zu ändern.
  10. Wählen Sie Speichern aus.

Konfigurieren optionaler Gruppenansprüche über das Anwendungsmanifest:

  1. Melden Sie sich beim Azure-Portal an.

  2. Wählen Sie nach der Authentifizierung Ihren Azure AD-Mandanten aus, indem Sie ihn in der rechten oberen Ecke der Seite auswählen.

  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.

  4. Wählen Sie in der Liste die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.

  5. Wählen Sie unter Verwalten die Option Manifest aus.

  6. Fügen Sie den folgenden Eintrag mit dem Manifest-Editor hinzu:

    Gültige Werte sind:

    • „Alle“ (umfasst „SecurityGroup“, „DirectoryRole“ und „DistributionList“)
    • SecurityGroup
    • DirectoryRole
    • „ApplicationGroup“ (diese Option umfasst nur Gruppen, die der Anwendung zugewiesen sind)

    Beispiel:

    "groupMembershipClaims": "SecurityGroup"

    Standardmäßig werden ObjectIDs von Gruppen im Wert des Gruppenanspruchs ausgegeben. Um den Anspruchswert so zu ändern, dass er lokale Gruppenattribute enthält, oder um den Anspruchstyp zu „role“ zu ändern, verwenden Sie die Konfiguration für optionale Ansprüche wie folgt:

  7. Legen Sie optionale Ansprüche für die Gruppennamenkonfiguration fest.

    Wenn die Gruppen im Token die lokalen AD-Gruppenattribute im Abschnitt mit optionalen Ansprüchen enthalten sollen, geben Sie an, welcher optionale Anspruch des Tokentyps angewandt werden soll. Geben Sie außerdem den Namen des angeforderten optionalen Anspruchs sowie weitere gewünschte Eigenschaften an. Es können mehrere Tokentypen aufgelistet werden:

    • idToken für das OIDC-ID-Token
    • accessToken für das OAuth-Zugriffstoken
    • Saml2Token für SAML-Token

    Der Typ „Saml2Token“ gilt für Token sowohl im SAML1.1- als auch im SAML2.0-Format.

    Ändern Sie für jeden relevanten Tokentyp den Gruppenanspruch so, dass der Abschnitt „Optionale Ansprüche“ im Manifest verwendet wird. Das Schema für optionale Ansprüche sieht folgendermaßen aus:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}
    Schema für optionale Ansprüche Wert
    name: Muss „groups“ lauten.
    source: Wird nicht verwendet. Auslassen oder NULL angeben.
    essential: Wird nicht verwendet. Auslassen oder FALSE angeben.
    additionalProperties: Liste zusätzlicher Eigenschaften. Gültige Optionen sind „sam_account_name“, „dns_domain_and_sam_account_name“, „netbios_domain_and_sam_account_name“, „emit_as_roles“ und „cloud_displayname.“

    In „additionalProperties“ ist nur eine dieser Optionen erforderlich: "sam_account_name", "dns_domain_and_sam_account_name" oder "netbios_domain_and_sam_account_name". Wenn mehrere dieser Optionen vorhanden sind, wird die erste verwendet, alle weiteren werden ignoriert. Darüber hinaus können Sie „cloud_displayname“ hinzufügen, um den Anzeigenamen der Cloudgruppe auszugeben. Beachten Sie, dass diese Option nur funktioniert, wenn “groupMembershipClaims” auf “ApplicationGroup”festgelegt ist.

    Einige Anwendungen erfordern Gruppeninformationen über Benutzer im Rollenanspruch. Fügen Sie den zusätzlichen Eigenschaften „emit_as_roles“ hinzu, um den Anspruchstyp von einem Gruppenanspruch in einen Rollenanspruch zu ändern. Die Gruppenwerte werden im Rollenanspruch ausgegeben.

    Wenn „emit_as_roles“ verwendet wird, sind konfigurierte Anwendungsrollen, die dem Benutzer zugewiesen sind, nicht im Rollenanspruch enthalten.

Beispiele:

  1. Ausgeben von Gruppen als Gruppennamen in OAuth-Zugriffstoken im Format „dnsDomainName\sAMAccountName“

    Benutzeroberflächenkonfiguration:

    Konfigurieren optionaler Ansprüche

    Eintrag des Anwendungsmanifests:

    "optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

  2. Ausgeben von Gruppennamen, die im Format „netbiosDomain\sAMAccountName“ als Rollenanspruch in SAML- und OIDC-ID-Token zurückgegeben werden sollen

    Benutzeroberflächenkonfiguration:

    Optionale Ansprüche im Manifest

    Eintrag des Anwendungsmanifests:

    "optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

  3. Geben Sie Gruppennamen im samAccountName-Format für lokale synchronisierte Gruppen aus, und zeigen Sie den Namen für Cloudgruppen in SAML- und OIDC-ID-Token für die der Anwendung zugewiesenen Gruppen an:

    Eintrag des Anwendungsmanifests:

    "groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

Beispiel für optionale Ansprüche

In diesem Abschnitt können Sie ein Szenario durchgehen, um zu erfahren, wie Sie optionale Ansprüche für Ihre Anwendung verwenden können. Es sind mehrere Optionen für das Aktualisieren der Eigenschaften in der Identitätskonfiguration einer Anwendung zum Aktivieren und Konfigurieren optionaler Ansprüche verfügbar:

  • Sie können die Benutzeroberfläche für die Tokenkonfiguration verwenden (siehe Beispiel unten).
  • Sie können das Manifest verwenden (siehe Beispiel unten). Lesen Sie zuerst das Dokument Grundlegendes zum Azure AD-Anwendungsmanifest, um eine Einführung in das Manifest zu erhalten.
  • Sie können zum Aktualisieren Ihrer Anwendung auch eine Anwendung schreiben, die die Microsoft Graph-API nutzt. Der Typ OptionalClaims im Referenzhandbuch zur Microsoft Graph-API kann beim Konfigurieren der optionalen Ansprüche hilfreich sein.

Beispiel:

Im folgenden Beispiel verwenden Sie die Benutzeroberfläche für die Tokenkonfiguration und das Manifest, um den Zugriffstoken, ID-Token und SAML-Token optionale Ansprüche hinzuzufügen, die für Ihre Anwendung vorgesehen sind. Verschiedene optionale Ansprüche wurden den einzelnen Tokentypen hinzugefügt, die von der Anwendung empfangen werden können:

  • Die ID-Token enthalten jetzt den UPN für Verbundbenutzer in vollständiger Form (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Die Zugriffstoken, die andere Clients für diese Anwendung anfordern, enthalten jetzt den Anspruch „auth_time“.
  • Die SAML-Token enthalten jetzt die Verzeichnisschemaerweiterung „skypeId“ (in diesem Beispiel lautet die App-ID für diese App „ab603c56068041afb2f6832e2a17e237“). Die SAML-Token stellen die Skype-ID als extension_ab603c56068041afb2f6832e2a17e237_skypeId bereit.

Benutzeroberflächenkonfiguration:

  1. Melden Sie sich beim Azure-Portal an.

  2. Wählen Sie nach der Authentifizierung Ihren Azure AD-Mandanten aus, indem Sie ihn in der rechten oberen Ecke der Seite auswählen.

  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.

  4. Wählen Sie unter Verwalten die Option App-Registrierungen aus.

  5. Suchen Sie in der Liste nach der Anwendung, für die Sie optionale Ansprüche konfigurieren möchten, und klicken Sie darauf.

  6. Wählen Sie unter Verwalten die Option Tokenkonfiguration aus.

  7. Klicken Sie auf Optionalen Anspruch hinzufügen, wählen Sie den Tokentyp ID und dann in der Liste der Ansprüche upn aus, und klicken Sie anschließend auf Hinzufügen.

  8. Klicken Sie auf Optionalen Anspruch hinzufügen, wählen Sie den Tokentyp Zugriff und dann in der Liste der Ansprüche auth_time aus, und klicken Sie anschließend auf Hinzufügen.

  9. Klicken Sie auf dem Übersichtsbildschirm „Tokenkonfiguration“ auf das Stiftsymbol neben upn, anschließend auf den Umschalter Extern authentifiziert und dann auf Speichern.

  10. Klicken Sie auf Optionalen Anspruch hinzufügen, wählen Sie den Tokentyp SAML und dann in der Liste der Ansprüche extn.skypeID aus (gilt nur, wenn Sie ein Azure AD-Benutzerobjekt mit dem Namen „skypeID“ erstellt haben), und klicken Sie anschließend auf Hinzufügen.

    Optionale Ansprüche für SAML-Token

Manifestkonfiguration:

  1. Melden Sie sich beim Azure-Portal an.

  2. Wählen Sie nach der Authentifizierung Ihren Azure AD-Mandanten aus, indem Sie ihn in der rechten oberen Ecke der Seite auswählen.

  3. Suchen Sie nach Azure Active Directory, und wählen Sie diese Option aus.

  4. Suchen Sie in der Liste nach der Anwendung, für die Sie optionale Ansprüche konfigurieren möchten, und klicken Sie darauf.

  5. Wählen Sie unter Verwalten die Option Manifest aus, um den Inline-Manifest-Editor zu öffnen.

  6. Das Manifest kann mit diesem Editor direkt bearbeitet werden. Das Manifest folgt dem Schema für die Anwendungsentität. Das Manifest wird nach dem Speichern automatisch formatiert. Neue Elemente werden der OptionalClaims-Eigenschaft hinzugefügt.

    "optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

  7. Wenn Sie das Manifest aktualisiert haben, klicken Sie auf Speichern, um das Manifest zu speichern.

Nächste Schritte

Erfahren Sie mehr über die Standardansprüche, die von Azure AD bereitgestellt werden.