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 outro provedor de identidade, 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, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    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 Azure Active Directory</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 Azure Active Directory</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>
</validate-azure-ad-token>

Atributos

Atributo Description Necessário Predefinição
tenant-id ID do locatário ou URL do serviço Microsoft Entra. 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

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

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 nome do host é fornecido usando uma expressão de política, e a ID do locatário do Microsoft Entra e a ID do aplicativo cliente são fornecidas usando valores nomeados. 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="{{aad-tenant-id}}" 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: