Validar token do Microsoft Entra

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

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

Nota

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 .

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Saiba mais sobre como definir ou editar 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>Base64 encoded signing key | certificate-id="mycertificate"</key>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Atributos

Atributo Description Necessário Predefinição
tenant-id ID do locatário ou URL do locatário do Microsoft Entra ID ou de 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 de contas pessoais da Microsoft (por exemplo, Skype, XBox)

São permitidas expressões de política.		 Sim N/A
nome do cabeçalho O nome do cabeçalho HTTP que contém o token. São permitidas expressões de política. Um dos header-name, query-parameter-name ou token-value deve ser especificado. Authorization
query-nome-parâmetro O nome do parâmetro de consulta que contém o token. São permitidas expressões de política. Um dos header-name, query-parameter-name ou token-value deve ser especificado. N/A
valor do token 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. São permitidas expressões de política. Um dos header-name, query-parameter-name ou token-value deve ser especificado. N/A
failed-validation-httpcode Código de status HTTP a ser retornado se o JWT não passar na validação. São permitidas expressões de política. Não 401
falha-validação-erro-mensagem Mensagem de erro para retornar no corpo da resposta HTTP se o JWT não passar na validação. Esta mensagem deve ter todos os caracteres especiais escapados corretamente. São permitidas expressões de política. Não A mensagem de erro padrão depende do problema de validação, por exemplo, "JWT não está presente".
output-token-variable-name String. Nome da variável de contexto que receberá o valor do token como um objeto do tipo Jwt após a validação bem-sucedida do token. Expressões de política não são permitidas. No N/A

Elementos

Elemento Description Obrigatório
Audiências Contém uma lista de declarações de público aceitáveis que podem estar presentes no token. Se vários audience valores estiverem presentes, cada valor será tentado até que todos estejam esgotados (caso em que a validação falhará) ou até que um seja bem-sucedido. São permitidas expressões de política. Não
IDs de aplicativos de back-end Contém uma lista de IDs de aplicativos 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
IDs de aplicativo cliente Contém uma lista de IDs de aplicativo cliente aceitáveis. Se vários application-id elementos estiverem presentes, cada valor será tentado até que todos se esgotem (caso em que a validação falha) ou até que um seja bem-sucedido. Se um ID de aplicativo cliente não for fornecido, uma ou mais audience declarações deverão ser especificadas. Expressões de política não são permitidas. Não
reclamações-obrigatórias Contém uma lista de elementos para valores de claim declaração que devem estar presentes no token para que ele seja considerado válido. Quando o match atributo é 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 match atributo é definido como any, pelo menos uma declaração deve estar presente no token para que a validação seja bem-sucedida. São permitidas expressões de política. Não
chaves de desencriptação Uma lista de chaves codificadas em Base64, em key subelementos, usadas para descriptografar os tokens. Se várias chaves de segurança estiverem presentes, cada chave será tentada até que todas as chaves se esgotem (caso em que a validação falha) ou uma chave seja bem-sucedida.

Para descriptografar um token criptografado com uma chave assimétrica, especifique opcionalmente a chave pública usando um certificate-id atributo com valor definido como o identificador de um certificado carregado no Gerenciamento de API.		 Não

atributos de declaração

Atributo Description Necessário Predefinição
nome Nome da declaração como se espera que apareça no token. São permitidas expressões de política. Sim N/A
Jogo O match atributo no claim elemento especifica se cada valor de declaração na política deve estar presente no token para que a validação seja bem-sucedida. Os valores possíveis são:

- all - Cada valor de reivindicação na apólice deve estar presente no token para que a validação seja bem-sucedida.

- any - Pelo menos um valor de reivindicação deve estar presente no token para que a validação seja bem-sucedida.

São permitidas expressões de política.		 Não todos
separador String. Especifica um separador (por exemplo, ",") a ser usado para extrair um conjunto de valores de uma declaração de vários valores. São permitidas expressões de política. No N/A

atributos-chave

Atributo Description Necessário Predefinição
ID do certificado Identificador de uma entidade de certificado carregada no Gerenciamento de API, usado para especificar a chave pública para verificar um token assinado com uma chave assimétrica. No N/A

Utilização

Notas de utilização

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

Exemplos

Validação de token simples

A política a seguir é a forma mínima da validate-azure-ad-token política. Ele espera que o JWT seja fornecido no cabeçalho padrão Authorization usando o Bearer esquema. 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 que o público e a afirmação estão corretos

A política a seguir verifica se a audiência é o nome do host da instância de Gerenciamento de API e se a ctry declaração é US. O ID de locatário da Microsoft é o locatário conhecido organizations , que permite tokens de contas em qualquer diretório organizacional. O nome do host é fornecido usando uma expressão de política e o ID do aplicativo cliente é fornecido usando um valor nomeado. O JWT decodificado é fornecido na variável após a jwt 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údos relacionados

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