Quando usar uma regra de declaração de transformação

• Aplica-se a:

  ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016

Você pode usar essa regra nos Serviços de Federação do Ative Directory (AD FS) quando precisar mapear um tipo de declaração de entrada para um tipo de declaração de saída e, em seguida, aplicar uma ação que determinará qual saída deve ocorrer com base nos valores originados na declaração de entrada. Ao usar essa regra, você passa ou transforma declarações que correspondem à lógica da regra a seguir, com base em qualquer uma das opções configuradas na regra, conforme descrito na tabela a seguir.

Opção de regra	Lógica da regra
Passe por todas as solicitações recebidas	Se o tipo de declaração de entrada for igual ao tipo de declaração especificado e o valor for igual a qualquer valor, então passe a declaração com o tipo de declaração de saída igual ao tipo de declaração especificado
Substitua um valor de declaração de entrada por um valor de declaração de saída diferente	Se o tipo de declaração de entrada for igual a e estiver especificado como tipo de declaração, e se o valor for igual a e estiver especificado como valor de declaração, então transforme a declaração usando como novo valor de declaração de saída o valor de declaração especificado e com o tipo de declaração de saída o tipo de declaração especificado.
Substituindo declarações de sufixo de email de entrada por um novo sufixo de email	Se o tipo de declaração de entrada igualar ao tipo de declaração especificado e o valor corresponder a qualquer sufixo de valor, então transforme a declaração com um novo valor de saída , um sufixo de valor especificado e um tipo de declaração de saída conforme o tipo de declaração especificado.

As seções a seguir fornecem uma introdução básica às regras de reivindicação e fornecem mais detalhes sobre quando usar essa regra.

Sobre as regras de reclamação

Uma regra de declaração representa uma instância da lógica de negócios que aceitará uma declaração de entrada, aplicará uma condição a ela (se x então y) e produzirá uma declaração de saída com base nos parâmetros da condição. A lista a seguir descreve dicas importantes que você deve saber sobre as regras de sinistro antes de ler mais neste tópico:

• No snap-in de Gestão do AD FS, as regras de declaração só podem ser criadas utilizando modelos de regras de declaração

• As regras de declaração processam as declarações de entrada, quer diretamente de um fornecedor de declarações (como o Active Directory ou outro Serviço de Federação), quer a partir da saída das regras de transformação de aceitação numa relação de confiança do fornecedor de declarações.

• As regras de declaração são processadas pelo mecanismo de emissão de declarações em ordem cronológica dentro de um determinado conjunto de regras. Ao definir a precedência nas regras, você pode refinar ou filtrar ainda mais as declarações geradas por regras anteriores dentro de um determinado conjunto de regras.

• Os modelos de regra de declaração sempre exigirão que você especifique um tipo de declaração de entrada. No entanto, você pode processar vários valores de declaração com o mesmo tipo de declaração usando uma única regra.

Para obter informações mais detalhadas sobre regras de reivindicação e conjuntos de regras de reivindicação, consulte The Role of Claim Rules. Para obter mais informações sobre como as regras são processadas, consulte A função do mecanismo de declarações. Para obter mais informações sobre como os conjuntos de regras de declaração são processados, consulte The Role of the Claims Pipeline.

Passe por todos os valores de sinistro

Ao usar esta ação, todos os valores de reivindicação de entrada que têm como chave um tipo de reivindicação de entrada especificado são mapeados para um tipo de reivindicação de saída especificado antes de serem enviados como reivindicações de saída em tokens assinados pelo seu Serviço de Federação.

Por exemplo, quando uma regra é definida com a opção lógica Transitar por todos os valores de declaração e o tipo de declaração de entrada de Grupo e o tipo de declaração de saída de Função são especificados, todos os valores de declaração de entrada que fluem do emissor são copiados individualmente em novas declarações de saída como Função.

Transformar uma reivindicação

No AD FS, o termo transformação de declarações significa substituir um valor de declaração de entrada por um valor de declaração de saída diferente. É a regra "Transformar uma Declaração de Entrada" que torna essa função possível. Dentro das propriedades desta regra, você pode definir condições para transformar valores de entrada com um valor de declaração de saída diferente com base no tipo de declaração de entrada especificado.

Por exemplo, conforme mostrado na ilustração a seguir, quando uma regra é definida com a condição de substituir um valor de entrada por um valor de declaração de saída diferente, todos os tipos de declaração de entrada de Grupo são mapeados para novos tipos de declaração de saída de Função. Nesse caso, o valor da declaração de entrada do Comprador é substituído pelo novo valor da declaração de saída de Admin.

Você também pode usar essa regra para aplicar uma condição que substituirá todas as declarações de entrada por um valor de sufixo de email especificado por um novo valor. Por exemplo, você pode definir uma condição nesta regra para alterar todos os valores de declaração com o sufixo de sales.corp.fabrikam.com para fabrikam.com.

Configurando esta regra em uma relação de confiança do provedor de declarações

Quando você usa uma relação de confiança do provedor de declarações, essa regra pode ser configurada para transformar declarações de entrada do provedor de declarações em equivalentes confiáveis. Os tipos de declaração ou valores de declaração podem ter um significado diferente em sua organização do que nas organizações de provedores de declarações. Você pode usar esta regra para normalizar os tipos e valores de reivindicações que vêm do provedor de reivindicações, de forma que seus equivalentes de saída possam ser compreendidos pela parte confiável.

Configurando esta regra em uma relação de confiança de terceira parte confiável

Quando você usa uma relação de confiança de terceira parte confiável, essa regra pode ser configurada para transformar declarações para a terceira parte confiável específica. Os tipos ou valores de declaração podem ter um significado diferente para uma terceira parte confiável específica, e essa regra possibilita que você altere os tipos e valores de declaração de saída para uma única terceira parte confiável.

Como criar esta regra

Você cria essa regra usando o idioma da regra de declaração ou usando o modelo de regra Transformar uma Declaração de Entrada no snap-in Gerenciamento do AD FS. Este modelo de regra fornece as seguintes opções de configuração:

• Especificar um nome de regra de declaração

• Transformar um tipo de declaração de entrada específico em um tipo de declaração de saída especificado

• Passe por todos os valores de reclamação.

• Substitua um valor de declaração de entrada por um valor de declaração de saída diferente

• Substitua as declarações de sufixo de email de entrada por um novo sufixo de e-mail

Para obter mais instruções sobre como criar esse modelo, consulte Criar uma regra para transformar uma declaração de entrada no Guia de Implantação do AD FS.

Usando a linguagem de regras de reivindicação

Se a declaração de saída tiver de ser construída a partir do conteúdo de mais de uma declaração de entrada, você deverá usar uma regra personalizada. Se o valor da declaração de saída tiver de ser baseado no valor da declaração de entrada, mas com conteúdo adicional, você também deverá usar uma regra personalizada nesse contexto. Para obter mais informações, consulte Quando usar uma regra de declaração personalizada.

Exemplos de como construir uma sintaxe de regra de transformação

Ao usar a sintaxe da linguagem da regra de declaração para transformar declarações, você pode definir uma propriedade da declaração transformada para um novo valor literal. Por exemplo, a regra a seguir altera o valor das declarações de função de "Administradores" para "root", mantendo o tipo de declaração inalterado.

c:[type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/role", value == "Administrators"]  => issue(type = c.type, value = "root");

Expressões regulares também podem ser usadas para transformações de declaração. Por exemplo, a regra a seguir definirá o domínio nas declarações de nome de usuário do Windows no formato DOMAIN\USER como FABRIKAM:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"] => issue(type = c.type, value = regexreplace(c.value, "(?<domain>[^\\]+)\\(?<user>.+)", "FABRIKAM\${user}"));

Práticas recomendadas para a criação de regras personalizadas

As transformações de declarações podem ser aplicadas seletivamente às declarações selecionadas usando recursos básicos de filtragem. Cada uma das propriedades de declaração usadas para filtragem pode receber valores atribuídos, com as seguintes advertências:

Reivindicar propriedade	Descrição
Tipo, Valor, TipoDeValor	Essas propriedades serão usadas com mais freqüência para atribuições. No mínimo, o tipo e o valor devem ser especificados para a declaração transformada resultante.
Emissor	Embora a linguagem da regra de declaração permita definir o Emissor de uma reivindicação, isso geralmente não é aconselhável. O emissor de uma declaração não é serializado no token. Quando um token é recebido, a propriedade Issuer de todas as declarações é definida como o identificador do servidor de federação que assinou o token. Assim, definir o emissor de uma declaração nas regras não terá efeito sobre o conteúdo do token e a configuração será perdida quando a reivindicação for empacotada em um token. O único cenário em que a definição do emissor de uma declaração faz sentido é se ela for definida como um valor específico no conjunto de regras do provedor de declarações e o conjunto de regras da terceira parte confiável for criado com regras que façam referência a esse valor específico. Se a propriedade Issuer não estiver explicitamente definida como um valor em uma regra de declaração, o mecanismo de emissão de declarações a definirá como "AUTORIDADE LOCAL".
OriginalIssuer	À semelhança do Emitente, o OriginalIssuer não deve, em geral, ser explicitamente atribuído um valor. Ao contrário de Issuer, a propriedade OriginalIssuer é serializada no token, mas a expectativa dos consumidores de token é que, se definida, ela contenha o identificador do servidor de federação que emitiu originalmente uma declaração.
Propriedades	Conforme descrito na seção anterior, o conjunto de propriedades de uma reivindicação não é mantido no token, portanto, as atribuições a propriedades só devem ser feitas se as políticas locais subsequentes fizerem referência às informações armazenadas na propriedade.

Para obter mais informações sobre como usar o idioma da regra de declaração, consulte The Role of the Claim Rule Language.