El papel del lenguaje de reglas de reclamación

El lenguaje de reglas de notificación de los Servicios de federación de Active Directory (AD FS) actúa como bloque de creación administrativo del comportamiento de las notificaciones entrantes y salientes, mientras que el motor de notificaciones actúa como el motor de procesamiento de la lógica en el lenguaje de reglas de notificación que define la regla personalizada. Para obtener más información sobre cómo el motor de notificaciones procesa todas las reglas, consulte El rol del motor de notificaciones.

Creación de reglas de notificación personalizadas mediante el lenguaje de reglas de notificación

AD FS proporciona a los administradores la opción de definir reglas personalizadas que pueden usar para determinar el comportamiento de las notificaciones de identidad con el lenguaje de las reglas de notificaciones. Puede usar los ejemplos de sintaxis de lenguaje de reglas de notificación de este tema para crear una regla personalizada que enumere, agregue, elimine y modifique notificaciones para satisfacer las necesidades de su organización. Puede crear reglas personalizadas escribiendo la sintaxis del lenguaje de reglas de notificación en la plantilla Enviar notificaciones mediante una regla de notificación personalizada .

Las reglas se separan entre sí con punto y coma.

Para obtener más información sobre cuándo usar reglas personalizadas, vea Cuándo usar una regla de notificación personalizada.

Uso de plantillas de reglas de notificación para obtener información sobre la sintaxis del lenguaje de reglas de notificación

AD FS también proporciona un conjunto de plantillas de regla de aceptación de notificaciones y emisión de notificaciones predefinidas que puede usar para implementar reglas de notificación comunes. En el cuadro de diálogo Editar reglas de notificación de una confianza determinada, puede crear una regla predefinida y ver la sintaxis del lenguaje de la regla de notificación que compone dicha regla haciendo clic en la pestaña Ver lenguaje de reglas. El uso de la información de esta sección y la técnica View Rule Language puede proporcionar información sobre cómo construir sus propias reglas personalizadas.

Para obtener información más detallada sobre las reglas de notificación y las plantillas de reglas de notificación, consulte El rol de reglas de notificación.

Descripción de los componentes del lenguaje de reglas de reclamaciones

El lenguaje de reglas de declaraciones consta de los siguientes componentes, separados por el operador "=>":

• A condition

• Una declaración de emisión

Conditions

Puede usar condiciones en una regla para comprobar las reclamaciones de entrada y determinar si se debe ejecutar la declaración de emisión de la regla. Una condición representa una expresión lógica que debe evaluarse si es verdadera para ejecutar la parte del cuerpo de la regla. Si falta este elemento, se asume un valor lógico true, es decir, se ejecuta siempre el cuerpo de la regla. La parte de condiciones contiene una lista de condiciones que se combinan junto con el operador lógico de combinación ("&&". ). Debe evaluarse si todas las condiciones de la lista son verdaderas para evaluar toda la parte condicional como verdadera. La condición puede ser un operador de selección de notificaciones o una llamada de función agregada. Estos dos son mutuamente excluyentes, lo que significa que los selectores de reclamaciones y las funciones de agregado no se pueden combinar en una sola parte de las condiciones de la regla.

Las condiciones son opcionales en las reglas. Por ejemplo, la siguiente regla no tiene una condición:

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

Hay tres tipos de condiciones:

• Condición única: esta es la forma más sencilla de una condición. Solo se realizan comprobaciones para una expresión; por ejemplo, nombre de cuenta de Windows = usuario de dominio.

• Condición múltiple: esta condición requiere comprobaciones adicionales para procesar varias expresiones en el cuerpo de la regla; por ejemplo, nombre de cuenta de Windows = usuario de dominio y grupo = contosopurchasers.

Note

Existe otra condición, pero es un subconjunto de la condición única o la condición múltiple. Se conoce como una condición de expresión regular (Regex). Se usa para tomar una expresión de entrada y hacer coincidir la expresión con un patrón determinado. A continuación se muestra un ejemplo de cómo se puede usar.

En los ejemplos siguientes se muestran algunas de las construcciones de sintaxis, que se basan en los tipos de condición, que puede usar para crear reglas personalizadas.

Ejemplos de condición simple

Las condiciones de expresión simple se describen en la tabla siguiente. Se construyen para comprobar simplemente si hay una reclamación con un tipo de reclamación especificado o para una reclamación con un tipo y un valor de reclamación especificados.

Condition description	Ejemplo de sintaxis de condición
Esta regla tiene una condición para comprobar si hay una notificación de entrada con un tipo de notificación especificado ("<http://test/name>" ). Si una reclamación coincidente está en las reclamaciones de entrada, la regla copia la reclamación coincidente o las reclamaciones al conjunto de reclamaciones de salida.	c: [type == "http://test/name"] => issue(claim = c );
Esta regla tiene una condición para comprobar si hay una notificación de entrada con un tipo de notificación especificado ("<http://test/name>" ) y el valor de notificación ("Terry" ). Si una reclamación coincidente está en las reclamaciones de entrada, la regla copia la reclamación coincidente o las reclamaciones al conjunto de reclamaciones de salida.	c: [type == "http://test/name", value == "Terry"] => issue(claim = c);

En la sección siguiente se muestran más -complex condiciones, incluidas las condiciones para comprobar varias notificaciones, condiciones para comprobar el emisor de una notificación y condiciones para comprobar los valores que coinciden con un patrón de expresión regular.

Varios ejemplos de -condition

En la tabla siguiente se proporciona un ejemplo de varias condiciones de -expression.

Condition description	Ejemplo de sintaxis de condición
Esta regla tiene una condición para comprobar si hay dos reclamaciones de entrada, cada una con un tipo de reclamación especificado ("<http://test/name>" y "<http://test/email>"). Si las dos reclamaciones coincidentes están en las reclamaciones de entrada, la regla copia la reclamación de nombre en el conjunto de reclamaciones de salida.	c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 );

Ejemplos de condición normal

En la tabla siguiente se proporciona un ejemplo de una condición regular de expresión -based.

Condition description	Ejemplo de sintaxis de condición
Esta regla tiene una condición que usa una expresión regular para comprobar una notificación de correo electrónico que termine en "@fabrikam.com". Si se encuentra una notificación coincidente en las notificaciones de entrada, la regla copia la notificación coincidente en el conjunto de notificaciones de salida.	c: [type == "http://test/email", value =~ "^. +@fabrikam.com$" ] => issue (claim = c );

Issuance statements

Custom rules are processed based on the issuance statements (issue or add ) that you program into the claim rule. Dependiendo del resultado deseado, la declaración de emisión o la declaración de adición puede redactarse en la regla para rellenar el conjunto de reclamaciones de entrada o el conjunto de reclamaciones de salida. Una regla personalizada que usa la instrucción add rellena explícitamente los valores de notificación solo al conjunto de notificaciones de entrada mientras una regla de notificación personalizada que usa la instrucción issue rellena los valores de notificación en el conjunto de notificaciones de entrada y en el conjunto de notificaciones de salida. Esto puede ser útil cuando un valor de reclamación está pensado para que solo lo usen las reglas futuras en el conjunto de reglas de reclamación.

Por ejemplo, en la ilustración siguiente, la reclamación entrante se agrega al conjunto de reclamaciones de entrada establecido por el motor de emisión de reclamaciones. When the first custom claim rule executes and the criteria of domain user is satisfied, the claims issuance engine processes the logic in the rule using the add statement, and the value of Editor is added to the input claim set. Because the value of Editor is present in the input claim set, Rule 2 can successfully process the issue statement in its logic and generate a new value of Hello, which is added to both the output claim set and to the input claim set for use by the next rule in the rule set. Ahora la regla 3 puede usar todos los valores que se encuentran en el conjunto de notificaciones de entrada como entrada para procesar su lógica.

Acciones de emisión de reclamaciones

El cuerpo de la regla representa una acción de emisión de notificaciones. Hay dos acciones de emisión de notificaciones que el lenguaje reconoce:

• Issue statement: The issue statement creates a claim that goes to both input and output claim sets. Por ejemplo, la siguiente declaración emite una nueva reclamación en función de su conjunto de reclamaciones de entrada.

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

• Add statement: The add statement creates a new claim that is added only to the input claim set collection. Por ejemplo, la siguiente instrucción agrega una nueva reclamación al conjunto de reclamaciones de entrada.

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

La instrucción de emisión de una regla define qué afirmaciones emitirá la regla cuando se cumplan las condiciones. Hay dos formas de instrucciones de emisión relacionadas con los argumentos y el comportamiento de las instrucciones:

• Normal—Normal issuance statements can issue claims by using literal values in the rule or the values from claims that match the conditions. Una instrucción de emisión normal puede constar de uno o los dos formatos siguientes:

  • Claim copy: The claim copy creates a copy of the existing claim in the output claim set. Este formulario de emisión solo tiene sentido cuando se combina con la instrucción de emisión "problema". Cuando se combina con la instrucción de emisión "add", no tiene ningún efecto.

  • New claim: This format creates a new claim, given the values for various claim properties. Se debe especificar Claim.Type; todas las demás propiedades de notificación son opcionales. Se omite el orden de los argumentos de este formulario.

• Attribute Store—This form creates claims with values that are retrieved from an attribute store. Es posible crear varios tipos de reclamaciones mediante una sola instrucción de emisión, lo cual es importante para los almacenes de atributos que realizan operaciones de entrada/salida (E/S) de red o disco durante la recuperación de atributos. Por lo tanto, es conveniente limitar el número de viajes de ida y vuelta entre el motor de directivas y el almacén de atributos. También es legal crear varias reclamaciones para un tipo de reclamación determinado. Cuando el almacén de atributos devuelve varios valores para un tipo de notificación determinado, la instrucción de emisión crea automáticamente una notificación para cada valor de notificación devuelto. Una implementación del almacén de atributos usa los argumentos param para sustituir los marcadores de posición del argumento de consulta por los valores proporcionados en argumentos param. Los marcadores de posición usan la misma sintaxis que la función .NET String.Format ( ) (por ejemplo, {1}, {2}, etc.). El orden de los argumentos para esta forma de emisión es importante y debe ser el orden que se prescribe en la gramática siguiente.

En la tabla siguiente se describen algunas construcciones sintácticas comunes para ambos tipos de instrucciones de emisión de reglas de notificación.

Tipo de declaración de emisión	Descripción de la declaración de emisión	Ejemplo de sintaxis de declaración de emisión
Normal	La siguiente regla siempre emite la misma notificación cada vez que un usuario tiene el tipo de notificación y el valor especificados:	c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee");
Normal	La siguiente regla convierte un tipo de reclamación en otro. Observe que el valor de la reclamación que coincide con la condición "c" se usa en la declaración de emisión.	c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value );
Attribute store	La siguiente regla usa el valor de una notificación entrante para consultar el almacén de atributos de Active Directory:	c: [Type == "http://test/name" ] => issue (store = "Enterprise AD Attribute Store", types = ("http://test/email" ), query = ";mail;{0}", param = c.Value )
Attribute store	La siguiente regla usa el valor de una notificación entrante para consultar un almacén de atributos del lenguaje de consulta estructurado (SQL) configurado anteriormente:	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 );

Expressions

Las expresiones se usan en el lado derecho para las restricciones del selector de notificaciones y los parámetros de la instrucción de emisión. Hay varios tipos de expresiones que admite el lenguaje. Todas las expresiones del lenguaje se basan en cadenas, lo que significa que toman cadenas como entrada y generan cadenas. No se admiten números u otros tipos de datos, como fecha y hora, en expresiones. A continuación se muestran los tipos de expresiones que admite el lenguaje:

• Literal de cadena: valor de cadena delimitado por el carácter de comillas (") en ambos lados.

• Concatenación de cadenas de expresiones: el resultado es una cadena generada por la concatenación de los valores izquierdo y derecho.

• Llamada a función: la función se identifica mediante un identificador y los parámetros se pasan como una coma -delimited lista de expresiones entre corchetes (" ( )".

• Acceso a la propiedad de la notificación en forma de nombre de propiedad DOT de nombre de variable: el resultado del valor de la propiedad de la notificación identificada para una valoración de variable determinada. La variable primero debe enlazarse a un selector de reclamaciones antes de poder usarla de esta manera. No es válido usar la variable enlazada a un selector de notificaciones dentro de las restricciones para ese mismo selector de notificaciones.

Las siguientes propiedades de notificación están disponibles para acceder a ellas:

• Claim.Type

• Claim.Value

• Claim.Issuer

• Claim.OriginalIssuer

• Claim.ValueType

• Claim.Properties[property_name] (Esta propiedad devuelve una cadena vacía si el valor _name de la propiedad no se encuentra en la colección de propiedades de la notificación).

Puede usar la función RegexReplace para llamar dentro de una expresión. Esta función toma una expresión de entrada y la coincide con el patrón especificado. Si el patrón coincide, el resultado de la coincidencia se reemplaza por el valor de la sustitución.

Exists functions

La función Exists se puede usar dentro de una condición para evaluar si existe una reclamación que coincida con la condición en el conjunto de reclamaciones de entrada. Si existe cualquier notificación coincidente, se llama a la instrucción de emisión tan solo una vez. En el ejemplo siguiente, la notificación de "origen" se emite exactamente una vez (si hay al menos una notificación en la colección del conjunto de notificaciones de entrada con el emisor establecido en "MSFT", independientemente de cuántas de las notificaciones tengan el emisor establecido en "MSFT". El uso de esta función impide que se emita notificaciones duplicadas.

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

Rule body

El cuerpo de la regla puede contener una única instrucción de emisión. Si se usan condiciones sin usar la función Exists, el cuerpo de la regla se ejecuta una vez por cada vez que coincide la parte de las condiciones.

Additional references

Crear una regla para enviar reclamaciones mediante una regla personalizada