Teilen über

Konfigurieren optionaler Ansprüche

  • Artikel

Token, die Von Microsoft Entra zurückgegeben werden, werden kleiner gehalten, um eine optimale Leistung durch Clients sicherzustellen, die sie anfordern. Daher sind einige Ansprüche nicht mehr standardmäßig im Token vorhanden und müssen für einzelne Anwendungen speziell angefordert werden.

Sie können optionale Ansprüche für Ihre Anwendung über die Anwendungsschnittstelle oder das Manifest des Microsoft Entra Admin Centers konfigurieren.

Voraussetzungen

Konfigurieren von optionalen Ansprüchen für die Anwendung

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.
  2. Wechseln Sie zu Identität>Anwendungen>App-Registrierungen.
  3. Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche basierend auf Ihrem Szenario und dem gewünschten Ergebnis konfigurieren möchten.
  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, z. B. Access.
  4. Wählen Sie die hinzuzufügenden optionalen Ansprüche aus.
  5. Wählen Sie Hinzufügen.

Das optionalClaims-Objekt deklariert die von einer Anwendung angeforderten optionalen Ansprüche. Eine Anwendung kann optionale Ansprüche konfigurieren, die in ID-Token, Zugriffstoken und SAML 2-Token zurückgegeben werden. Die Anwendung kann einen anderen Satz optionaler Ansprüche für die Rückgabe im jeweiligen Tokentyp konfigurieren.

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

Wenn es durch einen bestimmten Anspruch unterstützt wird, können Sie auch das Verhalten des optionalen Anspruchs mithilfe des Felds additionalProperties ändern.

Name Typ 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) Andere 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.

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 die Microsoft Graph-API. Das Zugriffstoken wird 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 Anwendung an.

Optionale Ansprüche unterstützen Erweiterungsattribute und Verzeichniserweiterungen. Dieses Feature ist von Nutzen, um zusätzliche Benutzerinformationen anzufügen, die von Ihrer Anwendung verwendet werden können. Beispielsweise andere Bezeichner oder wichtige Konfigurationsoptionen, die der Benutzende festgelegt hat. Wenn Ihr Anwendungsmanifest eine benutzerdefinierte Erweiterung erfordert und sich ein MSA-Benutzender bei Ihrer Anwendung 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 optionaler Gruppenansprüche

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

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 das Azure-Portal oder das Anwendungsmanifest konfigurieren. Optionale Gruppenansprüche werden im JWT nur für Benutzerprinzipale ausgegeben. Dienstprinzipale sind nicht in optionalen Gruppenansprüchen enthalten, die im JWT ausgegeben werden.

Wichtig

Die Anzahl von Gruppen, die in einem Token ausgegeben werden, ist für SAML-Assertionen auf 150 und für JWT auf 200 (einschließlich geschachtelter Gruppen) beschränkt. Unter Konfigurieren von Gruppenansprüchen für Anwendungen finden Sie weitere Informationen zu Grenzwerten für Gruppen und wichtigen Einschränkungen bei Gruppenansprüchen aus lokalen Attributen.

Führen Sie die folgenden Schritte aus, um optionale Gruppenansprüche mithilfe des Azure-Portal zu konfigurieren:

  1. Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.
  2. Wählen Sie unter Verwalten die Option Tokenkonfiguration aus.
  3. Wählen Sie Anspruchsgruppen hinzufügen aus.
  4. 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.
  5. 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.
  6. Wählen Sie Speichern aus.

Führen Sie die folgenden Schritte aus, um optionale Gruppenansprüche über das Anwendungsmanifest zu konfigurieren:

  1. Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.

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

  3. 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 Objekt-IDs von Gruppen im Wert des Gruppenanspruchs ausgegeben. Wenn der Anspruchswert so geändert werden soll, dass er lokale Gruppenattribute enthält, oder um den Anspruchstyp zu „Rolle“ zu ändern, verwenden Sie die optionalClaims-Konfiguration wie folgt:

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

    Wenn die Gruppen im Token im Abschnitt mit optionalen Ansprüchen die lokalen Gruppenattribute enthalten sollen, geben Sie an, welcher optionale Anspruch des Tokentyps angewandt werden soll. Geben Sie auch den Namen des angeforderten optionalen Anspruchs und alle anderen gewünschten 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 optionalClaims im Manifest verwendet wird. Das optionalClaims-Schema lautet folgendermaßen:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}
    Schema für optionale Ansprüche Wert
    name Muss gleich groups sein.
    source Wird nicht verwendet. Auslassen oder NULL angeben.
    essential Wird nicht verwendet. Auslassen oder FALSE angeben.
    additionalProperties Liste der anderen 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 entweder sam_account_name, dns_domain_and_sam_account_name oder netbios_domain_and_sam_account_name erforderlich. Wenn mehrere dieser Optionen vorhanden sind, wird die erste verwendet, alle weiteren werden ignoriert. Sie können auch cloud_displayname hinzufügen, um den Anzeigenamen der Cloudgruppe auszugeben. Diese Option funktioniert nur, wenn groupMembershipClaims auf ApplicationGroup festgelegt ist.

    Einige Anwendungen erfordern Gruppeninformationen über Benutzer im Rollenanspruch. Fügen Sie emit_as_roles zu additionalProperties 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 Benutzenden (oder einer Ressourcenanwendung) zugewiesen sind, nicht im Rollenanspruch enthalten.

Die folgenden Beispiele zeigen die Manifestkonfiguration für Gruppenansprüche:

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

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

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

"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"
            ]
        }
    ]
}

Ausgeben von Gruppennamen im Format sam_account_name für lokale synchronisierte Gruppen und des cloud_display-Namens für Cloudgruppen in SAML- und OIDC-ID-Token für die der Anwendung zugewiesenen Gruppen.

"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

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 das Azure-Portal verwenden.
  • Sie können das Manifest verwenden.
  • 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.

Im folgenden Beispiel werden das Azure-Portal und das Manifest verwendet, um den für Ihre Anwendung vorgesehenen Zugriffs-, ID- und SAML-Token optionale Ansprüche hinzuzufügen. Verschiedene optionale Ansprüche werden den einzelnen Tokentypen hinzugefügt, die von der Anwendung empfangen werden können:

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

Konfigurieren von Ansprüchen im Azure-Portal:

  1. Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.
  2. Wählen Sie unter Verwalten die Option Tokenkonfiguration aus.
  3. 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.
  4. 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.
  5. Klicken Sie auf dem Übersichtsbildschirm „Tokenkonfiguration“ auf das Stiftsymbol neben upn, anschließend auf den Umschalter Extern authentifiziert und dann auf Speichern.
  6. Wählen Sie Optionalen Anspruch hinzufügen und dann den Tokentyp SAML aus. Wählen Sie in der Liste der Ansprüche den Eintrag extn.skypeID (gilt nur, wenn Sie ein Microsoft Entra-Benutzerobjekt mit dem Namen „skypeID“ erstellt haben) und dann Hinzufügen aus.

Konfigurieren von Ansprüchen im Manifest:

  1. Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.

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

  3. 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
        }
    ]
}

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

Zugehöriger Inhalt