Ruolo del linguaggio delle regole delle attestazioni

  • Articolo

Active Directory Federation Services (ADFS) attestazione lingua delle regole viene utilizzato come il blocco predefinito amministrativo per il comportamento di attestazioni in ingresso e in uscita, mentre il motore delle attestazioni funge da motore di elaborazione per la logica nel linguaggio di regola attestazione che definisce la regola personalizzata. Per ulteriori informazioni su come tutte le regole vengono elaborate dal motore di attestazioni, vedere il ruolo del motore di attestazioni.

Creazione di regole attestazioni personalizzate usando il linguaggio delle regole attestazioni

ADFS offre agli amministratori l'opzione per definire regole personalizzate che possono utilizzare per determinare il comportamento di attestazioni di identità con il linguaggio di regola attestazione. È possibile usare gli esempi di sintassi del linguaggio delle regole attestazioni in questo argomento per creare una regola personalizzata che enumera, aggiunge, elimina e modifica attestazioni in base alle esigenze dell'organizzazione. È possibile creare regole personalizzate digitando nella sintassi del linguaggio di regola attestazione nel inviare attestazioni mediante un'attestazione personalizzata modello di regola.

Le regole sono separate le une dalle altre con un punto e virgola.

Per ulteriori informazioni sull'utilizzo di regole personalizzate, vedere quando utilizzare una regola attestazione personalizzata.

Uso di modelli di regole attestazioni per apprendere la sintassi del linguaggio delle regole attestazioni

ADFS offre inoltre una serie di rilascio di attestazione predefiniti e modelli di regole di accettazione che è possibile utilizzare per implementare comuni attestazione regole attestazione. Nel Modifica regole attestazione la finestra di dialogo per una determinata relazione di trust, è possibile creare una regola predefinita e visualizzare la sintassi di linguaggio di regola attestazione che costituiscono tale regola, facendo la Visualizza lingua delle regole scheda per la regola. Utilizzando le informazioni in questa sezione e Visualizza lingua delle regole tecnica possibile consentono di comprendere come creare regole personalizzate.

Per ulteriori informazioni sulle regole attestazione e i modelli di regola attestazione, vedere ruolo delle attestazioni regole.

Informazioni sui componenti del linguaggio delle regole attestazioni

Il linguaggio di regola attestazione include i componenti seguenti, separati dal “ =>” operatore:

  • Una condizione

  • Istruzione di rilascio

Condizioni

È possibile usare le condizioni in una regola per controllare le attestazioni di input e determinare se eseguire l'istruzione di rilascio della regola. Una condizione rappresenta un'espressione logica che deve restituire true per eseguire la parte del corpo della regola. Se questa parte manca, si presuppone un true logico; ciò significa che il corpo della regola viene sempre eseguito. La parte condizioni contiene un elenco di condizioni combinate con l'operatore logico di congiunzione ("&&" ). Tutte le condizioni incluse nell'elenco devono restituire true affinché l'intera parte condizionale restituisca true. La condizione può essere un operatore di selezione di attestazioni o una chiamata di funzione di aggregazione. Questi si escludono a vicenda, il che significa che i selettori di attestazioni e le funzioni di aggregazione non possono essere combinati in una parte relativa alle condizioni di una singola regola.

Le condizioni sono facoltative nelle regole. Ad esempio, la regola seguente non ha una condizione:

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

Esistono tre tipi di condizioni:

  • Singola condizione: è la forma più semplice di una condizione. Vengono effettuati i controlli per una sola espressione; ad esempio windows account name = utente di dominio.

  • Condizione multipla: questa condizione richiede ulteriori controlli per elaborare più espressioni nel corpo della regola; ad esempio, windows account name = utente di dominio e gruppo = contosopurchasers.

Nota

Esiste un'altra condizione, ma è un subset di singola condizione o di una condizione multipla. Viene considerato come un'espressione regolare (Regex) condizione. e viene usata per abbinare un'espressione di input a un modello specifico. Di seguito è riportato un esempio di come è possibile usarla.

Gli esempi seguenti mostrano alcune costruzioni di sintassi, basate sui tipi di condizione, che è possibile usare per creare regole personalizzate.

Esempi di singola condizione

Le condizioni di singola espressione sono descritte nella tabella seguente. Vengono costruite per controllare semplicemente la presenza di un'attestazione con un tipo di attestazione specificato o di un'attestazione con un tipo di attestazione valore dell'attestazione specificati.

Descrizione della condizione Esempio di sintassi della condizione
Questa regola presenta una condizione per verificare la presenza di un'attestazione di input con un tipo di attestazione specificato ("<http://test/name>" ). Se un'attestazione corrispondente si trova nelle attestazioni di input, la regola copia l'attestazione corrispondente o le attestazioni nel set di attestazioni di output. c: [type == "http://test/name"] => issue(claim = c );
Questa regola presenta una condizione per verificare la presenza di un'attestazione di input con un tipo di attestazione specificato ("<http://test/name>" ) e il valore dell'attestazione ("Terry"). Se un'attestazione corrispondente si trova nelle attestazioni di input, la regola copia l'attestazione corrispondente o le attestazioni nel set di attestazioni di output. c: [type == "http://test/name", value == "Terry"] => issue(claim = c);

Nella sezione successiva vengono mostrate le condizioni più complesse, incluse le condizioni per controllare la presenza di più attestazioni, le condizioni per controllare l'emittente di un'attestazione e le condizioni per verificare la presenza di valori che corrispondono a un modello di espressione regolare.

Esempi di più condizioni

La tabella seguente fornisce un esempio di condizioni con più espressioni.

Descrizione della condizione Esempio di sintassi della condizione
Questa regola ha una condizione per verificare la presenza di due attestazioni di input, ognuna con un tipo di attestazione specificato ("<http://test/name>" e "<http://test/email>" ). Se due attestazioni corrispondenti si trovano nelle attestazioni di input, la regola copia l'attestazione del nome nel set di attestazioni di output. c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 );

Esempi di condizione regolare

La tabella seguente fornisce un esempio di condizione regolare basata su espressioni.

Descrizione della condizione Esempio di sintassi della condizione
Questa regola presenta una condizione che usa un'espressione regolare per controllare la presenza di un'attestazione di posta elettronica che termina con "@fabrikam.com". Se un'attestazione corrispondente viene trovata nelle attestazioni di input, la regola copia l'attestazione corrispondente nel set di attestazioni di output. c: [type == "http://test/email", value =~ "^. +@fabrikam.com$" ] => issue (claim = c );

Istruzioni di rilascio

Regole personalizzate vengono elaborate in base alle istruzioni di rilascio (issue or add) programmare nella regola di attestazione. A seconda del risultato desiderato, l'istruzione di issue o add può essere scritta nella regola per popolare il set di attestazioni di input o il set di attestazioni di output. Una regola personalizzata che usa l'istruzione add in modo esplicito popola i valori di attestazione solo nel set di attestazioni di input mentre una regola attestazioni personalizzata che usa l'istruzione di emissione popola i valori di attestazione nel set di attestazioni di input e nel set di attestazioni di output. Può essere utile quando un valore attestazione deve essere usato solo dalle regole future nel set di regole attestazioni.

Nella figura seguente, ad esempio, l'attestazione in ingresso viene aggiunta al set di attestazioni di input dal motore di rilascio delle attestazioni. Quando viene eseguita la prima regola attestazioni personalizzata e i criteri di domain\user vengono soddisfatti, il motore di rilascio delle attestazioni elabora la logica della regola usando l'istruzione add e il valore di Editor viene aggiunto al set di attestazioni di input. Perché il valore dell'Editor è presente nel set di attestazioni di input, la regola 2 può correttamente l'istruzione di problema nella logica corrispondente e generare un nuovo valore di Hello, che viene aggiunto a entrambi l'output set di attestazioni e impostare l'attestazione di input impostato per l'utilizzo per la regola successiva nella regola. La regola 3 ora può usare tutti i valori presenti nel set di attestazioni di input come input per l'elaborazione della propria logica.

AD FS roles

Azioni di rilascio di attestazioni

Il corpo della regola rappresenta un'azione di rilascio di attestazioni. Esistono due azioni di rilascio di attestazioni riconosciute dalla lingua:

  • Istruzione: l'istruzione problema crea un'attestazione che si sia input e output i set di attestazioni. Ad esempio, l'istruzione seguente rilascia una nuova attestazione basata sul proprio set di attestazioni di input:

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

  • Aggiungere l'istruzione: l'istruzione add crea una nuova attestazione che viene aggiunto solo alla raccolta di set di attestazione di input. Ad esempio, l'istruzione seguente aggiunge una nuova attestazione al set di attestazioni di input:

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

L'istruzione di rilascio di una regola definisce quali attestazioni verranno rilasciate dalla regola quando le condizioni sono soddisfatte. Esistono due forme di istruzioni di rilascio relative agli argomenti e al comportamento dell'istruzione:

  • Normale-istruzioni normale rilascio possono rilasciare le attestazioni tramite valori letterali nella regola o i valori delle attestazioni che corrispondono alle condizioni. Un'istruzione di rilascio normale può essere costituita da uno o da entrambi i formati seguenti:

    • Copia di attestazione: la copia di attestazione crea una copia dell'attestazione esistente nel set di attestazioni di output. Questo modulo di rilascio ha senso solo quando viene combinato con l'istruzione di rilascio "issue". Quando viene combinato con l'istruzione di rilascio "add", non ha alcun effetto.

    • Nuova attestazione: questo formato rea una nuova attestazione, in base ai valori per diverse proprietà di attestazione. È necessario specificare Claim.Type; tutte le altre proprietà di attestazione sono facoltative. L'ordine degli argomenti per questo modulo viene ignorato.

  • Archivio attributiquesto modulo consente di creare attestazioni con i valori che vengono recuperati da un archivio di attributi. È possibile creare più tipi di attestazioni usando una singola istruzione di rilascio, aspetto importante per gli archivi di attributi che costituiscono la rete di operazioni di input/output (I/O) del disco durante il recupero di attributi. Quindi, è opportuno limitare il numero di roundtrip tra il motore dei criteri e l'archivio di attributi. È anche consentito creare più attestazioni per un determinato tipo di attestazione. Quando l'archivio di attributi restituisce più valori per un determinato tipo di attestazione, l'istruzione di rilascio crea automaticamente un'attestazione per ogni valore attestazione restituito. Un'implementazione dell'archivio di attributi usa gli argomenti dei parametri per sostituire i segnaposto nell'argomento query con i valori forniti negli argomenti dei parametri. I segnaposto viene utilizzata la stessa sintassi come Format .NET ( ) funzione (per esempio, {1}, {2} e così via). L'ordine degli argomenti per questa forma di rilascio è importante e deve essere quello previsto nella grammatica seguente.

La tabella seguente descrive alcune costruzioni di sintassi comuni per entrambi i tipi di istruzioni di rilascio nelle regole attestazioni.

Tipo di istruzione di rilascio Descrizione dell'istruzione di rilascio Esempio di sintassi dell'istruzione di rilascio
Normale La regola seguente rilascia sempre la stessa attestazione ogni volta che un utente ha il tipo e il valore attestazione specificati: c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee");
Normale La regola seguente converte un tipo di attestazione in un altro. Si noti che nell'istruzione di rilascio viene usato il valore dell'attestazione corrispondente alla condizione "c". c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value );
Archivio attributi La regola seguente usa il valore di un'attestazione in ingresso per eseguire una query nell'archivio di attributi di Active Directory: c: [Type == "http://test/name" ] => issue (store = "Enterprise AD Attribute Store", types = ("http://test/email" ), query = ";mail;{0}", param = c.Value )
Archivio attributi La regola seguente utilizza il valore di un'attestazione in ingresso per eseguire una query già configurati Structured Query Language (SQL) archivio attributi: 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 );

Espressioni

Le espressioni vengono usate sul lato destro sia per i vincoli del selettore di attestazioni che per i parametri delle istruzioni di rilascio. Esistono vari tipi di espressioni supportati dalla lingua. Tutte le espressioni nella lingua sono basate su stringa, cioè usano stringhe come input e producono stringhe. I numeri o altri tipi di dati, come data/ora, non sono supportati nelle espressioni. I tipi di espressioni supportati dalla lingua sono i seguenti:

  • Valore letterale stringa: stringa di valore, delimitate da offerta (") carattere su entrambi i lati.

  • Concatenazione di stringhe di espressioni: il risultato è una stringa che viene prodotta dalla concatenazione dei valori di sinistra e di destra.

  • Chiamata di funzione: la funzione è identificata da un identificatore e i parametri vengono passati come un elenco delimitato da virgola di espressioni racchiuse tra parentesi quadre ("()").

  • Accesso alle proprietà dell'attestazione sotto forma di nome proprietà DOT di un nome variabile: risultato del valore della proprietà dell'attestazione identificata per una determinata valutazione della variabile. La variabile deve prima essere associata a un selettore di attestazioni per poter essere usata in questo modo. Non è consentito usare la variabile associata a un selettore di attestazioni all'interno dei vincoli per lo stesso selettore di attestazioni.

Le proprietà di attestazione seguenti sono disponibili per l'accesso:

  • Claim.Type

  • Claim.Value

  • Claim.Issuer

  • Claim.OriginalIssuer

  • Claim.ValueType

  • Claim.Properties[property_name] (questa proprietà restituisce una stringa vuota se property_name non viene trovato nella raccolta delle proprietà dell'attestazione).

È possibile usare la funzione RegexReplace per chiamare all'interno di un'espressione. Questa funzione abbina un'espressione di input al modello specificato. Se il modello corrisponde, l'output della corrispondenza viene sostituito con il valore di sostituzione.

Funzioni Exists

La funzione Exists può essere usata in una condizione per valutare se un'attestazione che corrisponde alla condizione esiste nel set di attestazioni di input. Se la corrispondenza esiste, l'istruzione di rilascio viene chiamata una sola volta. Nell'esempio seguente, l'attestazione "origin" viene rilasciata esattamente una volta se esiste almeno un'attestazione nella raccolta di set di attestazioni di input per la quale l'emittente è impostato su "MSFT", indipendentemente dal numero di attestazioni per le quali l'emittente è impostato su "MSFT". L'uso di questa funzione impedisce il rilascio di attestazioni duplicate.

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

Corpo della regola

Il corpo della regola può contenere solo una singola istruzione di rilascio. Se le condizioni vengono usate senza la funzione Exists, il corpo della regola viene eseguito una sola volta per ogni volta in cui la parte delle condizioni viene abbinata.

Altri riferimenti

Creare una regola per inviare attestazioni mediante una regola personalizzata