Konfigurieren und Verwalten optionaler Ansprüche in ID-Token, Zugriffstoken und SAML-Token

Artikel
2025-01-27

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

Ein Azure-Konto mit einem aktiven Abonnement. Erstellen Sie kostenlos ein Konto.
Abschluss der Schnellstartanleitung: Registrieren einer Anwendung

Konfigurieren von optionalen Ansprüchen für die Anwendung

Melden Sie sich mindestens als Cloudanwendungsadministrator beim Microsoft Entra Admin Center an.
Navigieren Sie zu Entra IDApp-Registrierungen.
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.

Fahren Sie mit der App-UI fort
Fahren Sie mit dem Manifest fort

Wählen Sie unter "Verwalten" die Option "Tokenkonfiguration" aus.
Wählen Sie "Optionalen Anspruch hinzufügen" aus.
Wählen Sie den Tokentyp aus, den Sie konfigurieren möchten, z. B. Access.
Wählen Sie die hinzuzufügenden optionalen Ansprüche aus.
Wählen Sie "Hinzufügen" aus.

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 das Manifest lokal herunterladen und bearbeiten und dann "Hochladen " verwenden, um es erneut auf Ihre Anwendung anzuwenden. Wenn die Datei keine optionalClaims Eigenschaft enthält, können Sie sie hinzufügen.

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

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 mithilfe des Manifests der Ressource generiert, nicht mit dem Client. 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

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. Weitere Informationen zu Gruppenbeschränkungen und wichtigen Einschränkungen für Gruppenansprüche aus lokalen Attributen finden Sie unter Konfigurieren von Gruppenansprüchen für Anwendungen.

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

Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.
Wählen Sie unter "Verwalten" die Option "Tokenkonfiguration" aus.
Wählen Sie "Gruppenanspruch hinzufügen" aus.
Wählen Sie die Gruppentypen aus, die zurückgegeben werden sollen (Sicherheitsgruppen oder Verzeichnisrollen, alle Gruppen und/oder Gruppen, die der Anwendung zugewiesen sind):
- Die der Anwendungsoption zugewiesenen Gruppen umfassen nur Gruppen, die der Anwendung zugewiesen sind. Die der Anwendungsoption zugewiesenen Gruppen werden für große Organisationen aufgrund des Gruppennummernlimits im Token empfohlen. Um die der Anwendung zugewiesenen Gruppen zu ändern, wählen Sie die Anwendung aus der Liste der Unternehmensanwendungen aus. Wählen Sie "Benutzer und Gruppen" und dann " Benutzer/Gruppe hinzufügen" aus. Wählen Sie die Gruppen aus, die Sie der Anwendung aus Benutzern und Gruppen hinzufügen möchten.
- Die Option "Alle Gruppen " enthält "SecurityGroup", " DirectoryRole" und "DistributionList", aber keine der Anwendung zugewiesenen Gruppen.
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.
Wählen Sie "Speichern" aus.

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

Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.
Wählen Sie unter "Verwalten"die Option "Manifest" aus.
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:

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.
Es ist auch möglich, eine Anwendung zu schreiben, die die Microsoft Graph-API verwendet, um Ihre Anwendung zu aktualisieren. Der OptionalClaims-Typ im Microsoft Graph-API-Referenzhandbuch kann Ihnen beim Konfigurieren der optionalen Ansprüche helfen.

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:

Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.
Wählen Sie unter "Verwalten" die Option "Tokenkonfiguration" aus.
Wählen Sie "Optionalen Anspruch hinzufügen", wählen Sie den ID-Tokentyp aus, wählen Sie upn aus der Liste der Ansprüche aus, und wählen Sie dann "Hinzufügen".
Wählen Sie "Optionalen Anspruch hinzufügen", wählen Sie den Zugriffstokentyp aus, wählen Sie auth_time aus der Liste der Ansprüche und dann "Hinzufügen" aus.
Wählen Sie im Übersichtsbildschirm der "Tokenkonfiguration" das Stiftsymbol neben upn aus, wählen Sie den Extern authentifiziert-Schalter aus, und wählen Sie dann Speichern aus.
Wählen Sie optionalen Anspruch hinzufügen, den SAML-Tokentyp , wählen Sie "extn.skypeID " aus der Liste der Ansprüche aus (gilt nur, wenn Sie ein Microsoft Entra-Benutzerobjekt namens skypeID erstellt haben), und wählen Sie dann "Hinzufügen" aus.

Konfigurieren von Ansprüchen im Manifest:

Wählen Sie die Anwendung aus, für die Sie optionale Ansprüche konfigurieren möchten.
Wählen Sie unter "Verwalten" die Option "Manifest " aus, um den Inlinemanifest-Editor zu öffnen.

Das Manifest kann mit diesem Editor direkt bearbeitet werden. Das Manifest folgt dem Schema für die Anwendungsentität und formatiert das Manifest automatisch nach dem Speichern. 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
        }
    ]
}

Wenn Sie mit dem Aktualisieren des Manifests fertig sind, wählen Sie "Speichern" aus, um das Manifest zu speichern.

Einschränkung

Eine Anwendung kann eine maximale Anzahl von 10 Erweiterungsattributen als optionale Ansprüche ausgeben.

Freigeben über