Política VerifyJWT

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A política VerifyJWT verifica um JWT assinado ou descriptografa e verifica um JWT criptografado recebido de clientes ou outros sistemas. Essa política também extrai as declarações em variáveis de contexto para que 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 de JWS e JWT para uma introdução detalhada.

Quando esta política é executada, no caso de um JWT assinado, a Apigee verifica a assinatura do JWT usando a chave de verificação fornecida. No caso de um JWT criptografado, a Apigee descriptografa o JWT usando a chave de descriptografia. Em ambos os casos, a Apigee verifica posteriormente se o JWT é válido de acordo com o prazo de validade e não com antecedência, se estiver presente. 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.

Se a política verifica um JWT assinado ou criptografado, depende do elemento usado para especificar o algoritmo que verifica o JWT:

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

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

Verificar um JWT assinado

Nesta seção, explicamos como verificar um JWT assinado. Para um JWT assinado, use o elemento <Algorithm> para especificar o algoritmo de assinatura da chave.

Exemplos de um JWT assinado

As amostras a seguir ilustram como verificar um JWT assinado.

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 a Apigee precisa para decodificar e avaliar o JWT, como onde encontrar o JWT (em uma variável de fluxo especificada no elemento de origem), o algoritmo de assinatura necessário, para encontrar o segredo (armazenado em uma variável de fluxo da Apigee, que pode ter sido recuperada da KVM da Apigee, por exemplo) e um conjunto de declarações obrigatórias e seus valores.

<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.

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.

As amostras acima usam o elemento <Algorithm>, para que verifiquem um JWT assinado. O elemento <PrivateKey> especifica a chave usada para assinar o JWT. Há outros elementos importantes. O que você usa depende do algoritmo especificado pelo valor de <Algorithm>, conforme descrito na próxima seção.

Como configurar os elementos principais para verificar um JWT assinado

Os elementos a seguir especificam a chave usada para verificar um JWT assinado:

O elemento que você usa depende 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.

Verificar um JWT criptografado

Nesta seção, explicamos como verificar um JWT criptografado. Para um JWT criptografado, use o elemento <Algorithms> para especificar os algoritmos para a assinatura da chave e do conteúdo.

Exemplo para um JWT criptografado

O exemplo a seguir mostra como verificar um JWT criptografado (com <Type> definido como Encrypted), em que:

  • A chave é criptografada com o algoritmo RSA-OAEP-256.
  • O conteúdo é criptografado com o algoritmo A128GCM.
<VerifyJWT name="vjwt-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <Type>Encrypted</Type> 
  <PrivateKey>
    <Value ref="private.rsa_privatekey"/>
  </PrivateKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <TimeAllowance>30s</TimeAllowance>
  <Source>input_var</Source>
</VerifyJWT>

A amostra acima usa o elemento <Algorithms> para verificar um JWT criptografado. O elemento <PrivateKey> especifica a chave que será usada para descriptografar o JWT. Há outros elementos importantes. O que você usa depende do algoritmo especificado pelo valor de <Algorithms>, conforme descrito na próxima seção.

Como configurar os elementos principais para verificar um JWT criptografado

Os elementos a seguir especificam a chave usada para verificar um JWT criptografado:

O elemento que você usa depende do algoritmo de chave de criptografia escolhido, conforme mostrado na tabela a seguir:

Algoritmo Elementos-chave
RSA-OAEP-256 
<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

Observação: a variável especificada precisa ser resolvida para uma chave privada RSA em formato codificado em PEM.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

Observação: a variável especificada precisa ser resolvida para uma chave privada de curva elíptica no formato codificado em PEM.
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.flow-variable-name-here"/>
</SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 
<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>
dir 
<DirectKey>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

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
nome 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 da Apigee impõe outras restrições, como a remoção automática de caracteres que não sã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.

 falso 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. falso 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 criptográfico usado para verificar o token. Use o elemento <Algorithm> para verificar um JWT assinado.

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

<Algoritmos>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Use o elemento <Algorithms> para verificar um JWT criptografado. Esse elemento especifica o algoritmo criptográfico para criptografia de chaves que precisa ter sido usado quando o JWT criptografado foi criado. Essa opção também especifica o algoritmo para criptografia de conteúdo.

Padrão N/A
Presença Obrigatório ao verificar um JWT criptografado
Tipo Complexo

Elementos filhos de <Algorithms>

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <Algorithms>:

Elemento filho Obrigatório? Descrição
<Key> Obrigatório Especifica o algoritmo de criptografia da chave.
<Content> Opcional Especifica o algoritmo de criptografia do conteúdo.

A verificação falhará se:

  • o algoritmo declarado na propriedade alg no cabeçalho do JWT criptografado for diferente do algoritmo de criptografia de chaves especificado aqui no elemento <Key>;
  • a política especificar um elemento <Content>, e o algoritmo declarado na propriedade enc no cabeçalho do JWT criptografado for diferente do especificado no elemento <Content>.

Por exemplo, para verificar um JWT criptografado e conferir se o algoritmo da chave é RSA-OAEP-256 e se o algoritmo de conteúdo é A128GCM:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>

Por outro lado, para verificar um JWT criptografado e se o algoritmo de chave for RSA-OAEP-256, em vez de aplicar uma restrição ao algoritmo de conteúdo:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
  </Algorithms>

Algoritmos de criptografia de chaves

A tabela a seguir lista os algoritmos disponíveis para criptografia de chaves, bem como o tipo de chave que você precisa especificar para verificar um JWT usando esse algoritmo de criptografia de chaves.

Valor de <Key> (algoritmo de criptografia de chaves) Elemento importante para verificação
dir <DirectKey>
RSA-OAEP-256 <PrivateKey>
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 <SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 <PasswordKey>
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 <PrivateKey>

Consulte Verificar um JWT criptografado para um exemplo de que o algoritmo de criptografia de chaves é RSA-OAEP-256, portanto, use o elemento <PrivateKey>.

Algoritmos de criptografia de conteúdo

A política VerifyJWT não exige que você especifique um algoritmo para criptografia do conteúdo. Se você quiser especificar o algoritmo usado para criptografia do conteúdo, use o filho <Content> do elemento <Algorithms>.

Seja qual for o algoritmo de criptografia de chaves, a criptografia de conteúdo oferece suporte aos seguintes algoritmos, todos simétricos e baseados em AES:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

<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 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, 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.

Por 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.

Uma das razões 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 falso
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 falso
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 falso
Presença Opcional
Tipo Booleano
Valores válidos verdadeiro ou falso

<Issuer>

<VerifyJWT name='VJWT-29'>
  ...
  <!-- verify that the iss claim matches a hard-coded value -->
  <Issuer>issuer-string-here</Issuer>

  or:

  <!-- verify that the iss claim matches the value contained in a variable -->
  <Issuer ref='variable-containing-issuer'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Issuer ref='variable-containing-issuer'>fallback-value-here</Issuer>

A política verifica se o emissor no JWT (a declaração iss) corresponde à string especificada no elemento de configuração. A declaração iss é uma das declarações registradas mencionadas na IETF RFC 7519 (link em inglês).

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

<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. Por 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.

<MaxLifespan>

  <VerifyJWT name='VJWT-62'>
  ...
  <!-- hard-coded lifespan of 5 minutes -->
  <MaxLifespan>5m</MaxLifespan>

  or:

  <!-- refer to a variable -->
  <MaxLifespan ref='variable-here'/>

  or:

  <!-- attribute telling the policy to use iat rather than nbf -->
  <MaxLifespan useIssueTime='true'>1h</MaxLifespan>

  or:

  <!-- useIssueTime and ref, and hard-coded fallback value. -->
  <MaxLifespan useIssueTime='true' ref='variable-here'>1h</MaxLifespan>
  ...

Configura a política VerifyJWT para verificar se a vida útil de um token não excede um limite especificado. É possível especificar o limite usando um número seguido por um caractere, denotando o número de segundos, minutos, horas, dias ou semanas. Os seguintes caracteres são válidos:

  • s: segundos
  • m: minutos
  • h: horas
  • d: dias
  • w: semanas

Por exemplo, é possível especificar um dos seguintes valores: 120s, 10m, 1h, 7d, 3w.

A política calcula a vida útil real do token subtraindo o valor não anterior de (nbf) do valor de expiração (exp). Se exp ou nbf estiverem ausentes, a política gerará uma falha. Se a duração do token exceder o período especificado, a política emitirá uma falha.

É possível definir o atributo opcional useIssueTime como true para usar o valor iat em vez do valor nbf ao calcular a vida útil do token.

O uso do elemento MaxLifespan é opcional. É possível usar esse elemento apenas uma vez.

<PrivateKey>

Use esse elemento para especificar a chave privada que pode ser usada para verificar um JWT criptografado com um algoritmo assimétrico. Veja a seguir uma descrição dos possíveis elementos filhos.

<Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Um filho do elemento <PrivateKey>. Especifique a senha que a política precisa usar para descriptografar a chave privada, se necessário, ao verificar um JWT criptografado. Use o atributo ref para transmitir a senha em uma variável de fluxo.

Padrão N/A
Presença Opcional
Tipo String
Valores válidos Uma variável de referência de fluxo.

Observação: é necessário especificar uma variável de fluxo. A Apigee rejeitará uma configuração de política inválida em que a senha é especificada em texto simples. A variável de fluxo precisa ter o prefixo "particular". Por exemplo, private.mypassword

<Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Filho do elemento <PrivateKey>. Especifica uma chave privada codificada por PEM que a política usará para verificar um JWT criptografado. Use o atributo ref para transmitir a chave em uma variável de fluxo.

Padrão N/A
Presença Necessário para verificar um JWT que foi criptografado usando um algoritmo de criptografia de chave assimétrica.
Tipo String
Valores válidos Uma variável de fluxo que contém uma string que representa um valor de chave privada RSA codificado em PEM.

Observação: a variável do fluxo precisa ter o prefixo "private". Por exemplo, private.mykey

<PublicKey>

Especifica a origem da chave pública usada para verificar um JWT assinado com um algoritmo assimétrico. Os algoritmos compatíveis incluem RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512. Veja a seguir uma descrição dos possíveis elementos filhos.

<Certificate>

<PublicKey>
  <Certificate ref="signed_public.cert"/>
</PublicKey>

-or-

<PublicKey>
  <Certificate>
-----BEGIN CERTIFICATE-----
certificate data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

Um filho do elemento <PublicKey>. Especifica o certificado assinado usado como a origem da chave pública. Use o atributo ref para transmitir o certificado assinado em uma variável de fluxo ou especifique o certificado codificado por PEM diretamente. Alinhe os dados do certificado à esquerda, conforme mostrado no exemplo de referência.

Padrão N/A
Presença Opcional. Para verificar um JWT assinado com um algoritmo assimétrico, é preciso usar o elemento <Certificate>, <JWKS> ou <Value> para fornecer a chave pública.
Tipo String
Valores válidos Uma variável de fluxo ou string.

<JWKS>

  <PublicKey>
    <JWKS …  > … </JWKS>
  </PublicKey>

Um filho do elemento <PublicKey>. Especifica um JWKS como origem de chaves públicas. Ele será uma lista de chaves que seguem o formato descrito em IETF RFC 7517 - JSON Web Key (JWK).

Se o JWT de entrada receber um ID de chave presente no JWKS, a política usará a chave pública correta para verificar a assinatura do 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, a Apigee armazenará em cache o JWKS por um período de 300 segundos. Quando o cache expira, a Apigee busca o JWKS novamente.

Padrão N/A
Presença Opcional. Para verificar um JWT assinado com um algoritmo assimétrico, é preciso usar o elemento <Certificate>, <JWKS> ou <Value> para fornecer a chave pública.
Tipo String
Valores válidos

É possível especificar o JWKS de quatro maneiras:

  • literalmente, como um valor de texto:

      <PublicKey>
    <JWKS>{
      "keys": [
        {"kty":"RSA","e":"AQAB","kid":"b3918c88","n":"jxdm..."},
        {"kty":"RSA","e":"AQAB","kid":"24f094d4","n":"kWRdbgMQ..."}
      ]
    }
    </JWKS>
  </PublicKey>

  • indiretamente, com o atributo ref, especificando uma variável de fluxo:

      <PublicKey>
    <JWKS ref="variable-containing-jwks-content"/>
  </PublicKey>

    A variável referenciada precisa conter uma string que representa um JWKS.

  • indiretamente, usando um URI estático, com o atributo uri:

      <PublicKey>
    <JWKS uri="uri-that-returns-a-jwks"/>
  </PublicKey>

  • indiretamente, usando um URI determinado dinamicamente, com o atributo uriRef:

      <PublicKey>
    <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/>
  </PublicKey>

<Value>

<PublicKey>
  <Value ref="public.publickeyorcert"/>
</PublicKey>

-or-

<PublicKey>
  <Value>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN
ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
DQIDAQAB
-----END PUBLIC KEY-----
  </Value>
</PublicKey>

Um filho do elemento <PublicKey>. Especifica a chave pública a ser usada para verificar a assinatura em um JWT assinado. Use o atributo ref para transmitir a chave em uma variável de fluxo ou especifique a chave codificada por PEM diretamente. Alinhe a chave pública à esquerda, conforme mostrado no exemplo de referência.

Padrão N/A
Presença Opcional. Para verificar um JWT assinado com um algoritmo assimétrico, é preciso usar o elemento <Certificate>, <JWKS> ou <Value> para fornecer a chave pública.
Tipo String
Valores válidos Uma variável de fluxo ou string.

<RequiredClaims>

<VerifyJWT name='VJWT-1'>
  ...
  <!-- Directly specify the names of the claims to require -->
  <RequiredClaims>sub,iss,exp</RequiredClaims>

  -or-

  <!-- Specify the claim names indirectly, via a context variable -->
  <RequiredClaims ref='claims_to_require'/>
  ...
</VerifyJWT>

O elemento <RequiredClaims> é opcional. Ele especifica uma lista separada por vírgulas de nomes de declarações que precisam estar presentes no payload do JWT ao verificar um JWT. O elemento garante que o JWT apresentado contenha as declarações necessárias, mas não valide o conteúdo delas. Se alguma das declarações listadas não estiver presente, a política VerifyJWT gerará uma falha durante o tempo de execução.

Padrão N/A
Presença Opcional
Tipo String
Valores válidos Uma lista separada por vírgulas de nomes das declarações.

<SecretKey>

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

O elemento SecretKey é opcional. Especifica a chave do secret que será usada ao verificar um JWT assinado que usa um algoritmo simétrico (HS*) ou ao verificar um JWT criptografado que usa um algoritmo simétrico (AES) para criptografia de chaves.

Filhos de <SecretKey>

A tabela a seguir fornece uma descrição dos elementos e atributos filhos de <SecretKey>:

Filho(a) Presença Descrição
encoding (atributo) Opcional

Especifica como a chave é codificada na variável referenciada. Por padrão, quando nenhum atributo encoding está presente, a codificação da chave é tratada como UTF-8. Os valores válidos para o atributo são: hex, base16, base64 ou base64url. Os valores de codificação hex e base16 são sinônimos.

<SecretKey encoding="hex" >
  <Value ref="private.secretkey"/>
</SecretKey>

No exemplo acima, como a codificação é hex, se o conteúdo da variável private.secretkey for 494c6f766541504973, a chave será decodificada como um conjunto de 9 bytes, que no hex será 49 4c 6f 76 65 41 50 49 73.

Valor (elemento) Obrigatório

Uma chave do secret codificada. Especifica a chave de secret que será usada para verificar o payload. Use o atributo ref para fornecer a chave indiretamente usando uma variável, como private.secret-key.

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

A Apigee aplica uma força mínima fundamental aos algoritmos HS256/HS384/HS512. O comprimento mínimo de chave para HS256 é 32 bytes, para HS384 é 48 bytes e para HS512 é 64 bytes. O uso de uma chave de força mais baixa causa um erro de tempo de execução.

<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.

Com esse elemento, é possível configurar a política para recuperar o JWT de uma variável de parâmetro de consulta ou formulário ou qualquer outra variável. Quando esse elemento estiver presente, a política não vai remover nenhum prefixo Bearer. Se a variável não existir ou se a política não encontrar um JWT na variável especificada, a política retornará um erro.

Por padrão, quando nenhum elemento <Source> estiver presente, a política vai recuperar o JWT lendo a variável request.header.authorization e removendo o prefixo Bearer. Se você transmitir o JWT no cabeçalho de autorização como um token do portador (com o prefixo Bearer), não especifique o elemento <Source> na configuração da política. Por exemplo, você não usaria o elemento <Source> na configuração da política se transmitir o JWT no cabeçalho de autorização da seguinte maneira:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
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 de fluxo da Apigee.

<Subject>

<VerifyJWT name='VJWT-8'>
  ...
  <!-- verify that the sub claim matches a hard-coded value -->
  <Subject>subject-string-here</Subject>

  or:

  <!-- verify that the sub claim matches the value contained in a variable -->
  <Subject ref='variable-containing-subject'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Subject ref='variable-containing-subject'>fallback-value-here</Subject>

A política verifica se o assunto no JWT (a declaração sub) corresponde à string especificada na configuração da política. A declaração sub é uma das declarações registradas descritas em RFC7519.

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

<TimeAllowance>

<VerifyJWT name='VJWT-23'>
  ...
  <!-- configure a hard-coded time allowance of 20 seconds -->
  <TimeAllowance>20s</TimeAllowance>

  or:

  <!-- refer to a variable containing the time allowance -->
  <TimeAllowance ref='variable-containing-time-allowance'/>

  or:

  <!-- refer to a variable; fallback to a hard-coded value if the variable is empty -->
  <TimeAllowance ref='variable-containing-allowance'>30s</TimeAllowance>

O "período de carência" para horários, a fim de considerar a distorção do relógio entre o emissor e o verificador de um JWT. Isso se aplica tanto para a expiração (a declaração exp) quanto para a que não é antes do prazo (a declaração nbf). Por exemplo, se a permissão de tempo for configurada como 30s, um JWT expirado será tratado como válido por 30 segundos após a expiração declarada. O intervalo de antes do horário será avaliado de forma semelhante.

Padrão 0 segundos (sem período de carência)
Presença Opcional
Tipo String
Valores válidos Uma expressão de período ou uma referência a uma variável de fluxo que contenha uma expressão. Os períodos podem ser especificados por um número inteiro positivo seguido por um caractere que indica uma unidade de tempo, da seguinte maneira:
  • s = segundos
  • m = minutos
  • h = horas
  • d = dias

<Type>

<Type>type-string-here</Type>

Descreve se a política verifica um JWT assinado ou um JWT criptografado. O elemento <Type> é opcional. É possível usá-la para informar os leitores da configuração se a política gera um JWT assinado ou criptografado.

  • Se o elemento <Type> estiver presente:
    • Se o valor de <Type> for Signed, a política verificará um JWT assinado, e o elemento <Algorithm> precisará estar presente.
    • Se o valor de <Type> for Encrypted, a política verificará um JWT criptografado, e o elemento <Algorithms> precisará estar presente.
  • Se o elemento <Type> estiver ausente:
    • Se o elemento <Algorithm> estiver presente, a política presumirá que <Type> é Signed.
    • Se o elemento <Algorithms> estiver presente, a política presumirá que <Type> é Encrypted.
  • Se <Algorithm> e <Algorithms> não estiverem presentes, a configuração será inválida.
Padrão N/A
Presença Opcional
Tipo String
Valores válidos Signed ou Encrypted

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.FailedToDecode 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed 401 The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration 401 Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidIterationCount 401 The iteration count that was used in the encrypted JWT is not equal to the iteration count specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 Invalid JSON found in the header or payload.
steps.jwt.InvalidKeyConfiguration 401 JWKS in the <PublicKey> element is invalid. The reason could be that the JWKS URI endpoint is not reachable from the Apigee instance. Test connectivity to the endpoint by creating a passthrough proxy and using the JWKS endpoint as a target.
steps.jwt.InvalidSaltLength 401 The salt length that was used in the encrypted JWT is not equal to the salt length specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidToken 401 This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch 401 The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch 401 The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch 401 The subject claim failed on token verification.
steps.jwt.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader 401 Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired 401 The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid 401 The token is not yet valid.
steps.jwt.UnhandledCriticalHeader 401 A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException 401 An unknown exception occurred.
steps.jwt.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidNameForAdditionalClaim The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
InvalidEmptyElement This error occurs if the <Source> element of the Verify JWT policy is empty. If present, it must be defined with an Apigee flow variable name.
InvalidPublicKeyValue If the value used in the child element <JWKS> of the <PublicKey> element does not use a valid format as specified in RFC 7517, the deployment will fail.
InvalidConfigurationForActionAndAlgorithm If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.

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 "InvalidToken"
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 "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>