Rolle der Anspruchsregelsprache

  • Artikel

Die Anspruchsregelsprache in den Active Directory-Verbunddiensten (AD FS) dient als administrativer Baustein für das Verhalten von eingehenden und ausgehenden Ansprüchen. Die Anspruchs-Engine fungiert als Verarbeitungs-Engine für die Logik in der Anspruchsregelsprache, in der die benutzerdefinierte Regel definiert ist. Weitere Informationen dazu, wie die Regeln von der Anspruchs-Engine verarbeitet werden, finden Sie unter Rolle der Anspruchs-Engine.

Erstellen benutzerdefinierter Anspruchsregeln mithilfe der Anspruchsregelsprache

AD FS bietet Administratoren die Möglichkeit, benutzerdefinierte Regeln zu definieren, über die sie das Verhalten von Identitätsansprüchen mit der Anspruchsregelsprache bestimmen können. Mithilfe der Syntaxbeispiele für die Anspruchsregelsprache in diesem Thema können Sie benutzerdefinierte Regeln erstellen, die Ansprüche gemäß der Anforderungen Ihrer Organisation aufzählen, hinzufügen, löschen oder modifizieren. Benutzerdefinierte Regeln können durch Eingabe eines Syntaxausdrucks der Anspruchsregelsprache in die Regelvorlage Ansprüche mit einem benutzerdefinierten Anspruch senden erstellt werden.

Regeln werden durch Semikolons voneinander getrennt.

Weitere Informationen dazu, wann benutzerdefinierte Regeln verwendet werden können, finden Sie unter Wann sollte eine benutzerdefinierte Anspruchsregel verwendet werden?.

Verwenden von Anspruchsregelvorlagen zum Erlernen der Syntax der Anspruchsregelsprache

AD FS bietet außerdem eine Reihe vordefinierter Regelvorlagen für das Ausstellen und Akzeptieren von Ansprüchen, mit deren Hilfe Sie gängige Anspruchsregeln implementieren können. Mithilfe des Dialogfelds Anspruchsregeln bearbeiten lassen sich vordefinierte Regeln erstellen, wobei auch die zugrundeliegende Syntax der Anspruchsregelsprache angezeigt wird, indem Sie auf die Registerkarte Regelsprache anzeigen für diese Regel klicken. Mithilfe der Informationen in diesem Abschnitt und der Hilfestellung durch die Funktion Regelsprache anzeigen lässt sich das Erstellen eigener, benutzerdefinierter Regeln erschließen.

Ausführlichere Informationen zu Anspruchsregeln und Anspruchsregelvorlagen finden Sie unter Rolle von Anspruchsregeln.

Grundlegendes zu den Komponenten der Anspruchsregelsprache

Die Anspruchsregelsprache besteht aus den folgenden, durch den Operator „=>“ getrennten Komponenten:

  • Eine Bedingung

  • Eine Ausstellungsanweisung

Bedingungen

Die Bedingungen dienen in einer Regel dazu, Eingabeansprüche zu überprüfen und zu bestimmen, ob die Ausstellungsanweisung der Regel ausgeführt werden soll. Eine Bedingung stellt einen logischen Ausdruck dar, dessen Auswertung „true“ ergeben muss, damit der Hauptteil der Regel ausgeführt wird. Wenn dieser Teil fehlt, wird der logische Wert „true“ angenommen, d. h., der Hauptteil der Regel wird in diesem Fall immer ausgeführt. Der Bedingungsteil enthält eine Liste von Bedingungen, die mit dem logischen Konjunktionsoperator (“&&”) kombiniert werden. Alle Bedingungen in der Liste müssen „true“ ergeben, damit der Bedingungsteil insgesamt „true“ ergibt. Die Bedingung kann entweder ein Anspruchsselektoroperator oder ein zusammengesetzter Funktionsaufruf sein. Diese beiden Möglichkeiten schließen sich gegenseitig aus – Anspruchsselektoren und zusammengesetzte Funktionen lassen sich nicht im Bedingungsteil derselben Regel verwenden.

Bedingungen sind in Regeln optional. Beispielsweise besitzt die folgende Regel keine Bedingung:

=> issue(type = "http://test/role", value = "employee");

Es gibt drei Arten von Bedingungen:

  • Einzelbedingung – dies ist die einfachste Form einer Bedingung. Es wird nur nach einem einzigen Ausdruck gesucht, z. B. „windows account name = domain user“.

  • Mehrfachbedingung – dieser Bedingungstyp erfordert zusätzliche Überprüfungen, um mehrere Ausdrücke im Hauptteil der Regel zu verarbeiten, beispielsweise „windows account name = domain user and group = contosopurchasers“.

Hinweis

Es gibt einen weiteren Bedingungstyp, der jedoch Bestandteil von Einzelbedingungen und Mehrfachbedingungen sein kann. Dieser Bedingungstyp wird als regulärer Ausdruck (Regex) bezeichnet. Dabei wird ein Eingabeausdruck mit einem festgelegten Muster verglichen. Ein Verwendungsbeispiel wird unten gezeigt.

Die folgenden Beispiele zeigen einige Syntaxformen, die aus den drei Bedingungstypen bestehen, aus denen benutzerdefinierte Regeln erstellt werden können.

Beispiele für Einzelbedingungen

Bedingungen mit einzelnen Ausdrücken werden in der folgenden Tabelle beschrieben. Sie sind so aufgebaut, dass lediglich ein Anspruch mit einem bestimmten Anspruchstyp verglichen wird oder ein Anspruch mit einem bestimmten Anspruchstyp und einem zugehörigem Anspruchswert.

Beschreibung der Bedingung Syntaxbeispiel der Bedingung
Diese Regel enthält eine Bedingung, bei der nach einem Eingabeanspruch mit einem angegebenen Anspruchstyp („<http://test/name>“) gesucht wird. Wenn ein passender Anspruch in den Eingabeansprüchen vorhanden ist, kopiert die Regel den passenden Anspruch bzw. die Ansprüche in die Menge der Ausgabeansprüche. c: [type == "http://test/name"] => issue(claim = c );
Diese Regel enthält eine Bedingung, bei der nach einem Eingabeanspruch mit einem angegebenen Anspruchstyp („<http://test/name>“) und einem Anspruchswert („Terry“) gesucht wird. Wenn ein passender Anspruch in den Eingabeansprüchen vorhanden ist, kopiert die Regel den passenden Anspruch bzw. die Ansprüche in die Menge der Ausgabeansprüche. c: [type == "http://test/name", value == "Terry"] => issue(claim = c);

Im nächsten Abschnitt werden komplexere Bedingungen gezeigt, beispielsweise solche, bei denen nach mehreren Ansprüche gesucht wird, bei denen der Aussteller des Anspruchs überprüft wird oder bei denen nach Werten gesucht wird, die mit dem Muster eines regulären Ausdrucks übereinstimmen.

Beispiele für mehrere Bedingungen

Die folgende Tabelle enthält ein Beispiel für Bedingungen mit mehreren Ausdrücken.

Beschreibung der Bedingung Syntaxbeispiel der Bedingung
Diese Regel enthält eine Bedingung, bei der nach zwei Eingabeansprüchen gesucht wird, die jeweils einen angegebenen Anspruchstyp aufweisen („<http://test/name>“ und „<http://test/email>“). Wenn die zwei übereinstimmenden Ansprüche in den Eingabeansprüchen vorhanden sind, kopiert die Regel den Namensanspruch in die Menge der Ausgabeansprüche. c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 );

Beispiele für Bedingungen mit regulären Ausdrücken

Die folgende Tabelle zeigt ein Beispiel, in dem die Bedingung einen regulären Ausdruck enthält.

Beschreibung der Bedingung Syntaxbeispiel der Bedingung
Diese Regel enthält eine Bedingung, die einen regulären Ausdruck verwendet, um nach einem E-Mail-Anspruch zu suchen, der auf „@fabrikam.com“ endet. Wenn ein übereinstimmender Anspruch in den Eingabeansprüchen gefunden wird, kopiert die Regel den übereinstimmenden Anspruch in den Ausgabeanspruchssatz. c: [type == "http://test/email", value =~ "^. +@fabrikam.com$" ] => issue (claim = c );

Ausstellungsanweisungen

Benutzerdefinierte Regeln werden anhand der Ausstellungsanweisungen (issue oder add) verarbeitet, die Sie in die Anspruchsregeln programmieren. Abhängig vom gewünschten Ergebnis kann entweder die „issue“-Anweisung (Ausgeben) oder die „add“-Anweisung (Hinzufügen) in die Regel geschrieben werden, um den Eingabeanspruchssatz oder den Ausgabeanspruchssatz zu besetzen. Eine benutzerdefinierte Regel, die explizit die „add“-Anweisung verwendet, fügt Anspruchswerte nur in den Eingabeanspruchssatz ein, während eine benutzerdefinierte Regel, die explizit die „issue“-Anweisung verwendet, Anspruchswerte sowohl in den Eingabeanspruchssatz als auch in den Ausgabeanspruchssatz einfügt. Dies kann nützlich sein, wenn ein Anspruchswert nur von darauffolgenden Regeln in den Anspruchsregelsätzen verwendet werden soll.

In der folgenden Abbildung wird beispielsweise der eingehende Anspruch durch die Anspruchsausgabe-Engine dem Eingabeanspruchssatz hinzugefügt. Wenn die erste benutzerdefinierte Anspruchsregel ausgeführt wird und das Kriterium „domain user“ erfüllt ist, verarbeitet die Anspruchsausgabe-Engine die Logik der Regel mithilfe der add-Anweisung, und der Wert Editor wird dem Eingabeanspruchssatz hinzugefügt. Da der Wert von „Editor“ im Eingabeanspruchssatz vorhanden ist, kann Regel 2 die Ausstellungsanweisung ihrer Logik erfolgreich ausführen und den neuen Wert Hello erzeugen, der sowohl dem Ausgabeanspruchssatz als auch dem Eingabeanspruchssatz für die nächste Regel in der Regelmenge hinzugefügt wird. Regel 3 kann nun alle Ansprüche im Eingangsanspruchssatz als Eingabe für die Verarbeitung der Logik verwenden.

AD FS roles

Anspruchsausstellungsaktionen

Der Hauptteil der Regel stellt eine Anspruchsausstellungsaktion dar. Die Sprache erkennt zwei Anspruchsausstellungsaktionen:

  • „issue“-Anweisung: Die „issue“-Anweisung erstellt einen Anspruch, der sowohl in den Eingabeanspruchssatz als auch in den Ausgabeanspruchssatz kopiert wird. Die folgende Anweisung stellt beispielsweise eine neue Anforderung anhand ihres Eingabeanspruchssatzes aus.

    c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);

  • „add“-Anweisung: Die „add“-Anweisung erstellt eine neue Anforderung, die nur dem Eingabeanspruchssatz hinzugefügt wird. Die folgende Anweisung fügt z. B. dem Eingabeanspruchssatz einen neuen Anspruch hinzu:

    c:[type == "Name", value == "domain user"] => add(type = "Role", value = "Editor");

Die „issue“-Anweisung definiert, welche Ansprüche durch die Regel ausgegeben werden, wenn die Bedingungen zutreffen. Es gibt zwei Formen der „issue“-Anweisung, die sich durch die Anzahl der Argumente und das Verhalten der Anweisung unterscheiden:

  • Normal: Normale „issue“-Anweisungen können Ansprüche ausgeben, wenn die Regel mithilfe von Literalwerten formuliert ist oder die Werte direkt in übereinstimmenden Ansprüchen zu finden sind. Eine normale „issue“-Anweisung besteht aus einem oder beiden der folgenden Formate:

    • Anspruchskopie: Bei der Anspruchskopie wird eine Kopie des vorhandenen Anspruchs in den Ausgabeanspruchssatz kopiert. Diese Form der Ausstellung ist nur in Kombination mit der Ausstellungsanweisung „issue“ sinnvoll. In Kombination mit der Ausstellungsanweisung „add“ hat sie keinerlei Auswirkung.

    • Neuer Anspruch: Dieses Format erstellt anhand der Werte verschiedener Anspruchseigenschaften einen neuen Anspruch. „Claim.Type“ muss angegeben werden, alle anderen Anspruchseigenschaften sind optional. Die Reihenfolge der Argumente wird in dieser Form ignoriert.

  • Attributspeicher: Bei dieser Form werden Ansprüche mit Werten erstellt, die von einem Attributspeicher abgerufen werden. Mehrere Anspruchstypen können mithilfe einer einzelnen Ausstellungsanweisung erstellt werden – dies ist für Attributspeicher wichtig, die während des Attributabrufs E/A-Vorgänge für Netzwerk oder Laufwerk durchführen. Daher ist es wünschenswert, die Anzahl der Roundtrips zwischen der Richtlinien-Engine und dem Attributspeicher zu begrenzen. Es ist auch zulässig, für einen Anspruchstyp jeweils mehrere Ansprüche zu erstellen. Wenn der Attributspeicher mehrere Werte für einen Anspruchstyp zurückliefert, erstellt die Ausstellungsanweisung automatisch einen Anspruch für jeden Anspruchswert. Ein Mechanismus des Attributspeichers ersetzt die Platzhalter im Abfrageargument durch die Parameterargumente. Die Platzhalter verwenden dieselbe Syntax wie die .NET String.Format()-Funktion (z. B. {1}, {2} usw.). Die Reihenfolge der Argumente für diese Art der Ausstellung ist wichtig, und es muss die in der folgenden Grammatik vorgeschriebene Reihenfolge sein.

Die folgende Tabelle beschreibt einige allgemeine Syntaxkonstruktionen für beide Ausstellungsanweisungen in Anspruchsregeln.

Ausstellungsanweisungstyp Beschreibung der Ausstellungsanweisung Syntaxbeispiel für Ausstellungsanweisung
Normal Die folgende Regel gibt immer den gleichen Anspruch aus, wenn ein Benutzer den angegebenen Anspruchstyp und den Wert enthält: c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee");
Normal Die folgende Regel konvertiert einen Anspruchstyp in einen anderen. Beachten Sie, dass der Wert des Anspruchs, der der Bedingung „c“ entspricht, in der Ausstellungsanweisung verwendet wird. c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value );
Attributspeicher Die folgende Regel verwendet den Wert eines eingehenden Anspruchs, um den Active Directory-Attributspeicher abzufragen: c: [Type == "http://test/name" ] => issue (store = "Enterprise AD Attribute Store", types = ("http://test/email" ), query = ";mail;{0}", param = c.Value )
Attributspeicher Die folgende Regel verwendet den Wert eines eingehenden Anspruchs zum Abfragen eines zuvor konfigurierten SQL-Attributspeichers (Structured Query Language): c: [type == "http://test/name"] => issue (store = "Custom SQL store", types = ("http://test/email","http://test/displayname" ), query = "SELECT mail, displayname FROM users WHERE name ={0}", param = c.value );

Ausdrücke

Ausdrücke werden auf der rechten Seite sowohl für Anspruchsselektorbeschränkungen als auch für Parameter für Ausstellungsanweisungen verwendet. Es gibt verschiedene Arten von Ausdrücken, die die Sprache unterstützt. Alle Ausdrücke in der Sprache operieren auf Zeichenfolgen, d. h., dass Zeichenfolgen als Eingabe angenommen und als Ausgabe erzeugt werden. Zahlen und andere Datentypen wie beispielsweise Datum/Uhrzeit werden in Ausdrücken nicht unterstützt. Die Sprache unterstützt folgende Arten von Ausdrücken:

  • Zeichenfolgenliteral: Zeichenfolgenwert, der von Anführungszeichen (") umschlossen ist.

  • Verkettung von Ausdrücken als Zeichenfolgen: Das Ergebnis ist eine Zeichenfolge, die durch Verkettung der linken und rechten Werte erzeugt wird.

  • Funktionsaufruf: Die Funktion wird durch einen Bezeichner identifiziert, und die Parameter werden als durch Trennzeichen getrennte Liste von Ausdrücken übergeben, die in Klammern („()“) eingeschlossen sind.

  • Der Zugriff auf Anspruchseigenschaften erfolgt in der Form „Variablenname.Eigenschaftenname“: Das Ergebnis des Werts der betreffenden Anspruchseigenschaft für die Auswertung einer angegebenen Variable. Die Variable muss zunächst an einen Anspruchsselektor gebunden werden, bevor sie in dieser Weise verwendet werden kann. Es ist nicht zulässig, die an einen Anspruchsselektor gebundene Variable in den Beschränkungen für denselben Anspruchsselektor zu verwenden.

Die folgenden Anspruchseigenschaften sind verfügbar:

  • Claim.Type

  • Claim.Value

  • Claim.Issuer

  • Claim.OriginalIssuer

  • Claim.ValueType

  • Claim.Properties[Eigenschaftenname] (Diese Eigenschaft gibt eine leere Zeichenfolge zurück, wenn der Eigenschaftenname nicht in der Eigenschaftensammlung des Anspruchs vorhanden ist.)

Die RegexReplace-Funktion kann innerhalb eines Ausdrucks für Aufrufe verwendet werden. Diese Funktion übernimmt einen Eingabeausdruck und vergleicht ihn mit dem angegebenen Muster. Wenn das Muster übereinstimmt, wird die Ausgabe der Übereinstimmung durch den Ersatzwert ersetzt.

Exists-Funktion

Die Exists-Funktion kann in einer Bedingung verwendet werden, um das Vorhandensein eines Anspruchs im Eingabeanspruchssatz zu prüfen, der mit der Bedingung übereinstimmt. Wenn übereinstimmende Ansprüche vorhanden sind, wird die Ausstellungsanweisung nur einmal aufgerufen. Im folgenden Beispiel wird der Anspruch „origin“ genau einmal ausgegeben, nämlich dann, wenn mindestens ein Anspruch im Eingabeanspruchssatz vorhanden ist, bei dem der Aussteller „MSFT“ festgelegt wurde. Dabei ist die tatsächliche Anzahl der Ansprüche unerheblich, bei denen dies der Fall ist. Mit dieser Funktion wird verhindert, dass doppelte Ansprüche ausgestellt werden.

exists([issuer == "MSFT"])
   => issue(type = "origin", value = "Microsoft");

Hauptteil der Regel

Der Hauptteil der Regel kann nur eine einzelne Ausgabeanweisung enthalten. Wenn Bedingungen verwendet werden, ohne die Exists-Funktion zu nutzen, wird der Hauptteil der Regel jedes Mal ausgeführt, wenn der Bedingungsteil übereinstimmt.

Weitere Verweise

Erstellen einer Regel zum Senden von Ansprüchen mithilfe einer benutzerdefinierten Regel