Validar token do Microsoft Entra

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

A política de validate-azure-ad-token impõe a existência e a validade de um JWT (token Web JSON) fornecido pelo serviço Microsoft Entra (anteriormente chamado de Azure Active Directory) para um conjunto especificado de entidades de segurança no diretório. O JWT pode ser extraído de um cabeçalho HTTP, parâmetro de consulta ou valor fornecido usando uma expressão de política ou variável de contexto.

Observação

Para validar um JWT fornecido por um provedor de identidade diferente do Microsoft Entra, o Gerenciamento de API também fornece a política genérica validate-jwt.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Microsoft Entra</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Microsoft Entra</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Atributos

Atributo Descrição Obrigatório Padrão
tenant-id ID ou URL do locatário do Microsoft Entra ID ou um dos seguintes locatários conhecidos:

- organizations ou https://login.microsoftonline.com/organizations – para permitir tokens de contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra)
- common ou https://login.microsoftonline.com/common – para permitir tokens de contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra) e contas pessoais da Microsoft (por exemplo, Skype, Xbox)

Expressões de política são permitidas.		 Sim N/D
header-name O nome do cabeçalho HTTP contendo o token. Expressões de política são permitidas. É necessário especificar header-name, query-parameter-name ou token-value. Authorization
nome do parâmetro de consulta O nome do parâmetro de consulta que contém o token. Expressões de política são permitidas. É necessário especificar header-name, query-parameter-name ou token-value. N/D
token-value Expressão que retorna uma cadeia de caracteres que contém o token. Você não deve retornar Bearer como parte do valor do token. Expressões de política são permitidas. É necessário especificar header-name, query-parameter-name ou token-value. N/D
failed-validation-httpcode O código de status HTTP para retornar se o JWT não passar na validação. Expressões de política são permitidas. Não 401
failed-validation-error-message Mensagem de erro para retornar no corpo da resposta HTTP se o JWT não passar na validação. Esta mensagem deve conter quaisquer caracteres especiais adequadamente seguidos por caracteres de escape. Expressões de política são permitidas. Não A mensagem de erro padrão depende do problema de validação, por exemplo, "O JWT não está presente."
output-token-variable-name Cadeia de caracteres. Nome da variável de contexto que receberá o valor de token como um objeto do tipo Jwt após a validação de token bem-sucedida. Expressões de política não são permitidas. Não N/D

Elementos

Elemento Descrição Obrigatório
públicos-alvo Contém uma lista de declarações de público-alvo aceitáveis que podem estar presentes no token. Se vários valores audience estiverem presentes, cada valor será tentado até que todos estejam esgotados (nesse caso, a validação falhará) ou até que um seja bem-sucedido. Expressões de política são permitidas. No
backend-application-ids Contém uma lista de IDs de aplicativo de back-end aceitáveis. Isso só é necessário em casos avançados para a configuração de opções e geralmente pode ser removido. Expressões de política não são permitidas. Não
client-application-ids Contém uma lista de IDs de aplicativo cliente aceitáveis. Se vários elementos application-id estiverem presentes, cada valor será tentado até que todos estejam esgotados (nesse caso, a validação falhará) ou até que um seja bem-sucedido. Se uma ID de aplicativo cliente não for fornecida, uma ou mais declarações audience deverão ser especificadas. Expressões de política não são permitidas. Não
required-claims Contém uma lista de elementos claim para valores de declaração que devem estar presentes no token para que seja considerado válido. Quando o atributo match é definido como all, cada valor de declaração na política deve estar presente no token para que a validação seja bem-sucedida. Quando o atributo match é definido como any, pelo menos uma declaração deve estar presente no token para que a validação seja bem-sucedida. Expressões de política são permitidas. Não
decryption-keys Uma lista de key subelementos, usada para descriptografar um token assinado com uma chave assimétrica. Se várias chaves estiverem presentes, cada chave será testada até que todas se esgotem (caso em que a validação falha) ou uma chave seja bem-sucedida.

Especifique a chave pública usando um certificate-idatributo com valor definido para o identificador de um certificado carregado no Gerenciamento de API.		 Não

atributos de declaração

Atributo Descrição Obrigatório Padrão
name Nome da declaração, como espera-se que apareça no token. Expressões de política são permitidas. Sim N/D
match O atributo match no elemento claim especifica se todos os valores de declaração na política devem estar presentes no token para que a validação seja bem-sucedida. Os valores possíveis são:

- all – todos os valores de declaração na política devem estar presentes no token para que a validação seja bem-sucedida.

- any – pelo menos um valor de declaração na política deve estar presente no token para que a validação seja bem-sucedida.

Expressões de política são permitidas.		 Não all
separator Cadeia de caracteres. Especifica um separador (por exemplo, ",") a ser usado para extrair um conjunto de valores de uma declaração com valores múltiplos. Expressões de política são permitidas. No N/D

Atributos de chave

Atributo Descrição Obrigatório Padrão
ID do certificado Identificador de uma entidade de certificado carregada no API Management, usada para especificar a chave pública para verificar um token assinado com uma chave assimétrica. Yes N/D

Uso

Observações de uso

  • Você pode usar políticas de restrição de acesso em escopos diferentes para finalidades distintas. Por exemplo, você pode proteger toda a API com a autenticação do Microsoft Entra aplicando a política validate-azure-ad-token no nível da API ou pode aplicá-la no nível de operação da API e usar claims para um controle mais granular.
  • Não há suporte para a ID do Microsoft Entra para clientes (versão prévia).

Exemplos

Validação de token simples

A política a seguir é a forma mínima da política validate-azure-ad-token. Ele espera que o JWT seja fornecido no cabeçalho Authorization padrão usando o esquema Bearer. Neste exemplo, a ID do locatário do Microsoft Entra e a ID do aplicativo cliente são fornecidas usando valores nomeados.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

Validar se o público-alvo e a declaração estão corretos

A política a seguir verifica se o público-alvo é o nome do host da instância de Gerenciamento de API e se a declaração ctry é US. A ID de locatário da Microsoft é o locatário conhecido organizations, que permite tokens de contas de qualquer diretório organizacional. O nome do host é fornecido usando uma expressão de política e a ID do aplicativo cliente é fornecida usando um valor nomeado. O JWT decodificado é fornecido na variável jwt após a validação.

Para obter mais detalhes sobre declarações opcionais, leia Fornecer declarações opcionais ao seu aplicativo.

<validate-azure-ad-token tenant-id="organizations" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

Conteúdo relacionado

Para obter mais informações sobre como trabalhar com políticas, consulte: