Validar JWT

  • Artigo

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

A validate-jwt política impõe a existência e a validade de um token da Web JSON (JWT) suportado extraído de um cabeçalho HTTP especificado, extraído de um parâmetro de consulta especificado ou correspondente a um valor específico.

Nota

Para validar um JWT fornecido pelo serviço Microsoft Entra, o Gerenciamento de API também fornece a validate-azure-ad-token política.

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Para ajudá-lo a configurar essa política, o portal fornece um editor guiado baseado em formulários. Saiba mais sobre como definir ou editar políticas de Gerenciamento de API.

Declaração de política

<validate-jwt
    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"
    require-expiration-time="true | false"
    require-scheme="scheme"
    require-signed-tokens="true | false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, for example, https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <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 claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Atributos

Atributo Description Necessário Predefinição
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. N/A
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 para retornar 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".
exigir-expiração-tempo Booleano. Especifica se uma declaração de expiração é necessária no token. São permitidas expressões de política. Não verdadeiro
require-regime O nome do esquema de token, por exemplo, "Portador". Quando esse atributo for definido, a política garantirá que o esquema especificado esteja presente no valor do cabeçalho Authorization. São permitidas expressões de política. No N/A
require-signed-tokens Booleano. Especifica se um token precisa ser assinado. São permitidas expressões de política. Não verdadeiro
distorção do relógio Intervalo de tempo. Use para especificar a diferença de tempo máxima esperada entre os relógios do sistema do emissor do token e a instância de Gerenciamento de API. São permitidas expressões de política. Não 0 segundos
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
openid-config Adicione um ou mais desses elementos para especificar uma URL de ponto de extremidade de configuração OpenID compatível a partir da qual as chaves de assinatura e o emissor podem ser obtidos.

A configuração, incluindo o JSON Web Key set (JWKS), é extraída do ponto de extremidade a cada 1 hora e armazenada em cache. Se o token que está sendo validado fizer referência a uma chave de validação (usando kid declaração) que está faltando na configuração em cache, ou se a recuperação falhar, o Gerenciamento de API extrai do ponto de extremidade no máximo uma vez a cada 5 minutos. Estes intervalos estão sujeitos a alterações sem aviso prévio.

A resposta deve ser de acordo com as especificações, conforme definido no URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Para o Microsoft Entra ID, use o ponto de extremidade de metadados OpenID Connect configurado no registro do seu aplicativo, como:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- v2 Multi-Inquilino https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
- Inquilino cliente (pré-visualização) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Substituindo o nome ou ID do locatário do diretório, por exemplo contoso.onmicrosoft.com, por {tenant-name}.		 Não
chaves de assinatura do emissor Uma lista de chaves de segurança codificadas em Base64, em key subelementos, usadas para validar tokens assinados. Se várias chaves de segurança estiverem presentes, cada chave será tentada até que todas se esgotem (caso em que a validação falha) ou uma seja bem-sucedida (útil para a substituição de tokens).

Opcionalmente, especifique uma chave usando o id atributo para corresponder a uma kid declaração. Para validar um token assinado com uma chave assimétrica, especifique opcionalmente a chave pública usando um certificate-id atributo com valor o identificador de um certificado carregado no Gerenciamento de API ou o módulo n RSA e o par de expoentes e da chave de assinatura no formato codificado em Base64url.		 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.

Opcionalmente, especifique uma chave usando o id atributo para corresponder a uma kid declaração. Para descriptografar um token criptografado com uma chave assimétrica, especifique opcionalmente a chave pública usando um certificate-id atributo com valor o identificador de um certificado carregado no Gerenciamento de API ou o módulo n RSA e o par de expoentes e da chave no formato codificado em Base64url.		 Não
Audiências Uma lista de declarações de audiência aceitáveis, em audience subelementos, que podem estar presentes no token. Se vários valores de audiência 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. Pelo menos um público deve ser especificado. Não
emitentes Uma lista de entidades aceitáveis, em issuer subelementos, que emitiram o token. Se vários valores do emissor 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. Não
reclamações-obrigatórias Uma lista de declarações, em claim subelementos, que devem estar presentes no token para que ele seja considerado válido. Quando várias declarações estão presentes, o token deve corresponder aos valores de declaração de acordo com o match valor do atributo. Não

atributos-chave

Atributo Description Necessário Predefinição
id String. Identificador usado para corresponder kid à declaração apresentada no JWT. No N/A
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
n Módulo da chave pública usada para verificar o emissor de um token assinado com uma chave assimétrica. Deve ser especificado com o valor do expoente e. Expressões de política não são permitidas. No N/A
e Expoente da chave pública usada para verificar o emissor de um token assinado com uma chave assimétrica. Deve ser especificado com o valor do módulo n. Expressões de política não são permitidas. No N/A

atributos de declaração

Atributo Description Necessário Predefinição
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.		 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. No N/A

Utilização

Notas de utilização

  • A validate-jwt política requer que a exp declaração registrada seja incluída no token JWT, a menos que require-expiration-time o atributo seja especificado e definido como false.
  • A política suporta algoritmos de assinatura simétricos e assimétricos:
    • Simétrico - Os seguintes algoritmos de encriptação são suportados: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • Se usada na política, a chave deve ser fornecida embutida dentro da política no formulário codificado em Base64.
    • Assimétrico - Os seguintes algoritmos de encriptação são suportados: PS256, RS256, RS512.
      • Se usada na política, a chave pode ser fornecida por meio de um ponto de extremidade de configuração OpenID ou fornecendo a ID de um certificado carregado (no formato PFX) que contém a chave pública ou o par módulo-expoente da chave pública.
  • Para configurar a política com um ou mais pontos finais de configuração do OpenID para utilização com um gateway autoalojado, os URLs dos pontos finais de configuração do OpenID também têm de estar acessíveis pelo gateway de cloud.
  • 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-jwt 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.
  • Ao usar um cabeçalho personalizado (header-name), o esquema necessário configurado (require-scheme) será ignorado. Para usar um esquema necessário, os Authorization tokens JWT devem ser fornecidos no cabeçalho.

Exemplos

Validação de token simples

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Validação de token com certificado RSA

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Validação de token de locatário único do Microsoft Entra ID

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Validação de token de locatário do cliente Microsoft Entra ID

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

Validação de token B2C do Azure Ative Directory

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Autorizar o acesso a operações com base em declarações de token

Este exemplo mostra como usar a política para autorizar o validate-jwt acesso a operações com base no valor de declarações de token.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

Conteúdos relacionados

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