Freigeben über

Anpassen von Ansprüchen, die im JWT-Token (JSON Web Token) für Unternehmensanwendungen ausgestellt wurden

  • Artikel

Die Microsoft Identity Platform unterstützt das einmalige Anmelden (SSO) bei den meisten vorab integrierten Anwendungen im Microsoft Entra-Anwendungskatalog sowie bei benutzerdefinierten Anwendungen. Wenn sich ein Benutzer mithilfe des OIDC-Protokolls über die Microsoft Identity Platform bei einer Anwendung authentifiziert, wird ein Token an die Anwendung gesendet. Die Anwendung überprüft und verwendet das Token, um den Benutzer anzumelden, statt den Benutzernamen und das Kennwort anzufordern.

Diese von OIDC- und OAuth-Anwendungen verwendeten JWT-Token (JSON Web Token) enthalten Informationen zum Benutzer bzw. zur Benutzerin, die als Ansprüche bezeichnet werden. Ein Anspruch (Claim) bezeichnet Informationen, die ein Identitätsanbieter über einen Benutzer in dem für diesen Benutzer ausgestellten Token angibt. In einer OIDC-Antwort sind Anspruchsdaten in der Regel im ID-Token enthalten, das vom Identitätsanbieter in Form eines JWT-Tokens ausgegeben wird.

Anzeigen oder Bearbeiten von Ansprüchen

Tipp

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

Optionale JWT-Ansprüche können in der ursprünglichen Anwendungsregistrierung konfiguriert werden. Sie können jedoch auch in der Unternehmensanwendung konfiguriert werden. So können Sie die im JWT an die Anwendung ausgegebenen Ansprüche anzeigen oder bearbeiten:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.
  2. Browsen Sie zu Identität>Anwendungen>Unternehmensanwendungen>Alle Anwendungen.
  3. Wählen Sie die Anwendung aus, wählen Sie im Menü auf der linken Seite Einmaliges Anmelden und dann im Abschnitt Attribute & Ansprüche die Option Bearbeiten aus.

Eine Anwendung kann aus verschiedenen Gründen eine Anpassung von Ansprüchen erfordern. Zum Beispiel, wenn eine Anwendung einen anderen Satz von Anspruchs-URIs oder Anspruchswerten benötigt. Im Abschnitt Attribute & Ansprüche können Sie einen Anspruch für Ihre Anwendung hinzufügen oder entfernen. Sie können auch einen benutzerdefinierten Anspruch erstellen, der für eine Anwendung basierend auf dem Anwendungsfall spezifisch ist.

Die folgenden Schritte beschreiben, wie Sie einen Konstantenwert zuweisen:

  1. Wählen Sie den Anspruch aus, den Sie ändern möchten.
  2. Geben Sie als Quellattribut den Konstantenwert (ohne Anführungszeichen) entsprechend Ihrer Organisation ein, und wählen Sie Speichern aus.

Die Übersicht Attribute zeigt den konstanten Wert an.

Transformationen besonderer Ansprüche

Sie können die folgenden Funktionen für die Transformation besonderer Ansprüche verwenden:

Funktion BESCHREIBUNG
ExtractMailPrefix() Entfernt das Domänensuffix aus der E-Mail-Adresse oder dem Benutzerprinzipalnamen. Diese Funktion extrahiert nur den ersten Teil des Benutzernamens. Beispiel: joe_smith anstelle von joe_smith@contoso.com.
ToLower() Konvertiert die Zeichen des ausgewählten Attributs in Kleinbuchstaben.
ToUpper() Konvertiert die Zeichen des ausgewählten Attributs in Großbuchstaben.

Hinzufügen anwendungsspezifischer Ansprüche

Gehen Sie wie folgt vor, um anwendungsspezifische Ansprüche hinzuzufügen:

  1. Wählen Sie im Abschnitt Benutzerattribute und Ansprüche die Option Neuen Anspruch hinzufügen aus, um die Seite Benutzeransprüche verwalten zu öffnen.
  2. Geben Sie den Namen der Ansprüche ein. Der Wert muss nicht unbedingt einem URI-Muster folgen. Wenn Sie ein URI-Muster benötigen, können Sie es im Feld Namespace angeben.
  3. Wählen Sie die Quelle aus, aus der der Anspruch den zugehörigen Wert abruft. Sie können ein Benutzerattribut aus der Dropdownliste für „Quellattribut“ auswählen oder eine Transformation auf das Benutzerattribut anwenden, bevor es als Anspruch ausgegeben wird.

Anspruchstransformationen

So wenden Sie eine Transformation auf ein Benutzerattribut an

  1. Wählen Sie unter Anspruch verwalten die Option Transformation als Anspruchsquelle aus, um die Seite Transformation verwalten zu öffnen.
  2. Wählen Sie in der Dropdownliste der Transformationen die Funktion aus. Abhängig von der ausgewählten Funktion müssen Sie Parameter und einen konstanten Wert angeben, die in der Transformation ausgewertet werden sollen.
  3. Quelle als mehrwertige Quelle behandeln ist ein Kontrollkästchen, mit dem Sie auswählen, ob die Transformation auf alle Werte oder nur auf den ersten angewendet werden soll. Standardmäßig wird die Transformation auf das erste Element in einem mehrwertigen Anspruch angewendet. Wenn Sie dieses Kontrollkästchen aktivieren, wird sichergestellt, dass sie auf alle angewendet wird. Dieses Kontrollkästchen wird nur für mehrwertige Attribute aktiviert. Beispiel: user.proxyaddresses.
  4. Klicken Sie auf Transformation hinzufügen, um mehrere Transformationen anzuwenden. Sie können maximal zwei Transformationen auf einen Anspruch anwenden. Beispielsweise könnten Sie zuerst das E-Mail-Präfix von user.mailextrahieren. Dann könnten Sie die Zeichenfolge in Großbuchstaben umwandeln.

Zum Transformieren von Ansprüchen können Sie die folgenden Funktionen verwenden.

Funktion BESCHREIBUNG
ExtractMailPrefix() Entfernt das Domänensuffix aus der E-Mail-Adresse oder dem Benutzerprinzipalnamen. Diese Funktion extrahiert nur den ersten Teil des Benutzernamens. Beispiel: joe_smith anstelle von joe_smith@contoso.com.
Join() Erstellt einen neuen Wert durch Verknüpfen von zwei Attributen. Optional können Sie ein Trennzeichen zwischen den beiden Attributen verwenden. Bei der NameID-Anspruchstransformation weist die Join()-Funktion ein bestimmtes Verhalten auf, wenn die Transformationseingabe einen Domänenteil beinhaltet. Sie entfernt den Domänenteil aus der Eingabe, bevor sie mit der Trennlinie und dem ausgewählten Parameter verbunden wird. Wenn die Eingabe der Transformation beispielsweise joe_smith@contoso.com, die Trennlinie @ und der Parameter fabrikam.com ist, führt diese Eingabekombination zu joe_smith@fabrikam.com.
ToLowercase() Konvertiert die Zeichen des ausgewählten Attributs in Kleinbuchstaben.
ToUppercase() Konvertiert die Zeichen des ausgewählten Attributs in Großbuchstaben.
Contains() Gibt ein Attribut oder eine Konstante aus, wenn die Eingabe dem angegebenen Wert entspricht. Andernfalls können Sie eine andere Ausgabe angeben, wenn keine Übereinstimmung vorhanden ist.
Beispiel: Sie möchten eine Forderung ausgeben, deren Wert die E-Mail-Adresse des Benutzers ist, wenn sie die Domäne @contoso.com enthält, andernfalls möchten Sie den Benutzerprinzipalnamen ausgeben. Konfigurieren Sie zum Ausführen dieser Funktion die folgenden Werte:
Parameter 1 (Eingabe) : user.email
Value: „@contoso.com“
Parameter 2 (Ausgabe): user.email
Parameter 3 (Ausgabe, wenn keine Übereinstimmung vorhanden ist): user.userprincipalname
EndWith() Gibt ein Attribut oder eine Konstante aus, wenn die Eingabe mit dem angegebenen Wert endet. Andernfalls können Sie eine andere Ausgabe angeben, wenn keine Übereinstimmung vorhanden ist.
Beispiel: Sie möchten einen Anspruch ausgeben, dessen Wert der Mitarbeiter-ID des Benutzers entspricht, wenn die Mitarbeiter-ID mit 000 endet. Andernfalls soll ein Erweiterungsattribut ausgegeben werden. Konfigurieren Sie zum Ausführen dieser Funktion die folgenden Werte:
Parameter 1 (Eingabe) : user.employeeid
Value: „000“
Parameter 2 (Ausgabe): user.employeeid
Parameter 3 (Ausgabe, wenn keine Übereinstimmung vorhanden ist): user.extensionattribute1
StartWith() Gibt ein Attribut oder eine Konstante aus, wenn die Eingabe mit dem angegebenen Wert beginnt. Andernfalls können Sie eine andere Ausgabe angeben, wenn keine Übereinstimmung vorhanden ist.
Beispiel: Sie möchten einen Anspruch ausgeben, bei dem der Wert der Mitarbeiter-ID des Benutzer entspricht, wenn das Land bzw. die Region mit US beginnt. Andernfalls soll ein Erweiterungsattribut ausgegeben werden. Konfigurieren Sie zum Ausführen dieser Funktion die folgenden Werte:
Parameter 1 (Eingabe) : user.country
Value: „US“
Parameter 2 (Ausgabe): user.employeeid
Parameter 3 (Ausgabe, wenn keine Übereinstimmung vorhanden ist): user.extensionattribute1
Extract() – nach dem Abgleich Gibt die Teilzeichenfolge bei Übereinstimmung mit dem angegebenen Wert zurück.
Beispiel: Wenn der Eingabewert Finance_BSimon und der übereinstimmende Wert Finance_ ist, dann ist die Ausgabe des Anspruchs BSimon.
Extract() – vor dem Abgleich Gibt die Teilzeichenfolge zurück, bis sie mit dem angegebenen Wert übereinstimmt.
Beispiel: Wenn der Eingabewert BSimon_US und der übereinstimmende Wert _US ist, dann ist die Ausgabe des Anspruchs BSimon.
Extract() – zwischen Abgleichen Gibt die Teilzeichenfolge zurück, bis sie mit dem angegebenen Wert übereinstimmt.
Beispiel: Wenn der Eingabewert Finance_BSimon_US ist, der erste übereinstimmende Wert Finance_ und der zweite übereinstimmende Wert _US lautet, dann ist die Ausgabe des Anspruchs BSimon.
ExtractAlpha() – Präfix Gibt den alphabetischen Teil des Präfixes der Zeichenfolge zurück.
Beispiel: Wenn der Eingabewert BSimon_123 ist, wird BSimon zurückgegeben.
ExtractAlpha() – Suffix Gibt den alphabetischen Teil des Suffixes der Zeichenfolge zurück.
Beispiel: Wenn der Eingabewert 123_Simon ist, wird Simon zurückgegeben.
ExtractNumeric() – Präfix Gibt den numerischen Teil des Präfixes der Zeichenfolge zurück.
Beispiel: Wenn der Eingabewert 123_BSimon ist, wird 123 zurückgegeben.
ExtractNumeric() – Suffix Gibt den numerischen Teil des Suffixes der Zeichenfolge zurück.
Beispiel: Wenn der Eingabewert BSimon_123 ist, wird 123 zurückgegeben.
IfEmpty() Gibt ein Attribut oder eine Konstante aus, wenn die Eingabe null oder leer ist.
Beispiel: Sie möchten ein in einem Erweiterungsattribut gespeichertes Attribut ausgeben, wenn die Mitarbeiter-ID für einen bestimmten Benutzer leer ist. Konfigurieren Sie zum Ausführen dieser Funktion die folgenden Werte:
Parameter 1 (Eingabe): user.employeeid
Parameter 2 (Ausgabe): user.extensionattribute1
Parameter 3 (Ausgabe, wenn keine Übereinstimmung vorhanden ist): user.employeeid
IfNotEmpty() Gibt ein Attribut oder eine Konstante aus, wenn die Eingabe nicht null oder leer ist.
Beispiel: Sie möchten ein in einem Erweiterungsattribut gespeichertes Attribut ausgeben, wenn die Mitarbeiter-ID für einen bestimmten Benutzer nicht leer ist. Konfigurieren Sie zum Ausführen dieser Funktion die folgenden Werte:
Parameter 1 (Eingabe): user.employeeid
Parameter 2 (Ausgabe): user.extensionattribute1
Substring() – feste Länge Extrahiert Teile eines Zeichenfolgenanspruchstyps ab dem Zeichen an der angegebenen Position und gibt die angegebene Anzahl von Zeichen zurück.
SourceClaim: Die Anspruchsquelle der Transformation, die ausgeführt werden soll
StartIndex: Die nullbasierte Anfangsposition einer Teilzeichenfolge in dieser Instanz.
Length: Die Länge der Teilzeichenfolge in Zeichen.
Beispiel:
sourceClaim: PleaseExtractThisNow
StartIndex: 6
Length: 11
Output: ExtractThis
Substring() – EndOfString Extrahiert Teile eines Zeichenfolgenanspruchstyps ab dem Zeichen an der angegebenen Position und gibt den Rest des Anspruchs vom angegebenen StartIndex-Wert zurück.
SourceClaim: Die Anspruchsquelle der Transformation.
StartIndex: Die nullbasierte Anfangsposition einer Teilzeichenfolge in dieser Instanz.
Beispiel:
sourceClaim: PleaseExtractThisNow
StartIndex: 6
Output: ExtractThisNow
RegexReplace() Die RegexReplace()-Transformation akzeptiert diese Werte als Eingabeparameter:
– Parameter 1: ein Benutzerattribut als RegEx-Eingabe
– Eine Option zum Vertrauen der mehrwertigen Quelle
– RegEx-Muster
– Ersetzungsmuster Das Ersetzungsmuster kann statisches Textformat zusammen mit einem Verweis auf RegEx-Ausgabegruppen und zusätzliche Eingabeparameter enthalten.

Wenn Sie weitere Transformationen benötigen, übermitteln Sie Ihre Vorschläge an das Microsoft Entra ID-Feedbackforum in der Kategorie SaaS-Anwendung.

RegEx-basierte Anspruchstransformation

Die folgende Abbildung zeigt ein Beispiel für die Transformation der ersten Ebene:

Screenshot: Transformation der ersten Ebene

Die folgende Tabelle enthält Informationen zur Transformation der ersten Ebene. Die in der Tabelle aufgeführten Aktionen entsprechen den Bezeichnungen in der vorherigen Abbildung. Wählen Sie Bearbeiten aus, um das Blatt für die Anspruchstransformation zu öffnen.

Aktion Feld BESCHREIBUNG
1 Transformation Wählen Sie aus den Optionen Transformation die Option RegexReplace() aus, um die RegEx-basierte Anspruchstransformationsmethode für die Anspruchstransformation zu verwenden.
2 Parameter 1 Die Eingabe für die Transformation regulärer Ausdrücke. „user.mail“ ergibt beispielsweise die E-Mail-Adresse des Benutzers, etwa admin@fabrikam.com.
3 Treat source as multivalued Einige Eingabebenutzerattribute können mehrwertige Benutzerattribute sein. Wenn das ausgewählte Benutzerattribut mehrere Werte unterstützt und der Benutzer mehrere Werte für die Transformation verwenden möchte, muss er Quelle als mehrwertige Quelle behandeln auswählen. Wenn diese Option ausgewählt ist, werden alle Werte für die RegEx-Übereinstimmung verwendet, andernfalls wird nur der erste Wert verwendet.
4 Regex pattern Ein regulärer Ausdruck, der anhand des Werts des als Parameter 1 ausgewählten Benutzerattributs ausgewertet wird. Beispiel: Ein regulärer Ausdruck zum Extrahieren des Benutzeralias aus der E-Mail-Adresse des Benutzers würde (?'domain'^.*?)(?i)(\@fabrikam\.com)$ lauten.
5 Add additional parameter Für die Transformation können mehrere Benutzerattribute verwendet werden. Die Werte der Attribute würden dann mit der RegEx-Transformationsausgabe zusammengeführt. Bis zu fünf weitere Parameter werden unterstützt.
6 Replacement pattern Das Ersetzungsmuster ist die Textvorlage, die Platzhalter für RegEx-Ergebnisse enthält. Alle Gruppennamen müssen in geschweifte Klammern eingeschlossen sein, z. B. {group-name}. Angenommen, der Administrator möchte den Benutzeralias mit einem anderen Domänennamen (etwa xyz.com) verwenden und den Ländernamen damit zusammenführen. In diesem Fall wäre das Ersetzungsmuster {country}.{domain}@xyz.com. Dabei steht {country} für den Wert des Eingabeparameters und {domain} für die Gruppenausgabe der Auswertung regulärer Ausdrücke. In diesem Fall ist das erwartete Ergebnis US.swmal@xyz.com.

Die folgende Abbildung zeigt ein Beispiel für die Transformation der zweiten Ebene:

Screenshot: Transformation der zweiten Ebene

Die folgende Tabelle enthält Informationen zur Transformation der zweiten Ebene. Die in der Tabelle aufgeführten Aktionen entsprechen den Bezeichnungen in der vorherigen Abbildung.

Aktion Feld BESCHREIBUNG
1 Transformation RegEx-basierte Anspruchstransformationen sind nicht auf die erste Transformation beschränkt und können auch als Transformation der zweiten Ebene verwendet werden. Jede andere Transformationsmethode kann als erste Transformation verwendet werden.
2 Parameter 1 Wenn RegexReplace() als Transformation der zweiten Ebene ausgewählt wird, wird die Ausgabe der Transformation der ersten Ebene als Eingabe für die Transformation der zweiten Ebene verwendet. Um die Transformation anzuwenden, muss der RegEx-Ausdruck der zweiten Ebene mit der Ausgabe der ersten Transformation übereinstimmen.
3 Regex pattern RegEx-Muster ist der reguläre Ausdruck für die Transformation der zweiten Ebene.
4 Parameter input Benutzerattributeingaben für die Transformationen der zweiten Ebene.
5 Parameter input Administratoren können den ausgewählten Eingabeparameter löschen, wenn sie ihn nicht mehr benötigen.
6 Replacement pattern Das Ersetzungsmuster ist die Textvorlage, die Platzhalter für den Namen der RegEx-Ergebnisgruppe, den Namen der Eingabeparametergruppe und den statischen Textwert enthält. Alle Gruppennamen müssen in geschweifte Klammern eingeschlossen sein, z. B. {group-name}. Angenommen, der Administrator möchte den Benutzeralias mit einem anderen Domänennamen (etwa xyz.com) verwenden und den Ländernamen damit zusammenführen. In diesem Fall wäre das Ersetzungsmuster {country}.{domain}@xyz.com. Dabei steht {country} für den Wert des Eingabeparameters und {domain} für die Gruppenausgabe der Auswertung regulärer Ausdrücke. In diesem Fall ist das erwartete Ergebnis US.swmal@xyz.com.
7 Test transformation Die RegexReplace()-Transformation wird nur ausgewertet, wenn der Wert des ausgewählten Benutzerattributs für Parameter 1 mit dem regulären Ausdruck übereinstimmt, der im Textfeld RegEx-Muster angegeben ist. Stimmen die Werte nicht überein, wird dem Token der Standardanspruchswert hinzugefügt. Um den regulären Ausdruck anhand des Eingabeparameterwerts zu überprüfen, steht eine Testumgebung auf dem Transformationsblatt zur Verfügung. Diese Testumgebung funktioniert nur für Dummywerte. Wenn weitere Eingabeparameter verwendet werden, wird dem Testergebnis der Name des Parameters anstelle des tatsächlichen Werts hinzugefügt. Um auf den Testabschnitt zuzugreifen, wählen Sie Testtransformation aus.

Die folgende Abbildung zeigt ein Beispiel zum Testen der Transformationen:

Screenshot: Testen der Transformation

Die folgende Tabelle enthält Informationen zum Testen der Transformationen. Die in der Tabelle aufgeführten Aktionen entsprechen den Bezeichnungen in der vorherigen Abbildung.

Aktion Feld BESCHREIBUNG
1 Test transformation Wählen Sie die Schaltfläche „Schließen“ (X) aus, um den Testabschnitt auszublenden und die Schaltfläche Testtransformation wieder auf dem Blatt anzuzeigen.
2 Test regex input Akzeptiert die Eingabe, die für die Testauswertung des regulären Ausdrucks verwendet wird. Falls die RegEx-basierte Anspruchstransformation als Transformation der zweiten Ebene konfiguriert ist, wird ein Wert angegeben, der die erwartete Ausgabe der ersten Transformation darstellt.
3 Run test Nachdem die RegEx-Testeingabe bereitgestellt und das RegEx-Muster, das Ersetzungsmuster und die Eingabeparameter konfiguriert wurden, kann der Ausdruck durch Auswählen von Test ausführen ausgewertet werden.
4 Test transformation result Wenn die Auswertung erfolgreich war, wird eine Ausgabe von Testtransformation mit der Bezeichnung Ergebnis der Testtransformation gerendert.
5 Remove transformation Die Transformation der zweiten Ebene kann entfernt werden, indem Sie Transformation entfernen auswählen.
6 Specify output if no match Wenn ein RegEx-Eingabewert für Parameter 1 konfiguriert wird, der nicht mit Regulärer Ausdruck übereinstimmt, wird die Transformation übersprungen. In solchen Fällen können Sie das alternative Benutzerattribut konfigurieren, das dem Token für den Anspruch hinzugefügt wird, indem Sie das Kontrollkästchen Ausgabe angeben, wenn keine Übereinstimmung vorliegt aktivieren.
7 Parameter 3 Falls ein alternatives Benutzerattribute zurückgegeben werden muss, wenn keine Übereinstimmung vorhanden ist und Ausgabe angeben, wenn keine Übereinstimmung vorliegt aktiviert ist, kann ein alternatives Benutzerattribute mithilfe der Dropdownliste ausgewählt werden. Dieses Dropdownmenü ist für Parameter 3 (Ausgabe bei Nichtübereinstimmung) verfügbar.
8 Summary Am unteren Rand des Blatts wird eine vollständige Zusammenfassung des Formats angezeigt, die die Bedeutung der Transformation in einfachem Text erläutert.
9 Add Nach der Überprüfung der Konfigurationseinstellungen für die Transformation kann diese in einer Anspruchsrichtlinie gespeichert werden, indem Sie Hinzufügen auswählen. Wählen Sie die Option Speichern auf dem Blatt Anspruch verwalten aus, um die Änderungen zu speichern.

Die RegexReplace()-Transformation ist auch für Gruppenanspruchstransformationen verfügbar.

Transformationsüberprüfungen

Eine Meldung liefert weitere Informationen, wenn die folgenden Bedingungen nach Auswahl von Hinzufügen oder Test ausführen auftreten:

  • Es wurden Eingabeparameter mit doppelten Benutzerattributen verwendet.
  • Nicht verwendete Eingabeparameter gefunden. Definierte Eingabeparameter sollten eine entsprechende Verwendung im Text des Ersetzungsmusters aufweisen.
  • Die bereitgestellte RegEx-Testeingabe stimmt nicht mit dem angegebenen regulären Ausdruck überein.
  • Für die Gruppen im Ersetzungsmuster wurden keine Quellen gefunden.

Ausgeben von Ansprüchen aufgrund von Bedingungen

Sie können die Anspruchsquelle auf Basis des Benutzertyps und der Gruppe, zu der der Benutzer gehört, angeben.

Folgende Benutzertypen stehen zur Auswahl:

  • Alle: Alle Benutzer dürfen auf die Anwendung zugreifen.
  • Mitglieder: Native Mitglieder des Mandanten
  • Alle Gäste: Benutzer*in wurde mit oder ohne Microsoft Entra ID aus einer externen Organisation verschoben.
  • Microsoft Entra-Gäste: Der Gastbenutzer gehört zu einer anderen Organisation mit Microsoft Entra ID.
  • Externe Gäste: Der Gastbenutzer gehört zu einer externen Organisation, die nicht über Microsoft Entra ID verfügt.

Der Benutzertyp ist hilfreich bei einem Szenario, bei dem sich die Anspruchsquelle für einen Gast und einen Mitarbeiter, die auf eine Anwendung zugreifen, unterscheidet. Sie können angeben, dass NameID aus „user.email“ erstellt wird, wenn es sich bei dem Benutzer um einen Mitarbeiter handelt. Wenn der Benutzer ein Gast ist, wird NameID aus „user.extensionattribute1“ erstellt.

So fügen Sie eine Anspruchsbedingung hinzu

  1. Erweitern Sie unter Anspruch verwalten die Anspruchsbedingungen.
  2. Wählen Sie den Benutzertyp aus.
  3. Wählen Sie die Gruppe(n) aus, zu der bzw. denen der Benutzer gehören soll. Sie können übergreifend über alle Ansprüche für eine bestimmte Anwendung bis zu 50 eindeutige Gruppen auswählen.
  4. Wählen Sie die Quelle aus, aus der der Anspruch den zugehörigen Wert abruft. Sie können ein Benutzerattribut aus der Dropdownliste für „Quellattribut“ auswählen oder eine Transformation auf das Benutzerattribut anwenden, bevor es als Anspruch ausgegeben wird.

Die Reihenfolge, in der Sie die Bedingungen hinzufügen, spielt eine wichtige Rolle. Microsoft Entra wertet zuerst alle Bedingungen mit der Quelle Attribute und dann alle Bedingungen mit der Quelle Transformation aus, um zu entscheiden, welcher Wert im Anspruch ausgegeben werden soll. Microsoft Entra ID wertet Bedingungen mit derselben Quelle von oben nach unten aus. Der Anspruch gibt den letzten Wert aus, der mit dem Ausdruck im Anspruch übereinstimmt. Transformationen wie IsNotEmpty und Contains fungieren wie Einschränkungen.

Beispiel: Britta Simon ist Gastbenutzer im Contoso-Mandanten. Britta gehört zu einer anderen Organisation, die ebenfalls Microsoft Entra ID verwendet. Wenn Britta bei der folgenden Konfiguration für die Fabrikam-Anwendung versucht, sich bei Fabrikam anzumelden, wertet Microsoft Identity Platform die Bedingungen aus.

Zuerst überprüft Microsoft Identity Platform, ob der Benutzertyp von Britta Alle Gäste lautet. Da der Typ Alle Gäste lautet, ordnet die Microsoft-Identitätsplattform die Quelle für den Anspruch user.extensionattribute1 zu. Als Nächstes überprüft Microsoft Identity Platform, ob der Benutzertyp von Britta Microsoft Entra-Gäste lautet. Da der Typ Alle Gäste lautet, ordnet die Microsoft-Identitätsplattform die Quelle für den Anspruch user.mail zu. Abschließend wird der Anspruch mit dem Wert user.mail für Britta ausgegeben.

Ein weiteres Beispiel: Britta Simon versucht, sich anzumelden, und sie verwendet die folgende Konfiguration. Microsoft Entra wertet zuerst alle Bedingungen mit der Quelle Attribute aus. Die Quelle für den Anspruch ist user.mail, wenn der Benutzertyp von Britta Microsoft Entra-Gäste lautet. Als Nächstes wertet Microsoft Entra ID die Transformationen aus. Da Britta Gast ist, ist user.extensionattribute1 jetzt die neue Quelle für den Anspruch. Da Britta sich in Microsoft Entra-Gäste befindet, ist user.othermail jetzt die neue Quelle für diesen Anspruch. Abschließend wird der Anspruch mit dem Wert user.othermail für Britta ausgegeben.

Als letztes Beispiel betrachten wir, was geschieht, wenn Britta den Wert user.othermail nicht konfiguriert hat oder dieser leer ist. Der Anspruch fällt auf user.extensionattribute1 zurück, wobei der Konditionseintrag in beiden Fällen ignoriert wird.

Sicherheitsüberlegungen

Anwendungen, die Token empfangen, verlassen sich auf Anspruchswerte, die nicht manipuliert werden können. Wenn Sie den Tokeninhalt durch eine Anspruchsanpassung ändern, sind diese Annahmen möglicherweise nicht mehr korrekt. Anwendungen müssen explizit bestätigen, dass Token geändert wurden, um sich vor Anpassungen zu schützen, die von böswilligen Akteuren erstellt wurden. Schützen Sie auf folgende Weise vor unangemessenen Anpassungen:

Ohne dies gibt Microsoft Entra ID den Fehlercode „AADSTS50146“ zurück.

Konfigurieren eines benutzerdefinierten Signaturschlüssels

Bei mehrinstanzenfähigen Apps sollte ein benutzerdefinierter Signaturschlüssel verwendet werden. Legen Sie acceptMappedClaims nicht im App-Manifest fest. Wenn Sie eine App im Azure-Portal einrichten, erhalten Sie ein App-Registrierungsobjekt und einen Dienstprinzipal in Ihrem Mandanten. Diese App verwendet den globalen Azure-Anmeldeschlüssel, der nicht zum Anpassen von Ansprüchen in Token verwendet werden kann. Um benutzerdefinierte Ansprüche in Token abzurufen, erstellen Sie einen benutzerdefinierten Anmeldeschlüssel aus einem Zertifikat, und fügen Sie ihn dem Dienstprinzipal hinzu. Sie können zu Testzwecken ein selbstsigniertes Zertifikat verwenden. Nachdem Sie den benutzerdefinierten Signaturschlüssel konfiguriert haben, muss Ihr Anwendungscode den Tokensignaturschlüssel überprüfen.

Fügen Sie dem Dienstprinzipal die folgenden Informationen hinzu:

Extrahieren Sie den Base64-codierten privaten und öffentlichen Schlüssel aus dem PFX-Dateiexport Ihres Zertifikats. Stellen Sie sicher, dass die für „Sign“ verwendete keyId für keyCredential mit der keyId von passwordCredential übereinstimmt. Sie können customkeyIdentifier generieren, indem Sie den Hash des Zertifikatfingerabdrucks abrufen.

Anforderung

Hinweis

Deaktivieren Sie zuerst eine Dienstprinzipalsperrkonfiguration für neu erstellte Apps vom Blatt „Microsoft Entra Admin Center-App-Registrierungen“, bevor Sie versuchen, einen PATCH für den Dienstprinzipal durchzuführen, was zu einer 400 ungültigen Anforderung führt.

Das folgende Beispiel zeigt das Format der HTTP PATCH-Anforderung zum Hinzufügen eines benutzerdefinierten Signaturschlüssels zu einem Dienstprinzipal. Der Wert „key“ in der keyCredentials-Eigenschaft wird zur besseren Lesbarkeit gekürzt. Der Wert ist Base64-codiert. Für den privaten Schlüssel wird die Eigenschaft Sign verwendet. Für den öffentlichen Schlüssel wird die Eigenschaft Verify verwendet.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/aaaaaaaa-bbbb-cccc-1111-222222222222

Content-type: servicePrincipals/json
Authorization: Bearer {token}

{
    "keyCredentials":[
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=", 
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "X509CertAndPassword",
            "usage": "Sign",
            "key":"cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        },
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "bbbbbbbb-1c1c-2d2d-3e3e-444444444444",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        }

    ],
    "passwordCredentials": [
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "keyId": "cccccccc-2d2d-3e3e-4f4f-555555555555",
            "endDateTime": "2022-01-27T19:40:33Z",
            "startDateTime": "2020-04-20T19:40:33Z",
            "secretText": "mypassword"
        }
    ]
}

Konfigurieren eines benutzerdefinierten Signaturschlüssels mit PowerShell

Verwenden Sie PowerShell, um eine öffentliche MSAL-Clientanwendung zu instanziieren, und verwenden Sie die Autorisierungscodegenehmigung, um ein Zugriffstoken für die delegierte Berechtigung für Microsoft Graph abzurufen. Verwenden Sie das Zugriffstoken, um Microsoft Graph aufzurufen, und konfigurieren Sie einen benutzerdefinierten Signaturschlüssel für den Dienstprinzipal. Nachdem Sie den benutzerdefinierten Signaturschlüssel konfiguriert haben, muss Ihr Anwendungscode den Tokensignaturschlüssel überprüfen.

Sie benötigen folgende Komponenten, um das Skript auszuführen:

  • Die Objekt-ID des Dienstprinzipals Ihrer Anwendung, die sich auf dem Blatt Übersicht des Eintrags Ihrer Anwendung in Unternehmensanwendungen im Azure-Portal befindet
  • Eine App-Registrierung zum Anmelden eines Benutzers und Abrufen des Zugriffstokens zum Aufrufen der Microsoft Graph-API. Rufen Sie die Anwendungs-ID (Client-ID) der App im Azure-Portal über das Blatt Übersicht des Eintrags Ihrer Anwendung unter App-Registrierungen ab. Die App-Registrierung sollte die folgende Konfiguration aufweisen:
    • Umleitungs-URI „http://localhost"“, der in der Plattformkonfiguration Mobile Anwendungen und Desktopanwendungen aufgeführt ist
    • Delegierte Microsoft Graph-Berechtigungen (Application.ReadWrite.All und User.Read) in API-Berechtigungen aufgeführt sind (diese Berechtigungen müssen die Administratoreinwilligung umfassen)
  • Einen Benutzer, der sich anmeldet, um das Microsoft Graph-Zugriffstoken abzurufen. Der Benutzer oder die Benutzerin muss eine der folgenden Microsoft Entra-Administratorrollen besitzen (zum Aktualisieren des Dienstprinzipals erforderlich):
    • Cloudanwendungsadministrator
    • Anwendungsadministrator
  • Ein Zertifikat, das als benutzerdefinierter Signaturschlüssel für unsere Anwendung konfiguriert werden soll. Sie können entweder ein selbstsigniertes Zertifikat erstellen oder eines von Ihrer vertrauenswürdigen Zertifizierungsstelle beziehen. Die folgenden Zertifikatkomponenten werden im Skript verwendet:
    • Öffentlicher Schlüssel (in der Regel eine CER-Datei)
    • Privater Schlüssel im PKCS#12-Format (in PFX-Datei)
    • Kennwort für den privaten Schlüssel (PFX-Datei)

Wichtig

Der private Schlüssel muss im PKCS#12-Format vorliegen, da Microsoft Entra ID keine anderen Formattypen unterstützt. Die Verwendung eines falschen Formats kann zum Fehler „Ungültiges Zertifikat: Schlüsselwert ist ungültiges Zertifikat.“ führen, wenn Microsoft Graph zum Ausführen eines PATCH-Vorgangs für den Dienstprinzipal mit einem keyCredentials-Element verwendet wird, das die Zertifikatinformationen enthält.

##########################################################
# Replace the variables below with the appropriate values 

$fqdn="yourDomainHere" # This is used for the 'issued to' and 'issued by' field of the certificate
$pwd="password" # password for exporting the certificate private key
$tenantId   = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Replace with your Tenant ID
$appObjId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" # Replace with the Object ID of the App Registration

##########################################################

# Create a self-signed cert

$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
$cerFile = $location + "\\" + $fqdn + ".cer"
$pfxFile = $location + "\\" + $fqdn + ".pfx"
 
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile

$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$password = $pwd  # password for the pfx file
 
# Check PowerShell version (minimum 5.1) (.Net) or PowerShell Core (.Net Core) and read the certificate file accordingly
 
if ($PSVersionTable.PSVersion.Major -gt 5)
    { 
        $core = $true
    }
else
    { 
        $core = $false
    }
 
    #  this is for PowerShell Core
    $Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
 
    # reading certificate files and creating Certificate Object
    if ($core)
    {
        $pfx_cert = get-content $pfxpath -AsByteStream -Raw
        $cer_cert = get-content $cerpath -AsByteStream -Raw
        $cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
    }
    else
    {
        $pfx_cert = get-content $pfxpath -Encoding Byte
        $cer_cert = get-content $cerpath -Encoding Byte
        # calling Get-PfxCertificate in PowerShell 5.1 prompts for password - using alternative method
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
    }

 
    # base 64 encode the private key and public key
    $base64pfx = [System.Convert]::ToBase64String($pfx_cert)
    $base64cer = [System.Convert]::ToBase64String($cer_cert)
 
    # getting id for the keyCredential object
    $guid1 = New-Guid
    $guid2 = New-Guid
 
    # get the custom key identifier from the certificate thumbprint:
    $hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
    $hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
    $customKeyIdentifier = [System.Convert]::ToBase64String($hash)
 
    # get end date and start date for our keycredentials
    $endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
    $startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
 
    # building our json payload
    $object = [ordered]@{    
    keyCredentials = @(       
         [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid1
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Sign"
            key = $base64pfx
            displayName = "CN=$fqdn" 
        },
        [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid2
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Verify"
            key = $base64cer
            displayName = "CN=$fqdn"   
        }
        )  
    passwordCredentials = @(
        [ordered]@{
            customKeyIdentifier = $customKeyIdentifier
            displayName = "CN=$fqdn"
            keyId = $guid1           
            endDateTime = $endDateTime
            startDateTime = $startDateTime
            secretText = $password
            hint = $null
        }
    )
    }
 
Connect-MgGraph -tenantId $tenantId -Scopes Application.ReadWrite.All
$graphuri = "https://graph.microsoft.com/v1.0/applications/$appObjId"
Invoke-MgGraphRequest -Method PATCH -Uri $graphuri -Body $object

    $json = $object | ConvertTo-Json -Depth 99
    Write-Host "JSON Payload:"
    Write-Output $json

Überprüfen des Tokensignaturschlüssels

Apps mit aktivierter Anspruchszuordnung müssen ihre Tokensignaturschlüssel überprüfen, indem sie appid={client_id} an ihre OpenID Connect-Metadatenanforderungen anfügen. Das folgende Beispiel zeigt das Format des OpenID Connect-Metadatendokuments, das Sie verwenden sollten:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

Aktualisieren des Anwendungsmanifests

Alternativ können Sie für einzelne Mandantenanwendungen die acceptMappedClaims-Eigenschaft im Anwendungsmanifest auf true festlegen. Wie im apiApplication-Ressourcentyp dokumentiert. Durch das Festlegen der Eigenschaft kann eine Anwendung die Anspruchszuordnung verwenden, ohne einen benutzerdefinierten Signaturschlüssel anzugeben.

Warnung

Legen Sie die acceptMappedClaims-Eigenschaft für mehrmandantenfähige Apps nicht auf TRUE fest. Dies kann dazu führen, dass böswillige Akteure Anspruchszuordnungsrichtlinien für Ihre App erstellen.

Die angeforderte Tokenzielgruppe muss einen verifizierten Domänennamen Ihres Microsoft Entra-Mandanten verwenden. Das bedeutet, dass Sie Application ID URI (im Anwendungsmanifest durch identifierUris dargestellt) beispielsweise auf https://contoso.com/my-api oder https://contoso.onmicrosoft.com/my-api (unter Verwendung des Standardmandantennamens) festlegen müssen.

Wenn Sie keine überprüfte Domäne verwenden, gibt Microsoft Entra ID einen AADSTS501461-Fehlercode mit folgender Meldung aus: „_AcceptMappedClaims wird nur für eine Tokenzielgruppe, die mit der Anwendungs-GUID übereinstimmt, oder für eine Zielgruppe innerhalb der überprüften Domänen des Mandanten unterstützt. Ändern Sie entweder den Ressourcenbezeichner, oder verwenden Sie einen anwendungsspezifischen Signaturschlüssel.“

Erweiterte Anspruchsoptionen

Konfigurieren Sie erweiterte Anspruchsoptionen für OIDC-Anwendungen, um den gleichen Anspruch wie SAML-Token verfügbar zu machen. Ebenfalls für Anwendungen, die denselben Anspruch sowohl für SAML2.0- als auch für OIDC-Antwort-Tokens verwenden wollen.

Erweiterte Anspruchsoptionen können konfiguriert werden, indem Sie das Kontrollkästchen Erweiterte Anspruchsoptionen auf dem Blatt Ansprüche verwalten aktivieren.

Zugehöriger Inhalt