Quando usar uma regra de declaração de passagem ou filtro

• Aplica-se a:

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

Você pode usar essa regra no Serviços de Federação do Active Directory (AD FS) quando precisar usar um tipo específico de declaração de entrada e, em seguida, aplicar uma ação que determinará qual saída deve ocorrer com base nos valores de declaração de entrada. Quando você usa essa regra, passa ou filtra quaisquer declarações que correspondem à lógica de regra na tabela a seguir, com base em uma das opções configuradas na regra.

Opção de regras	Lógica de regras
Passar todos os valores da declaração	Se o tipo de declaração de entrada for igual a tipo de declaração especificada e o valor for igual a qualquer valor, passe a declaração
Passar apenas um valor de declaração específica	Se o tipo de declaração de entrada for igual a tipo de declaração especificada e o valor for igual a valor da declaração especificada, passe a declaração
Passar apenas valores de declaração que correspondam a um valor de sufixo de email específico	Se o tipo de declaração de entrada for igual a tipo de declaração especificada e o valor for igual a valor de sufixo especificado, passe a declaração
Passar apenas valores de declaração que iniciam com um valor específico	Se o tipo de declaração de entrada for igual a tipo de declaração especificada e o valor começar com valor de declaração especificada, passe a declaração

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

Sobre as regras de declaração

Uma regra de declaração representa uma instância de lógica de negócios que obterá 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 conhecer sobre as regras de declaração antes de ler mais neste tópico:

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

• Regras de declaração processam declarações de entrada diretamente de um provedor de declarações (como o Active Directory ou outro Serviço de Federação) ou da saída das regras de transformação de aceitação em uma relação de confiança com o provedor 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 em regras, você pode refinar ou filtrar mais as declarações geradas pelas 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 as regras de declaração e os conjuntos de regras de declaração, confira A função das regras de declaração. Para obter mais informações sobre como as regras são processadas, confira 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, confira A função do pipeline de declarações.

Passar todos os valores da declaração

Ao usar essa ação, todos os valores de declaração de entrada para o tipo de declaração especificado são passados como declarações de saída. Por exemplo, quando o tipo de declaração de entrada é especificado como o tipo de declaração de função, todos os valores de declaração de entrada são copiados individualmente em novas declarações de saída com o tipo de saída de Função.

Filtrando uma declaração

No AD FS, o termo filtragem de declarações significa filtrar ou restringir valores de declaração de entrada, para que somente determinados valores sejam passados ou enviados como declarações de saída. É o modelo de regra Passar ou filtrar uma declaração de entrada que torna essa função possível. Dentro das propriedades dessa regra, você pode definir condições para filtrar valores de entrada, para que somente os valores que atendam aos critérios especificados sejam passados.

Por exemplo, você pode usar essa regra para passar apenas declarações que correspondam ao o valor da declaração do Comprador quando o tipo de declaração de entrada corresponder ao tipo de declaração da Função, ou emita apenas declarações sobre o nome do usuário, mas não as declarações contendo cadastro de pessoas físicas do usuário.

Quando você usa uma condição de filtro com essa regra, todas as declarações de entrada são examinadas para determinar quais declarações atendem ao conjunto de critérios definidos pela regra. Todas as outras declarações são ignoradas para que somente os valores da declaração especificada, que correspondem a um tipo de declaração selecionado, passem.

Por exemplo, conforme mostrado na ilustração a seguir, quando uma regra é definida com a condição de filtrar apenas declarações de entrada inseridas no tipo de declaração de UPN e também que terminam com @fabrikam.com, todas as outras declarações de entrada são ignoradas, a menos que atendam aos critérios. Isso inclui a declaração de entrada com o tipo de declaração Endereço de email, mesmo que o valor da declaração termine com @fabrikam.com. Nesse caso, somente a declaração com o valor Nick@fabrikam.com é enviada para a terceira parte confiável.

Configurando essa 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 passar apenas declarações de entrada do provedor de declarações que correspondam a determinadas restrições. Por exemplo, você talvez queira apenas aceitar declarações de email do provedor de declarações; portanto, você usaria esse modelo de regra para aceitar tipos de declaração de email que terminam no nome DNS (Sistema de Nomes de Domínio) do provedor de declarações.

Configurando essa regra em um objeto de confiança de terceira parte confiável

Quando você usa um objeto de confiança de terceira parte confiável, essa regra pode ser configurada para passar ou filtrar declarações de saída que serão enviadas para a terceira parte confiável. Algumas partes confiáveis talvez não compreenda certos tipos de declaração ou determinadas declarações podem conter informações confidenciais que não devem ser enviadas para determinadas terceiras partes. Esse modelo de regra pode ajudar a impor essas políticas para um objeto de confiança de terceira parte confiável específico.

Como criar essa regra

Crie essa regra usando a linguagem de regra de declaração ou o modelo de regra Passar ou filtrar uma declaração de entrada no snap-in de gerenciamento do AD FS. Essa regra fornece as seguintes opções de configuração:

• Especificar um nome de regra de declaração

• Especificar um tipo de declaração de entrada

• Passar todos os valores da declaração

• Passar apenas um valor de declaração específica

• Passar apenas valores de declaração que correspondam a um valor de sufixo de email específico

• Passar apenas valores de declaração que iniciam com um valor específico

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

Usando linguagem de regra de declaração

Se uma declaração dever ser enviada apenas quando o valor da declaração corresponder a um padrão personalizado, você deverá usar uma regra personalizada. Para obter mais informações, consulte Quando usar uma regra personalizada.

Exemplos de como construir uma sintaxe de regras de passagem ou filtro

Uma regra de filtragem simples filtraria declarações com base em uma das propriedades descritas acima. Por exemplo, a seguinte regra passará por todas as declarações de email:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]  => issue(claim  = c);

Filtros podem ser logicamente unidos por AND. Por exemplo, a seguinte regra aceitará todas as declarações de email com o valor johndoe@fabrikam.com:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", value == "johndoe@fabrikam.com "]  => issue(claim  = c);

Nos exemplos acima, os filtros usaram sempre um operador de igualdade. A linguagem de regra de declaração dá suporte aos seguintes operadores:

• == - igual a (diferencia maiúsculas de minúsculas)

• == - diferente de (diferencia maiúsculas de minúsculas)

• =~- correspondência de expressão regular

• !~ - não correspondência de expressão regular

Por exemplo, a seguinte regra aceitará todas as declarações de email não emitidas pelo servidor de federação local que tem um sufixo de boeing.com:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", value =~ "^.*@boeing\.com$" , issuer != "LOCAL AUTHORITY"]  => issue(claim  = c);

Práticas recomendadas para criar regras personalizadas

Um filtro pode ser aplicado a uma ou mais das propriedades de cada declaração, conforme descrito na tabela a seguir.

Propriedade da declaração	Descrição
Type	O tipo de declaração (geralmente representado como um Uri) reflete um contrato implícito entre parceiros em uma federação sobre quais tipos de informações são transmitidos na declaração. Por exemplo, declarações do tipo http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress conterão o endereço de email do usuário.
Valor	O valor da declaração. Por exemplo, uma declaração do tipo http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress pode ter um valor de johndoe@fabrikam.com
ValueType	ValueType representa como as informações contidas no valor da declaração devem ser interpretadas. Normalmente ValueType será definido como http://www.w3.org/2001/XMLSchema#string, mas o valor da declaração pode conter dados codificados Base64Binary (por exemplo, uma imagem) ou uma data, Booliano etc.
Emissor	O emissor representa a parte que emitiu por último as declarações sobre o usuário. Se as declarações forem obtidas em um servidor de federação do provedor de declarações, o emissor de todas as declarações será definido como "LOCAL AUTHORITY". Se as declarações foram recebidas por um servidor de federação do Provedor de Federações, o emissor das declarações será definido como o identificador do provedor de declarações do provedor de declarações que assinou o token. Assim, durante o processamento de regras de declarações recebidas de um provedor de declarações, o emissor de todas as declarações será definido como o mesmo valor. Ao criar regras para uma terceira parte confiável, a propriedade emissora pode ser usada para distinguir entre solicitações originadas de provedores de declarações diferentes.
OriginalIssuer	Essa propriedade de declaração deve transmitir o servidor de federação emitiu originalmente a declaração. Como a propriedade do emissor de declarações está definida para o último servidor de federação que assinou o token, o emissor original é útil em cenários em que uma declaração passou por mais de um servidor de federação (por exemplo, uma terceira parte confiável que recebe um token de um servidor de federação do provedor de federações pode estar interessado nas declarações específicas nas quais o servidor de federação autenticou o usuário)
Propriedades	Além das cinco propriedades descritas acima, cada declaração também tem um recipiente de propriedades no qual as propriedades nomeadas podem ser armazenadas. Essas propriedades não são serializadas no token e só fazem sentido para transmitir informações entre os componentes do pipeline de emissão de declarações dentro do escopo de um servidor de federação único. Por exemplo, configuração de uma propriedade durante processamento de regras do provedor de declarações e depois fazer referência a ela nas regras da terceira parte confiável.