O papel da linguagem de regras de declarações

A linguagem da regra de declaração do Serviços de Federação do Active Directory (AD FS) atua como o bloco de construção administrativo para o comportamento das declarações de entrada e de saída, enquanto o mecanismo de declarações atua como o mecanismo de processamento para a lógica da linguagem da regra de declaração que define a regra personalizada. Para obter mais informações sobre como todas as regras são processadas pelo mecanismo de declarações, consulte a função do mecanismo de declarações.

Criando regras de reivindicação personalizadas usando a linguagem de regras de reivindicação

O AD FS oferece aos administradores a opção de definir regras personalizadas que podem ser usadas para determinar o comportamento das declarações de identidade com a linguagem de regras de declaração. Você pode usar os exemplos de sintaxe da linguagem de regra de declaração neste tópico para criar uma regra personalizada que enumera, adiciona, exclui e modifica declarações para atender às necessidades da sua organização. Você pode criar regras personalizadas digitando na sintaxe da linguagem de regras de declaração no modelo de regra Enviar Declarações Usando uma Declaração Personalizada.

As regras são separadas umas das outras com ponto-e-vírgula.

Para obter mais informações sobre quando usar regras personalizadas, consulte Quando usar uma regra de declaração personalizada.

Usando modelos de regras de declaração para saber mais sobre a sintaxe da linguagem de regras de declaração

O AD FS também fornece um conjunto de modelos predefinidos de regra de aceitação de declarações e emissão de declarações que você pode usar para implementar regras comuns de declaração. Na caixa de diálogo Editar Regras de Declaração para uma determinada confiança, você pode criar uma regra predefinida e exibir a sintaxe da linguagem de regra de declaração que compõe essa regra clicando na guia Exibir Idioma da Regra para essa regra. Usar as informações nesta seção e a técnica Exibir Linguagem de Regra pode fornecer insights sobre como construir suas próprias regras personalizadas.

Para obter informações mais detalhadas sobre regras de declaração e modelos de regra de declaração, consulte a função de regras de declaração.

Entendendo os componentes da linguagem de regras de declaração

A linguagem da regra de declaração consiste nos seguintes componentes, separados pelo operador " =>":

• Uma condição

• Uma declaração de emissão

Condições

Você pode usar as condições de uma regra para verificar as declarações de entrada e determinar se a instrução de emissão da regra deve ser executada. Uma condição representa uma expressão lógica que deve ser avaliada como verdadeiro para executar o bloco de regras. Se essa parte estiver ausente, será considerada uma condição lógica true; ou seja, o corpo da regra sempre será executado. A parte de condições contém uma lista de condições combinadas com o operador lógico de conjunção ("&&"). Todas as condições na lista devem ser avaliadas como verdadeiras para que toda a parte condicional seja avaliada como verdadeira. A condição pode ser um operador de seleção de declarações ou uma chamada de função de agregação. Esses dois são mutuamente exclusivos, o que significa que seletores de declaração e funções de agregação não podem ser combinados em uma única parte de condições de regra.

As condições são opcionais nas regras. Por exemplo, a regra a seguir não tem uma condição:

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

Há três tipos de condições:

• Condição única: essa é a forma mais simples de uma condição. Verificações são feitas para apenas uma expressão; por exemplo, nome da conta do Windows = usuário do domínio.

• Condição múltipla – essa condição requer verificações adicionais para processar várias expressões no corpo da regra; por exemplo, nome da conta do Windows = usuário de domínio e grupo = contosopurchasers.

Os exemplos a seguir mostram algumas das construções de sintaxe, que são baseadas nos tipos de condição, que você pode usar para criar regras personalizadas.

Exemplos únicos de -condition

As condições únicas de -expression são descritas na tabela a seguir. Eles são construídos para simplesmente verificar uma alegação com um tipo de alegação específico ou uma alegação com um tipo e valor específicos.

Mais -complex condições são mostradas na próxima seção, incluindo condições para verificar várias declarações, condições para verificar o emissor de uma declaração e condições para verificar valores que correspondam a um padrão de expressão regular.

Vários exemplos de -condition

A tabela a seguir fornece um exemplo de várias condições de -expression.

Exemplos regulares de -condition

A tabela a seguir fornece um exemplo de uma condição de expressão regular -based.

Declarações de emissão

As regras personalizadas são processadas com base nas declarações de emissão (emitir ou adicionar) que você programa na regra de declaração. Dependendo do resultado desejado, a instrução issue ou a instrução add podem ser gravadas na regra para preencher o conjunto de declarações de entrada ou o conjunto de declarações de saída. Uma regra personalizada que usa a instrução add preenche explicitamente valores de declaração apenas para o conjunto de declarações de entrada, enquanto uma regra de declaração personalizada que usa a instrução de emissão preenche valores de declaração no conjunto de declarações de entrada e no conjunto de declarações de saída. Isso pode ser útil quando um valor de declaração se destina a ser usado apenas por regras futuras no conjunto de regras de declaração.

Por exemplo, na ilustração a seguir, a declaração recebida é adicionada ao conjunto de declarações de entrada pelo motor de emissão de declarações. Quando a primeira regra de declaração personalizada é executada e os critérios do usuário de domínio são atendidos, o mecanismo de emissão de declarações processa a lógica na regra usando a instrução add e o valor do Editor é adicionado ao conjunto de declarações de entrada. Como o valor do Editor está presente no conjunto de declarações de entrada, a Regra 2 pode processar com êxito a instrução de problema em sua lógica e gerar um novo valor de Hello, que é adicionado ao conjunto de declarações de saída e ao conjunto de declarações de entrada para uso pela próxima regra no conjunto de regras. Agora, a regra 3 pode usar todos os valores que estiverem presentes no conjunto de declarações de entrada definido como entrada para o processamento de sua lógica.

Ações de emissão de declaração

O corpo da regra representa uma ação de emissão de declaração. Há duas ações de emissão de declaração que o idioma reconhece:

• Declaração do problema: A declaração do problema cria uma reivindicação que é atribuída aos conjuntos de declarações de entrada e saída. Por exemplo, a instrução a seguir emite uma nova declaração com base em seu conjunto de declarações de entrada:

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

• Adicionar instrução: A instrução add cria uma nova declaração que é adicionada somente à coleção de conjuntos de declarações de entrada. Por exemplo, a instrução a seguir adiciona uma nova declaração ao conjunto de declarações de entrada:

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

A instrução de emissão de uma regra define quais declarações serão emitidas pela regra quando as condições forem atendidas. Há duas formas de instruções de emissão relacionadas aos argumentos e ao comportamento da instrução:

• Normal — as instruções de emissão normais podem emitir declarações usando valores literais na regra ou os valores de declarações que correspondem às condições. Uma instrução de emissão normal pode consistir em um ou ambos os seguintes formatos:

  • Cópia da declaração: a cópia da declaração cria uma cópia da declaração existente no conjunto de declarações de saída. Essa forma de emissão só faz sentido quando é combinada com a instrução "emissão". Quando ela é combinada com a instrução “adição”, não tem nenhum efeito.

  • Nova declaração: esse formato cria uma nova declaração, considerando os valores de várias propriedades de declaração. Claim.Type deve ser especificado; todas as outras propriedades de declaração são opcionais. A ordem dos argumentos para esse formulário é ignorada.

• Repositório de Atributos — esse formulário cria declarações com valores recuperados de um repositório de atributos. É possível criar vários tipos de reivindicação usando uma única instrução de emissão, que é importante para repositórios de atributos que fazem operações de E/S (entrada/saída) de rede ou disco durante a recuperação de atributos. Portanto, é desejável limitar o número de viagens de ida e volta entre o mecanismo de política e o repositório de atributos. Também é legal criar várias declarações para um determinado tipo de declaração. Quando o repositório de atributos retorna vários valores para um determinado tipo de declaração, a instrução de emissão cria automaticamente uma declaração para cada valor de declaração retornado. Uma implementação de repositório de atributos usa os argumentos de parâmetro para substituir os espaços reservados no argumento de consulta por valores que são fornecidas nos argumentos de parâmetro. Os espaços reservados usam a mesma sintaxe que a função String.Format() do .NET (por exemplo, {1}, {2} e assim por diante). A ordem dos argumentos para essa forma de emissão é importante e deve ser a ordem que é prescrita na gramática a seguir.

A tabela a seguir descreve algumas construções de sintaxe comuns para ambos os tipos de declarações de emissão nas regras de declaração.

Expressões

As expressões são usadas no lado direito para as restrições do seletor de declarações e os parâmetros de instruções de emissão. Há vários tipos de expressões compatíveis com a linguagem. Todas as expressões no idioma são baseadas em cadeia de caracteres, o que significa que elas tomam cadeias de caracteres como entrada e produzem cadeias de caracteres. Não há suporte para números ou outros tipos de dados, como data/hora, em expressões. Veja a seguir os tipos de expressões compatíveis com o idioma:

• Literal de cadeia de caracteres: valor da cadeia de caracteres, delimitado pelo caractere de aspas (“) nos dois lados.

• Concatenação de expressões da cadeia de caracteres: o resultado é uma cadeia de caracteres que é produzida pela concatenação dos valores à esquerda e à direita.

• Chamada de função: a função é identificada por um identificador e os parâmetros são passados como uma vírgula -delimited lista de expressões entre colchetes (" ( )" ).

• O acesso de propriedade da declaração na forma de um nome de propriedade de DOT do nome de variável: o resultado do valor da propriedade da declaração identificada para determinada avaliação de variável. A variável deve primeiro ser associada a um seletor de declarações antes de poder ser usada dessa forma. É ilegal usar a variável associada a um seletor de declarações dentro das restrições para esse mesmo seletor de declarações.

As seguintes propriedades declaradas estão disponíveis para acesso:

• Reivindicação.Tipo

• Claim.Value

• Claim.Issuer

• Claim.OriginalIssuer

• Claim.ValueType

• Claim.Properties[property_name] (Essa propriedade retornará uma cadeia de caracteres vazia se a propriedade _name não puder ser encontrada na coleção de propriedades da declaração. )

Você pode usar a função RegexReplace para chamar dentro de uma expressão. Essa função usa uma expressão de entrada e a compara ao padrão fornecido. Se o padrão corresponder, a saída da correspondência é substituída pelo valor de substituição.

Existem funções

A função Exists pode ser usada em uma condição para avaliar se uma declaração que corresponde à condição existe no conjunto de declarações de entrada. Se houver alguma reivindicação correspondente, o aviso de emissão será chamado apenas uma vez. No exemplo a seguir, a declaração de "origem" é emitida exatamente uma vez , se houver pelo menos uma declaração na coleção de conjuntos de declarações de entrada que tenha o emissor definido como "MSFT", não importa quantas declarações tenham o emissor definido como "MSFT". Usar essa função impede que declarações duplicadas sejam emitidas.

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

Corpo da regra

O corpo da regra pode conter apenas uma única declaração de emissão. Se as condições forem usadas sem usar a função Exists, o corpo da regra é executado uma vez para cada vez em que houver a correspondência da parte de condições.

Referências adicionais

Criar uma regra para enviar declarações usando uma regra personalizada