Política VerifyJWT

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O que

Verifica a assinatura em um JWT recebido de clientes ou outros sistemas. Essa política também extrai as declarações em variáveis de contexto para que as políticas ou condições subsequentes possam examinar esses valores e tomar decisões de autorização ou roteamento. Consulte a visão geral das políticas do JWS e do JWT para uma introdução detalhada.

Quando essa política é executada, o Edge verifica a assinatura de um JWT e se ele é válido de acordo com o prazo de validade e não antes, se estiverem presentes. A política também pode verificar os valores de declarações específicas no JWT, como o assunto, o emissor, o público ou o valor de declarações adicionais.

Se o JWT for verificado e válido, todas as declarações contidas nele serão extraídas em variáveis de contexto para uso por políticas ou condições subsequentes, e a solicitação poderá continuar. Se não for possível verificar a assinatura do JWT ou se o JWT for inválido devido a um dos carimbos de data/hora, todo o processamento será interrompido e um erro será retornado na resposta.

Para saber mais sobre as partes de um JWT e como elas são criptografadas e assinadas, consulte RFC7519.

Vídeo

Assista a um breve vídeo para saber como verificar a assinatura em um JWT.

Amostras

Verificar um JWT assinado com o algoritmo HS256

Esta política de exemplo verifica um JWT assinado com o algoritmo de criptografia HS256, ou HMAC, usando uma soma de verificação SHA-256. O JWT é transmitido na solicitação do proxy usando um parâmetro de formulário chamado jwt. A chave está contida em uma variável chamada private.secretkey. Veja no vídeo acima um exemplo completo, incluindo como fazer uma solicitação à política.

A configuração da política inclui as informações que o Edge precisa para decodificar e avaliar o JWT, por exemplo, onde encontrar o JWT (em uma variável de fluxo especificada no elemento de origem), o algoritmo de assinatura obrigatório, onde encontrar a chave secreta (armazenada em uma variável de fluxo do Edge, que pode ter sido recuperada da KVM do Edge, por exemplo) e um conjunto de declarações necessárias e os valores delas.

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

A política grava a saída em variáveis de contexto para que as políticas ou condições subsequentes no proxy de API possam examinar esses valores. Consulte Variáveis de fluxo para ver uma lista das variáveis definidas por essa política.

Verificar um JWT assinado com o algoritmo RS256

Esta política de exemplo verifica um JWT assinado com o algoritmo RS256. Para verificar, você precisa fornecer a chave pública. O JWT é transmitido na solicitação do proxy usando um parâmetro de formulário chamado jwt. A chave pública está contida em uma variável chamada public.publickey. Veja no vídeo acima um exemplo completo, incluindo como fazer uma solicitação à política.

Consulte a referência de elemento para detalhes sobre os requisitos e as opções de cada elemento desta política de amostra.

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

Para a configuração acima, um JWT com este cabeçalho …

{
  "typ" : "JWT", 
  "alg" : "RS256"
}

E este payload…

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

… será considerado válido, se a assinatura puder ser verificada com a chave pública fornecida.

Um JWT com o mesmo cabeçalho, mas com este payload…

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

… Será determinado como inválido, mesmo que a assinatura seja verificada, porque a declaração "sub" incluída no JWT não corresponde ao valor obrigatório do elemento "Subject", conforme especificado na configuração da política.

A política grava a saída em variáveis de contexto para que as políticas ou condições subsequentes no proxy de API possam examinar esses valores. Consulte Variáveis de fluxo para ver uma lista das variáveis definidas por essa política.

Como definir os elementos principais

Os elementos usados para especificar a chave usada para verificar o JWT dependem do algoritmo escolhido, conforme mostrado na tabela a seguir:

Algoritmo Elementos-chave
HS*
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>
RS*, ES*, PS*
<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

ou

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

ou

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>
*Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Referência de elemento

A referência de política descreve os elementos e atributos da política "Verificar JWT".

Observação: a configuração varia um pouco dependendo do algoritmo de criptografia utilizado. Consulte os Amostras para ver exemplos que demonstram configurações para casos de uso específicos.

Atributos que se aplicam ao elemento de nível superior

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

Os seguintes atributos são comuns a todos os elementos pai de política.

Atributo Descrição Padrão Presença
name O nome interno da política. Os caracteres que podem ser usados no nome são restritos a: A-Z0-9._\-$ %. No entanto, a IU de gerenciamento de borda aplica outras restrições, como a remoção automática de caracteres não alfanuméricos.

Opcionalmente, use o elemento <displayname></displayname> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

N/A Obrigatório
continueOnError Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

false Opcional
ativado Defina como true para aplicar a política.

Defina como false para "desativar" a política. A política não será aplicada mesmo se permanecer anexada a um fluxo.

verdadeiro Opcional
async Esse atributo está obsoleto. false Descontinuado

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

Padrão Se você omitir esse elemento, o valor do atributo name da política será usado.
Presença Opcional
Tipo String

<Algorithm>

<Algorithm>HS256</Algorithm>

Especifica o algoritmo de criptografia para assinar o token. Os algoritmos RS*/PS*/ES* empregam um par de chaves públicas/secretas, enquanto os algoritmos HS* empregam um secret compartilhado. Consulte também Sobre algoritmos de criptografia de assinatura.

É possível especificar vários valores separados por vírgulas. Por exemplo, "HS256, HS512" ou "RS256, PS256". No entanto, não é possível combinar algoritmos HS* e ES* com nenhum outro porque eles exigem um tipo de chave específico. É possível combinar algoritmos RS* e PS*.

Padrão N/A
Presença Obrigatório
Tipo String de valores separados por vírgulas
Valores válidos HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

A política verifica se a declaração de público no JWT corresponde ao valor especificado na configuração. Se não houver correspondência, a política gerará um erro. Essa declaração identifica os destinatários para quem o JWT é destinado. Esta é uma das declarações registradas mencionadas em RFC7519.

Padrão N/A
Presença Opcional
Tipo String
Valores válidos Uma variável ou string de fluxo que identifica o público.

<AdditionalClaims/Claim>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Valida se o payload do JWT contém as declarações adicionais especificadas e se os valores de declaração declarados correspondem.

Uma declaração adicional usa um nome que não é um dos nomes de declaração JWT registrados padrão. O valor de uma declaração adicional pode ser uma string, um número, um booleano, um mapa ou uma matriz. Um mapa é simplesmente um conjunto de pares de nome/valor. O valor de uma declaração de qualquer um desses tipos pode ser especificado explicitamente na configuração da política ou indiretamente por meio de uma referência a uma variável de fluxo.

Padrão N/A
Presença Opcional
Tipo String, número, booleano ou mapa
Array Defina como true para indicar se o valor é uma matriz de tipos. Padrão: false
Valores válidos Qualquer valor que você queira usar para uma reivindicação adicional.

O elemento <Claim> usa estes atributos:

  • name: obrigatório. O nome da declaração.
  • ref: (opcional) o nome de uma variável de fluxo. Se presente, a política usará o valor dessa variável como a declaração. Se um atributo ref e um valor de declaração explícito forem especificados, o valor explícito será o padrão e será usado se a variável de fluxo referenciada não for resolvida.
  • type: (opcional) uma das seguintes opções: string (padrão), número, booleano ou mapa.
  • array: (opcional) defina como true para indicar se o valor é uma matriz de tipos. Padrão: false

Quando você inclui o elemento <Claim>, os nomes das declarações são definidos estaticamente quando você configura a política. Como alternativa, é possível transmitir um objeto JSON para especificar os nomes das declarações. Como o objeto JSON é transmitidos como uma variável, os nomes das declarações são determinados no ambiente de execução.

Exemplo:

<AdditionalClaims ref='json_claims'/>

Em que a variável json_claims contém um objeto JSON no formulário:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Valida se o cabeçalho JWT contém os pares de nome/valor adicionais de declaração especificados e que os valores de declaração declarados correspondem.

Uma declaração adicional usa um nome que não é um dos nomes de declaração JWT registrados padrão. O valor de uma declaração adicional pode ser uma string, um número, um booleano, um mapa ou uma matriz. Um mapa é simplesmente um conjunto de pares de nome/valor. O valor de uma declaração de qualquer um desses tipos pode ser especificado explicitamente na configuração da política ou indiretamente por meio de uma referência a uma variável de fluxo.

Padrão N/A
Presença Opcional
Tipo

String (padrão), número, booleano ou mapa.

O tipo padrão será String se nenhum tipo for especificado.

Array Defina como true para indicar se o valor é uma matriz de tipos. Padrão: false
Valores válidos Qualquer valor que você queira usar para uma reivindicação adicional.

O elemento <Claim> usa estes atributos:

  • name: obrigatório. O nome da declaração.
  • ref: (opcional) o nome de uma variável de fluxo. Se presente, a política usará o valor dessa variável como a declaração. Se um atributo ref e um valor de declaração explícito forem especificados, o valor explícito será o padrão e será usado se a variável de fluxo referenciada não for resolvida.
  • type: (opcional) uma das seguintes opções: string (padrão), número, booleano ou mapa.
  • array: (opcional) defina como true para indicar se o valor é uma matriz de tipos. Padrão: false

<CustomClaims>

Observação: atualmente, um elemento CustomClaims é inserido quando você adiciona uma nova política GenerateJWT por meio da IU. Este elemento não é funcional e é ignorado. O elemento correto a ser usado é <AdditionalClaims>. A IU será atualizada para inserir os elementos corretos posteriormente.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Verifica se o JWT tem a declaração jti específica. Quando o valor text e o atributo ref estiverem vazios, a política gerará um jti contendo um UUID aleatório. A declaração do ID do JWT (jti) é um identificador exclusivo do JWT. Para mais informações sobre jti, consulte RFC7519.

Padrão N/A
Presença Opcional
Tipo String ou referência.
Valores válidos Uma string ou o nome de uma variável de fluxo que contém o ID.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Defina como "false" se você quiser que a política gere um erro quando qualquer cabeçalho listado no cabeçalho crit do JWT não estiver listado no elemento <KnownHeaders>. Defina como "true" para que a política VerifyJWT ignore o cabeçalho crit.

Um motivo para definir esse elemento como verdadeiro é se você estiver em um ambiente de teste e ainda não estiver pronto para causar uma falha em um cabeçalho ausente.

Padrão false
Presença Opcional
Tipo Booleano
Valores válidos verdadeiro ou falso

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Defina como falso (padrão) se você quiser que a política gere um erro quando um JWT contiver uma declaração iat (Emitida em) que especifica um horário no futuro. Defina como "true" para fazer com que a política ignore iat durante a verificação.

Padrão false
Presença Opcional
Tipo Booleano
Valores válidos verdadeiro ou falso

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Defina como falso se você quiser que a política gere um erro quando qualquer variável referenciada especificada na política não for resolvida. Defina como "true" para tratar qualquer variável não resolvida como uma string vazia (null).

Padrão false
Presença Opcional
Tipo Booleano
Valores válidos verdadeiro ou falso

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

A política verifica se o emissor no JWT corresponde à string especificada no elemento de configuração. Uma declaração que identifica o emissor do JWT. Esse é um dos conjuntos registrados de declarações mencionados na RFC7519.

Padrão N/A
Presença Opcional
Tipo String ou referência
Valores válidos Tudo

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

A política GenerateJWT usa o elemento <CriticalHeaders> para preencher o cabeçalho crit em um JWT. Exemplo:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

A política VerifyJWT examina o cabeçalho crit no JWT, se existir, e, para cada cabeçalho listado, ele verifica se o elemento <KnownHeaders> também lista esse cabeçalho. O elemento <KnownHeaders> pode conter um superconjunto dos itens listados em crit. É necessário que todos os cabeçalhos listados em crit sejam listados no elemento <KnownHeaders>. Qualquer cabeçalho encontrado pela política em crit que também não esteja listado em <KnownHeaders> faz com que a política VerifyJWT falhe.

Se quiser, configure a política VerifyJWT para ignorar o cabeçalho crit definindo o elemento <IgnoreCriticalHeaders> como true.

Padrão N/A
Presença Opcional
Tipo Matriz de strings separadas por vírgulas
Valores válidos Uma matriz ou o nome de uma variável que contém a matriz.

<PublicKey/Certificate>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

Especifica o certificado assinado usado para verificar a assinatura no JWT. Use o atributo ref para transmitir o certificado assinado em uma variável de fluxo ou especifique o certificado codificado em PEM diretamente. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Padrão N/A
Presença Para verificar um JWT assinado com um algoritmo RSA, você precisa usar os elementos de Certificado, JWK ou Valor.
Tipo String
Valores válidos Uma variável de fluxo ou string.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Especifica um valor no formato JWKS (RFC 7517, em inglês) que contém um conjunto de chaves públicas. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Se o JWT de entrada receber um ID de chave presente no conjunto de JWKS, a política usará a chave pública correta para verificar a assinatura JWT. Para detalhes sobre esse recurso, consulte Como usar um conjunto de chaves da Web JSON (JWKS) para verificar um JWT.

Se você buscar o valor de um URL público, o Edge armazenará o JWKS em cache por um período de 300 segundos. Quando o cache expira, o Edge busca o JWKS novamente.

Padrão N/A
Presença Para verificar um JWT usando um algoritmo RSA, é necessário usar os elementos de Certificado, JWKS ou Valor.
Tipo String
Valores válidos Uma variável de fluxo, valor de string ou URL.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

Especifica a chave pública ou o certificado público usado para verificar a assinatura no JWT. Use o atributo ref para transmitir a chave/certificado em uma variável de fluxo ou especifique a chave codificada em PEM diretamente. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512, ou ES256/ES384/ES512.

Padrão N/A
Presença Para verificar um JWT assinado com um algoritmo RSA, você precisa usar os elementos de Certificado, JWK ou Valor.
Tipo String
Valores válidos Uma variável de fluxo ou string.

<SecretKey/Value>

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.your-variable-name"/>
</SecretKey>

Fornece a chave secreta usada para verificar ou assinar tokens com um algoritmo HMAC. Use somente quando o algoritmo for HS256, HS384 ou HS512.

Padrão N/A
Presença Obrigatório para algoritmos HMAC.
Tipo String
Valores válidos

Para encoding, os valores válidos são hex, base16, base64 ou base64url. Os valores de codificação hex e base16 são sinônimos.

Use o atributo ref para passar a chave em uma variável de fluxo.

Observação: no caso de uma variável de fluxo, ela precisa ter o prefixo "particular". Por exemplo, private.mysecret

<Source>

<Source>jwt-variable</Source>

Se presente, especifica a variável de fluxo em que a política espera encontrar o JWT a ser verificado.

Padrão request.header.authorization. Consulte a observação acima para informações importantes sobre o padrão.
Presença Opcional
Tipo String
Valores válidos Um nome de variável do Edge flow.

<Subject>

<Subject>subject-string-here</Subject>

A política verifica se o assunto no JWT corresponde à string especificada na configuração da política. Essa declaração identifica ou faz uma declaração sobre o assunto do JWT. Este é um dos conjuntos de declarações padrão mencionados em RFC7519.

Padrão N/A
Presença Opcional
Tipo String
Valores válidos Qualquer valor que identifica exclusivamente um assunto.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

O "período de carência" dos horários. Por exemplo, se a cota de tempo estiver configurada como 60 segundos, um JWT expirado será tratado como ainda válido, por 60 segundos após a expiração declarada. O intervalo de antes do horário será avaliado de forma semelhante. O padrão é de 0 segundos (sem período de carência).

Padrão 0 segundos (sem período de carência)
Presença Opcional
Tipo String
Valores válidos Um valor ou uma referência a uma variável de fluxo contendo o valor. Os períodos podem ser especificados da seguinte forma:
  • s = segundos
  • m = minutos
  • h = horas
  • d = dias

Variáveis de fluxo

Após a conclusão, as políticas Verificar JWT e Decodificar JWT definem variáveis de contexto de acordo com este padrão:

jwt.{policy_name}.{variable_name}

Por exemplo, se o nome da política for jwt-parse-token, a política armazenará o assunto especificado no JWT para esta variável de contexto: jwt.jwt-parse-token.decoded.claim.sub Para compatibilidade com versões anteriores, ela também vai estar disponível em jwt.jwt-parse-token.claim.subject.

Nome da variável Descrição
claim.audience A declaração de público do JWT. Esse valor pode ser uma string ou uma matriz de strings.
claim.expiry A data/hora de validade, expressa em segundos desde o período.
claim.issuedat A data em que o token foi emitido, expressa em segundos desde o período.
claim.issuer A declaração do emissor do JWT.
claim.notbefore Se o JWT incluir uma declaração nbf, essa variável conterá o valor, expresso em milissegundos desde o período.
claim.subject A declaração do assunto do JWT.
claim.name O valor da declaração nomeada (padrão ou adicional) no payload. Um deles será definido para cada reivindicação no payload.
decoded.claim.name O valor analisável pelo JSON da declaração nomeada (padrão ou adicional) no payload. Uma variável é definida para cada declaração no payload. Por exemplo, é possível usar decoded.claim.iat para recuperar o momento de emissão do JWT, expresso em segundos desde o período. Embora você também possa usar as variáveis de fluxo claim.name, essa é a variável recomendada para acessar uma declaração.
decoded.header.name É o valor analisável pelo JSON de um cabeçalho no payload. Uma variável é definida para cada cabeçalho no payload. Ainda que você também possa usar as variáveis de fluxo header.name, essa é a variável recomendada para acessar um cabeçalho.
expiry_formatted A data/hora de validade, formatada como uma string legível. Exemplo: 2017-09-28T21:30:45.000+0000
header.algorithm O algoritmo de assinatura usado no JWT. Por exemplo, RS256, HS384 e assim por diante. Consulte Parâmetro de cabeçalho (algoritmo) para saber mais.
header.kid O ID da chave, se adicionado quando o JWT foi gerado. Consulte também "Como usar um conjunto de chaves da Web JSON (JWKS)" na visão geral das políticas JWT para verificar um JWT. Consulte Parâmetro de cabeçalho (ID da chave) para mais informações.
header.type Será definido como JWT.
header.name O valor do cabeçalho nomeado (padrão ou adicional). Um deles será definido para cada cabeçalho adicional na parte do cabeçalho do JWT.
header-json O cabeçalho no formato JSON.
is_expired verdadeiro ou falso
payload-claim-names Uma matriz de declarações aceitas pelo JWT.
payload-json
O payload no formato JSON.
seconds_remaining O número de segundos até a expiração do token. Se o token tiver expirado, esse número será negativo.
time_remaining_formatted O tempo restante para expiração do token, formatado como uma string legível. Exemplo: 00:59:59.926
valid No caso de VerifyJWT, essa variável será verdadeira quando a assinatura for verificada e a hora atual for anterior à expiração do token e posterior ao valor notBefore, se estiverem presentes. Caso contrário, ela será falsa.

No caso de DecodeJWT, essa variável não está definida.

Referência de erros

Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falhas para lidar com elas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha Status HTTP Ocorre quando
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Ocorre quando a política de verificação tem vários algoritmos.
steps.jwt.AlgorithmMismatch 401 O algoritmo especificado na política de geração não corresponde ao esperado na política de verificação. Os algoritmos especificados precisam corresponder.
steps.jwt.FailedToDecode 401 A política não conseguiu decodificar o JWT. É possível que o JWT esteja corrompido.
steps.jwt.GenerationFailed 401 A política não pôde gerar o JWT.
steps.jwt.InsufficientKeyLength 401 Para uma chave com menos de 32 bytes para o algoritmo HS256, menos de 48 bytes para o algoritmo HS386 e menos de 64 bytes para o algoritmo HS512.
steps.jwt.InvalidClaim 401 Para uma reivindicação ausente ou incompatibilidade de reivindicação ou um cabeçalho ou cabeçalho ausente.
steps.jwt.InvalidCurve 401 A curva especificada pela chave não é válida para o algoritmo de curva elíptica.
steps.jwt.InvalidJsonFormat 401 JSON inválido encontrado no cabeçalho ou payload.
steps.jwt.InvalidToken 401 Esse erro ocorre quando a verificação de assinatura do JWT falha.
steps.jwt.JwtAudienceMismatch 401 A declaração de público falhou na verificação do token.
steps.jwt.JwtIssuerMismatch 401 A declaração do emissor falhou na verificação do token.
steps.jwt.JwtSubjectMismatch 401 A declaração do assunto falhou na verificação do token.
steps.jwt.KeyIdMissing 401 A política "Verificar" usa um JWKS como uma origem para chaves públicas, mas o JWT assinado não inclui uma propriedade kid no cabeçalho.
steps.jwt.KeyParsingFailed 401 Não foi possível analisar a chave pública com base nas informações de chave fornecidas.
steps.jwt.NoAlgorithmFoundInHeader 401 Ocorre quando o JWT não contém cabeçalho de algoritmo.
steps.jwt.NoMatchingPublicKey 401 A política de verificação usa uma JWKS como fonte para chaves públicas, mas o kid no JWT assinado não está listado na JWKS.
steps.jwt.SigningFailed 401 Em GenerateJWT, para uma chave menor que o tamanho mínimo para os algoritmos HS384 ou HS512
steps.jwt.TokenExpired 401 A política tenta verificar um token expirado.
steps.jwt.TokenNotYetValid 401 O token ainda não é válido.
steps.jwt.UnhandledCriticalHeader 401 Um cabeçalho encontrado pela política de verificação de JWT no cabeçalho crit não está listado em KnownHeaders.
steps.jwt.UnknownException 401 Ocorreu uma exceção desconhecida.
steps.jwt.WrongKeyType 401 Tipo incorreto de chave especificado. Por exemplo, se você especificar uma chave RSA para um algoritmo de curva elíptica ou uma chave de curva para um algoritmo RSA.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém essa política.

Nome do erro Causa Corrigir
InvalidNameForAdditionalClaim A implantação falhará se a declaração usada no elemento filho <Claim> do elemento <AdditionalClaims> for um dos seguintes nomes registrados: kid, iss, sub, aud, iat, exp, nbf ou jti.
InvalidTypeForAdditionalClaim Se a declaração usada no elemento filho <Claim> do elemento <AdditionalClaims> não for do tipo string, number, boolean ou map, a implantação falhará.
MissingNameForAdditionalClaim Se o nome da declaração não for especificado no elemento filho <Claim> do elemento <AdditionalClaims>, a implantação falhará.
InvalidNameForAdditionalHeader Esse erro ocorre quando o nome da declaração usada no elemento filho <Claim> do elemento <AdditionalClaims> é alg ou typ.
InvalidTypeForAdditionalHeader Se o tipo de declaração usado no elemento filho <Claim> do elemento <AdditionalClaims> não for do tipo string, number, boolean ou map, a implantação falhará.
InvalidValueOfArrayAttribute Esse erro ocorre quando o valor do atributo de matriz no elemento filho <Claim> do elemento <AdditionalClaims> não está definido como true ou false.
InvalidValueForElement Se o valor especificado no elemento <Algorithm> não for compatível, a implantação falhará.
MissingConfigurationElement Esse erro ocorrerá se o elemento <PrivateKey> não for usado com algoritmos da família RSA ou se o elemento <SecretKey> não for usado com algoritmos da família HS.
InvalidKeyConfiguration Se o elemento filho <Value> não estiver definido nos elementos <PrivateKey> ou <SecretKey>, a implantação falhará.
EmptyElementForKeyConfiguration Se o atributo de referência do elemento filho <Value> dos elementos <PrivateKey> ou <SecretKey> estiver vazio ou não especificado, a implantação falhará.
InvalidConfigurationForVerify Esse erro ocorrerá se o elemento <Id> for definido no elemento <SecretKey>.
InvalidEmptyElement Este erro ocorre se o elemento <Source> da política de verificação JWT estiver vazio. Se presente, precisa ser definido com um nome de variável de fluxo do Edge.
InvalidPublicKeyValue Se o valor usado no elemento filho <JWKS> do elemento <PublicKey> não usar um formato válido, conforme especificado no RFC 7517, a implantação falhará.
InvalidConfigurationForActionAndAlgorithm Se o elemento <PrivateKey> for usado com algoritmos da família HS ou o elemento <SecretKey> for usado com algoritmos da família RSA, a implantação falhará.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha. fault.name Matches "TokenExpired"
JWT.failed Todas as políticas do JWT definem a mesma variável em caso de falha. JWT.failed = true

Exemplo de resposta de erro

Códigos de falha de política JWT

Para gerenciar erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto em faultstring, porque ele pode mudar.

Exemplo de regra de falha

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>