Ruolo del linguaggio delle regole di autorizzazione
Il linguaggio delle regole di attestazioni di Active Directory Federation Services (AD FS) funge da blocco costitutivo amministrativo per il comportamento delle attestazioni in ingresso e in uscita, e il motore delle attestazioni funge da motore di elaborazione per la logica nel linguaggio delle regole che definiscono la regola personalizzata. Per altre informazioni sull'elaborazione di tutte le regole dal motore delle attestazioni, vedere Ruolo del motore di attestazioni.
Creazione di regole di attestazione personalizzate usando il linguaggio delle regole di attestazione
AD FS offre agli amministratori la possibilità di definire regole personalizzate che possono usare per determinare il comportamento delle attestazioni di identità con il linguaggio delle regole delle attestazioni. È possibile usare gli esempi di sintassi del linguaggio delle regole di attestazione in questa sezione per creare una regola personalizzata che enumera, aggiunge, elimina e modifica le attestazioni per soddisfare le esigenze della tua organizzazione. Puoi creare regole personalizzate digitando nella sintassi del linguaggio di regole di attestazioni nel modello di regola Invia attestazioni usando un'attestazione personalizzata.
Le regole sono separate l'una dall'altra con punti e virgola.
Per ulteriori informazioni su quando usare regole di attestazione personalizzate, vedere Quando usare una regola di attestazione personalizzata.
Uso dei modelli di regola attestazione per apprendere la sintassi del linguaggio delle regole attestazione
AD FS fornisce anche un set di modelli predefiniti per l'emissione di dichiarazioni e regole di accettazione delle dichiarazioni che è possibile utilizzare per implementare regole comuni delle dichiarazioni. Nella finestra di dialogo Modifica regole attestazione per un determinato trust, è possibile creare una regola predefinita e visualizzare la sintassi del linguaggio delle regole di attestazione che costituisce tale regola facendo clic sulla scheda View Rule Language per tale regola. L'uso delle informazioni contenute in questa sezione e la tecnica View Rule Language possono fornire informazioni dettagliate su come costruire regole personalizzate.
Per informazioni più dettagliate sulle regole di attestazione e sui modelli di regole di attestazione, vedere Il ruolo delle regole di attestazione.
Comprensione dei componenti del linguaggio delle regole delle dichiarazioni
Il linguaggio delle regole di attestazione è costituito dai componenti seguenti, separati dall'operatore " =>" :
Una condizione
Un documento di emissione
Condizioni
È possibile utilizzare le condizioni in una regola per controllare le dichiarazioni di input e determinare se la dichiarazione di emissione della regola deve essere eseguita. Una condizione rappresenta un'espressione logica che deve essere valutata su true per eseguire la parte del corpo della regola. Se questa parte non è presente, si presuppone un vero logico; ossia, 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 nell'elenco devono essere valutate su true affinché l'intera parte condizionale venga valutata su true. La condizione può essere un operatore di selezione delle richieste o una chiamata a funzione di aggregazione. Questi due elementi si escludono a vicenda, il che significa che i selettori di rivendicazioni e le funzioni di aggregazione non possono essere combinati in una sola parte delle condizioni delle regole.
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: questa è la forma più semplice di una condizione. Vengono eseguiti controlli per una sola espressione; Ad esempio, nome account di Windows = utente di dominio.
Condizione multipla: questa condizione richiede controlli aggiuntivi per elaborare più espressioni nel corpo della regola; ad esempio, nome account di Windows = utente di dominio e gruppo = contosopurchasers.
Nota
Esiste un'altra condizione, ma è un subset della singola condizione o della condizione multipla. Si fa riferimento a una condizione di espressione regolare (Regex). Viene usato per prendere un'espressione di input e abbinarla a un determinato modello. Di seguito è riportato un esempio di come può essere usato.
Gli esempi seguenti illustrano alcune delle costruzioni della sintassi, basate sui tipi di condizione, che è possibile usare per creare regole personalizzate.
Esempi di -condition singoli
Le singole condizioni -expression sono descritte nella tabella seguente. Vengono costruiti per verificare semplicemente la presenza di un'attestazione con un tipo di attestazione specificato o per un'attestazione con un tipo di attestazione e un valore di attestazione specificati.
| Descrizione della condizione | Esempio di sintassi della condizione |
|---|---|
Questa regola ha una condizione per verificare la presenza di una dichiarazione di input con un tipo di dichiarazione specificato ("<http://test/name>" ). Se un'attestazione corrispondente si trova nelle attestazioni di input, la regola copia l'attestazione o le attestazioni corrispondenti nel set di attestazioni di output. |
c: [type == "http://test/name"] => issue(claim = c ); |
Questa regola ha una condizione per verificare un'attestazione di input con un tipo di attestazione specificato ("<http://test/name>") e un valore di attestazione ("Terry"). Se un'attestazione corrispondente si trova nelle attestazioni di input, la regola copia l'attestazione o le attestazioni corrispondenti nel set di attestazioni di output. |
c: [type == "http://test/name", value == "Terry"] => issue(claim = c); |
Altre -complex condizioni sono visualizzate nella sezione successiva, incluse le condizioni per verificare la presenza di più attestazioni, condizioni per controllare l'autorità emittente di un'attestazione e condizioni per verificare la presenza di valori corrispondenti a un criterio di espressione regolare.
Più esempi di -condition
Nella tabella seguente viene fornito un esempio di più condizioni di -expression.
| 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 le 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 regolari di -condition
Nella tabella seguente viene fornito un esempio di condizione regolare, espressione -based.
| Descrizione della condizione | Esempio di sintassi della condizione |
|---|---|
| Questa regola ha una condizione che utilizza un'espressione regolare per verificare la presenza di una attestazione -mail che termina con "@fabrikam.com". Se viene trovata un'attestazione corrispondente 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 ); |
Dichiarazioni di emissione
Le regole personalizzate vengono elaborate in base alle dichiarazioni di emissione (emissione o aggiunta ) programmate nella regola di attestazione. A seconda del risultato desiderato, l'istruzione di emissione o di aggiunta 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 popola in modo esplicito i valori delle attestazioni solo nel set di attestazioni di input, mentre una regola personalizzata di attestazione che usa l'istruzione issue popola i valori delle attestazioni sia nel set di attestazioni di input che nel set di attestazioni di output. Ciò può essere utile quando un valore di attestazione è destinato ad essere utilizzato solo da regole future nel gruppo di regole di attestazione.
Nell'illustrazione seguente, ad esempio, l'attestazione in ingresso viene aggiunta all'attestazione di input impostata dal motore di rilascio delle attestazioni. Quando la prima regola di attestazione personalizzata viene eseguita e i criteri dell'utente di dominio vengono soddisfatti, il motore di rilascio delle attestazioni elabora la logica nella regola usando l'istruzione di aggiunta, e il valore di Editor viene aggiunto al set di attestazioni di input. Poiché il valore di Editor è presente nel set di attestazioni di input, la regola 2 può elaborare correttamente la dichiarazione di problema nella sua logica e generare un nuovo valore di Hello, che viene aggiunto sia al set di attestazioni di output che al set di attestazioni di input per essere utilizzato dalla regola successiva nel set di regole. La regola 3 può ora usare tutti i valori presenti nell'insieme di dichiarazioni di input come input per processare la sua logica.
Azioni di emissione delle richieste
Il corpo della regola rappresenta un'azione di emissione delle attestazioni. Esistono due azioni di emissione delle richieste che la lingua riconosce.
Dichiarazione del problema: La dichiarazione del problema crea una dichiarazione che va sia ai set di dichiarazioni di input che a quelli di output. Ad esempio, il seguente comando emette una nuova richiesta basata sul set di input di richieste:
c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);Istruzione Add: L'istruzione Add crea una nuova attestazione che viene aggiunta solo alla raccolta di set di attestazioni 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");
La dichiarazione di emissione di una regola definisce quali affermazioni verranno emesse dalla regola quando le condizioni sono soddisfatte. Esistono due forme di dichiarazioni di rilascio riguardanti gli argomenti e il comportamento della dichiarazione.
Normale— le normali dichiarazioni di rilascio possono emettere attestazioni usando valori letterali nella regola o i valori delle attestazioni che corrispondono alle condizioni. Una dichiarazione di rilascio normale può consistere in uno o entrambi i formati seguenti:
Copia Attestazione: La Copia dell'Attestazione crea una copia dell'attestazione esistente nel set di attestazioni di output. Questo modulo di emissione ha senso solo quando viene combinato con la dichiarazione di emissione "issue". Quando è combinato con la dichiarazione di emissione "add", non produce alcun effetto.
Nuovo reclamo: questo formato crea un nuovo reclamo, in base ai valori per varie proprietà del reclamo. Claim.Type deve essere specificato; tutte le altre proprietà delle dichiarazioni sono facoltative. L'ordine degli argomenti per questo modulo viene ignorato.
Archivio Attributi: questo modulo crea dichiarazioni con valori recuperati da un Archivio Attributi. È possibile creare più tipi di attestazione usando una singola dichiarazione di rilascio, importante per gli archivi di attributi che eseguono operazioni di input/output su rete o disco durante il recupero dell'attributo. Pertanto, è consigliabile limitare il numero di cicli di comunicazione tra il motore dei criteri e l'archivio degli attributi. È anche legale creare più attestazioni per un determinato tipo di attestazione. Quando l'archivio 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 degli attributi utilizza gli argomenti param per sostituire i segnaposto nell'argomento di query con i valori forniti negli stessi argomenti param. I segnaposto usano la stessa sintassi della funzione .NET String.Format ( ) (ad esempio, {1}, {2}e così via ). L'ordine degli argomenti per questa forma di rilascio è importante e deve essere l'ordine previsto nella grammatica seguente.
Nella tabella seguente vengono descritte alcune costruzioni di sintassi comuni per entrambi i tipi di dichiarazioni di rilascio nelle regole delle attestazioni.
| Tipo di dichiarazione di emissione | Descrizione della dichiarazione di emissione | Esempio di sintassi della dichiarazione di rilascio |
|---|---|---|
| Normale | La regola seguente genera sempre la stessa attestazione ogni volta che un utente ha il tipo di attestazione e il valore specificati: | c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee"); |
| Normale | La regola seguente converte un tipo di reclamo in un altro. Si noti che il valore della dichiarazione corrispondente alla condizione "c" viene usato nella dichiarazione di emissione. | c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value ); |
| Archivio di attributi | La regola seguente usa il valore di un'attestazione in ingresso per eseguire una query nell'archivio 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 ) |
| Negozio di attributi | La regola seguente usa il valore di un'attestazione in ingresso per eseguire query su un archivio attributi SQL (Structured Query Language) configurato in precedenza: | 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 nella parte destra sia per i vincoli del selettore di attestazioni sia per i parametri dell'istruzione di rilascio. Esistono diversi tipi di espressioni supportate dal linguaggio. Tutte le espressioni nel linguaggio sono basate su stringhe, ovvero accettano stringhe come input e producono stringhe. I numeri o altri tipi di dati, ad esempio data/ora, nelle espressioni non sono supportati. Di seguito sono riportati i tipi di espressioni supportate dal linguaggio:
Literale di stringa: valore della stringa, delimitato dal carattere virgolette (“) su entrambi i lati.
Concatenazione di stringhe di espressioni: il risultato è una stringa prodotta dalla concatenazione dei valori sinistro e destro.
Chiamata di funzione: la funzione viene identificata da un identificatore e i parametri vengono passati come virgola -delimited elenco di espressioni racchiuse tra parentesi quadre (" ( )".
Accesso alla proprietà dell'attestazione sotto forma di nome variabile nome proprietà DOT: risultato del valore della proprietà dell'attestazione identificata per una determinata valutazione variabile. La variabile deve prima essere associata a un selettore di attestazioni prima di poterla usare in questo modo. Non è consentito usare la variabile associata a un selettore di attestazioni all'interno dei vincoli per lo stesso selettore di attestazioni.
Sono accessibili le seguenti proprietà delle rivendicazioni:
TipoDiRichiesta
Claim.Value
Emittente del Reclamo
Richiesta.EmittenteOriginale
TipoValoreReclamo
Claim.Properties[property_name] (Questa proprietà restituisce una stringa vuota se non è possibile trovare la proprietà _name nell'insieme delle proprietà dell'attestazione. )
È possibile usare la funzione RegexReplace per chiamare all'interno di un'espressione. Questa funzione accetta un'espressione di input e la corrisponde al modello specificato. Se il criterio corrisponde, l'output della corrispondenza viene sostituito con il valore sostitutivo.
Esistono funzioni
La funzione Exists può essere usata in una condizione per valutare se esiste un'attestazione che corrisponde alla condizione nel set di attestazioni di input. Se esiste una richiesta corrispondente, la dichiarazione di emissione viene effettuata una sola volta. Nell'esempio seguente, la dichiarazione "origin" viene rilasciata esattamente una volta: se nella raccolta di set di dichiarazioni di input è presente almeno una dichiarazione con l'emittente impostato su "MSFT", indipendentemente da quante dichiarazioni hanno l'emittente impostato su "MSFT". L'uso di questa funzione impedisce l'emissione 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 usare la funzione Exists, il corpo della regola viene eseguito una volta per ogni volta che la parte delle condizioni corrisponde.
Altri riferimenti
Creare una regola per inviare attestazioni usando una regola personalizzata