Wann sollten Sie eine Transformationsanspruchsregel verwenden?

  • Artikel

Sie können diese Regel in Active Directory-Verbunddienste (AD FS) verwenden, wenn Sie einen eingehenden Anspruchstyp einem ausgehenden Anspruchstyp zuordnen müssen und dann eine Aktion anwenden, die bestimmt, welche Ausgabe auf der Basis der Werte erfolgen soll, die aus dem eingehenden Anspruch stammen. Wenn Sie diese Regel verwenden, leiten Sie Ansprüche weiter bzw. transformieren Sie Ansprüche, die der folgenden Regellogik entsprechen. Dies geschieht auf Basis der Optionen, die Sie in der Regel konfigurieren, wie in der folgenden Tabelle beschrieben.

Regeloption Regellogik
Alle eingehenden Ansprüche weiterleiten Wenn der eingehende Anspruchstyp dem angegebenen Anspruchstyp und der Wert einem beliebigen Wert entspricht, leiten Sie den Anspruch mit einem ausgehenden Anspruchstyp weiter, der dem angegebenen Anspruchstyp entspricht.
Ersetzen Sie einen eingehenden Anspruchswert durch einen anderen ausgehenden Anspruchswert Wenn der eingehende Anspruchstyp dem angegebenen Anspruchstyp und der Wert dem angegebenen Anspruchswert entspricht, transformieren Sie den Anspruch mit einem neuen ausgehenden Anspruchswert, der dem angegebenen Anspruchswert entspricht, und mit einem ausgehenden Anspruchstyp, der dem angegebenen Anspruchstyp entspricht.
Eingehende E-Mail-Suffixansprüche durch ein neues E-Mail-Suffix ersetzen Wenn der eingehende Anspruchstyp dem angegebenen Anspruchstyp und der Wert einem beliebigen Suffixwert entspricht, transformieren Sie den Anspruch mit einem neuen ausgehenden Anspruchswert, der dem angegebenen Suffixwert entspricht, und mit einem ausgehenden Anspruchstyp, der dem angegebenen Anspruchstyp entspricht.

Die folgenden Abschnitte enthalten eine grundlegende Einführung in Anspruchsregeln und bieten weitere Details zur Verwendung dieser Regeln.

Informationen zu Anspruchsregeln

Eine Anspruchsregel stellt eine Instanz der Geschäftslogik dar, die auf einen eingehenden Anspruch eine Bedingung anwendet (wenn x, dann y) und auf der Grundlage der Bedingungsparameter einen ausgehenden Anspruch erzeugt. Die folgende Liste enthält wichtige Tipps zu Anspruchsregeln, die Sie kennen sollten, bevor Sie fortfahren, dieses Thema zu lesen:

  • Im AD FS-Verwaltungs-Snap-In können Anspruchsregeln nur mit Anspruchsregelvorlagen erstellt werden.

  • Anspruchsregeln verarbeiten eingehende Ansprüche entweder direkt von einem Anspruchsanbieter (wie Active Directory oder einem anderen Verbunddienst) oder von der Ausgabe der Akzeptanztransformationsregeln in einer Anspruchsanbietervertrauensstellung aus.

  • Anspruchsregeln werden von der Anspruchsausstellungs-Engine chronologisch nach einem bestimmten Regelsatz verarbeitet. Indem Sie eine Rangfolge der Regeln festlegen, können Sie Ansprüche, die durch vorausgehende Regeln in einem bestimmten Regelsatz generiert werden, weiter optimieren oder filtern.

  • Anspruchsregelvorlagen erfordern immer, dass Sie einen eingehenden Anspruchstyp angeben. Allerdings können Sie mehrere Anspruchswerte mit den gleichen Anspruchstyp mithilfe einer einzigen Regel verarbeiten.

Ausführlichere Informationen zu Anspruchsregeln und Anspruchsregelsätzen finden Sie unter Die Rolle von Anspruchsregeln. Weitere Informationen dazu, wie Regeln verarbeitet werden, finden Sie unter Die Rolle der Anspruchs-Engine. Weitere Informationen dazu, wie Anspruchsregelsätze verarbeitet werden, finden Sie unter Die Rolle der Anspruchspipeline.

Alle Anspruchswerte weiterleiten

Wenn Sie diese Aktion verwenden, werden alle eingehenden Anspruchswerte, die auf einen angegebenen eingehenden Anspruchstyp abgestimmt sind, einem angegebenen ausgehenden Anspruchstyp zugeordnet, bevor sie als ausgehende Ansprüche in Tokens gesendet werden, die durch den Verbunddienst signiert sind.

Wenn eine Regel z. B. mit der Optionslogik Alle Anspruchswerte weiterleiten festgelegt und der eingehende Anspruchstyp "Gruppe" und der ausgehende Anspruchstyp "Rolle" angegeben ist, werden alle eingehenden Anspruchswerte, die vom Aussteller einfließen, einzeln mit dem Anspruchstyp "Rolle" in neue ausgehende Ansprüche kopiert.

Transformieren eines Anspruchs

In AD FS bezeichnet der Begriff Anspruchstransformation das Ersetzen eines eingehenden Anspruchswerts durch einen anderen ausgehenden Anspruchswert. Die Regel zum Transformieren eines eingehenden Anspruchs macht diese Funktion möglich. Im Rahmen der Eigenschaften dieser Regel können Sie Bedingungen zum Transformieren eines eingehenden Werts mit einem anderen ausgehenden Anspruchswert auf der Basis des angegebenen eingehenden Anspruchstyps festlegen.

Wenn beispielsweise, wie in der folgenden Abbildung gezeigt, eine Regel mit der Bedingung festgelegt wird, einen eingehenden Wert durch einen anderen ausgehenden Anspruchswert zu ersetzen, werden alle eingehenden Anspruchstypen "Group" neuen ausgehenden Anspruchstypen "Role" zugeordnet. In diesem Fall wird der eingehenden Anspruchswert "Purchaser" durch den neuen ausgehenden Anspruchswert "Admin" ersetzt.

when to use a transform

Mit dieser Regel können Sie auch eine Bedingung anwenden, die alle eingehenden Ansprüche mit einem bestimmten E-Mail-Suffixwert durch einen neuen Wert ersetzt. Sie könnten z. B. in dieser Regel eine Bedingung zum Ändern aller Anspruchswerte mit dem Suffix "sales.corp.fabrikam.com" in "fabrikam.com" festlegen.

Konfigurieren diese Regel in einer Anspruchsanbietervertrauensstellung

Bei Verwendung einer Anspruchsanbietervertrauensstellung kann diese Regel zum Transformieren eingehender Ansprüche vom Anspruchsanbieter in vertrauenswürdige Äquivalente konfiguriert werden. Anspruchstypen oder Anspruchswerte können in Ihrer Organisation eine andere Bedeutung als in den Organisationen der Anspruchsanbieter haben. Mit dieser Regel können Sie die Anspruchstypen und -Werte normalisieren, die vom Anspruchsanbieter stammen, sodass ihre ausgehenden Anspruchsäquivalente von der vertrauenden Seite verstanden werden.

Konfigurieren diese Regel in einer Vertrauensstellung der vertrauenden Seite

Wenn Sie eine Vertrauensstellung der vertrauenden Seite verwenden, kann diese Regel zum Transformieren von Ansprüchen für die bestimmte vertrauende Seite konfiguriert werden. Anspruchstypen oder -werte können für eine bestimmte vertrauende Seite eine andere Bedeutung haben, und diese Regel ermöglicht Ihnen, die ausgehenden Anspruchstypen und -werte für eine einzelne vertrauende Seite zu ändern.

Erstellen dieser Regel

Sie erstellen diese Regel entweder mithilfe der Anspruchsregelsprache oder der Regelvorlage Transformieren eines eingehenden Anspruchs im Snap-In „Verwaltung“ von AD FS. Diese Regelvorlage bietet die folgenden Konfigurationsoptionen:

  • Angeben eines Anspruchsregelnamens

  • Transformieren eines bestimmten eingehenden Anspruchstyps in einen bestimmten ausgehenden Anspruchstyp

  • Alle Anspruchswerte weiterleiten

  • Ersetzen Sie einen eingehenden Anspruchswert durch einen anderen ausgehenden Anspruchswert

  • Ersetzen eingehender E-Mail-Suffixansprüche durch ein neues E-Mail-Suffix

Weitere Anweisungen zum Erstellen dieser Vorlage finden Sie unter Erstellen einer Regel zum Transformieren eines eingehenden Anspruchs im AD FS-Bereitstellungsleitfaden.

Verwenden der Anspruchsregelsprache

Wenn der ausgehende Anspruch aus dem Inhalt mehrerer eingehender Ansprüche erstellt werden muss, müssen Sie stattdessen eine benutzerdefinierte Regel verwenden. Wenn der Anspruchswert des ausgehenden Anspruchs auf dem Wert des eingehenden Anspruchs basieren muss – jedoch mit zusätzlichem Inhalt – müssen Sie auch in diesem Kontext eine benutzerdefinierte Regel verwenden. Weitere Informationen finden Sie unter When to Use a Custom Claim Rule.

Beispiele zum Erstellen einer Transformationsregelsyntax

Bei Verwendung der Anspruchsregel-Sprachsyntax zum Transformieren von Ansprüchen können Sie für eine Eigenschaft des transformierten Anspruchs einen neuen literalen Wert festlegen. Beispielsweise ändert die folgende Regel unter Beibehaltung des Anspruchstyps den Wert der Rollenansprüche von „Administrators“ in „Root“:

c:[type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/role", value == "Administrators"]  => issue(type = c.type, value = "root");

Reguläre Ausdrücke können auch für Anspruchstransformationen verwendet werden. Mit der folgenden Regel wird z. B. die Domäne in Windows-Benutzernamenansprüchen im Format DOMAIN\USER auf FABRIKAM festgelegt:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"] => issue(type = c.type, value = regexreplace(c.value, "(?<domain>[^\\]+)\\(?<user>.+)", "FABRIKAM\${user}"));

Bewährte Methoden zum Erstellen benutzerdefinierter Regeln

Anspruchstransformationen können mithilfe grundlegender Filterfunktionen selektiv auf ausgewählte Ansprüche angewendet werden. Jeder der zum Filtern verwendeten Anspruchseigenschaften können Werte zugewiesen werden, jedoch mit folgenden Vorsichtsmaßnahmen:

Anspruchseigenschaft BESCHREIBUNG
Type, Value, ValueType Diese Eigenschaften werden am häufigsten für Zuweisungen verwendet. Für den resultierenden transformierten Anspruch müssen zumindest Typ und Wert angegeben werden.
Issuer (Aussteller) Die Anspruchsregelsprache erlaubt zwar, den Aussteller eines Anspruchs festzulegen, jedoch wird dies im Allgemeinen nicht empfohlen. Der Aussteller eines Anspruchs ist im Token nicht serialisiert. Beim Empfang eines Tokens wird die Eigenschaft "Issuer" aller Ansprüche auf den Bezeichner des Verbundservers festgelegt, der das Token signiert hat. Folglich hat das Festlegen des Ausstellers eines Anspruchs in den Regeln keinen Einfluss auf den Inhalt des Tokens, und die Einstellung geht verloren, sobald der Anspruch in einem Token verpackt wird. Das einzige Szenario, in dem das Festlegen des Ausstellers eines Anspruchs sinnvoll ist, liegt vor, wenn er im Anspruchsanbieter-Regelsatz auf einen bestimmten Wert gesetzt ist, und der Regelsatz der vertrauenden Seite mit Regeln erstellt ist, die auf diesen bestimmten Wert verweisen. Wenn die Eigenschaft „Issuer“ nicht explizit auf einen Wert in einer Anspruchsregel festgelegt ist, legt die Anspruchsausstellungs-Engine sie auf LOCAL AUTHORITY fest.
OriginalIssuer Genau wie "Issuer" sollte "OriginalIssuer" im Allgemeinen nicht explizit ein Wert zugewiesen werden. Im Gegensatz zu "Issuer" wird die Eigenschaft "OriginalIssuer" im Token serialisiert, aber Tokennutzer gehen davon aus, dass sie, sofern festgelegt, den Bezeichner des Verbundservers enthält, der ursprünglich einen Anspruch ausgestellt hat.
Eigenschaften Wie im vorherigen Abschnitt beschrieben, wird die Eigenschaftensammlung eines Anspruchs im Token nicht beibehalten, sodass Zuweisungen zu Eigenschaften nur erfolgen sollten, wenn die nachfolgenden lokalen Richtlinien auf die in der Eigenschaft gespeicherten Informationen verweisen.

Weitere Informationen zur Verwendung der Anspruchsregelsprache finden Sie unter Die Rolle der Anspruchsregelsprache.