Política VerifyJWT

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

Confira a documentação da Apigee Edge.

Ícone da política

O quê?

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

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Nem todos os usuários têm necessidade de saber sobre os tipos de política e ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

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.

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

Como

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

Vídeo

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

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

 true Opcional
async Esse atributo está obsoleto. falso Obsoleto

<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

<Algorithms>

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

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 Booleanos
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 Booleanos
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 Booleanos
Valores válidos verdadeiro ou falso

<Issuer>

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

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 padrão de declarações mencionados no IETF RFC 7519.

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.

<MaxLifespan>

  <VerifyJWT name='xxx'>
  ...
  <!-- 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-----
cert 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.

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.

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

<Subject>subject-string-here</Subject>
-or-
<Subject ref='variable-containing-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

<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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa 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 Generate não correspondeu ao esperado na política Verify. 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 Uma falta de reivindicação ou incompatibilidade de reivindicação ou falta de cabeçalho ou cabeçalho incompatível.
steps.jwt.InvalidConfiguration 401 Os elementos <Algorithm> e <Algorithms> estão presentes.
steps.jwt.InvalidCurve 401 A curva especificada pela chave não é válida para o algoritmo de curva elíptica.
steps.jwt.InvalidIterationCount 401 A contagem de iterações usada no JWT criptografado não é igual à contagem de iteração especificada na configuração da política "Verificar JWT". Isso se aplica apenas ao JWT que usa <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 JSON inválido encontrado no cabeçalho ou payload.
steps.jwt.InvalidKeyConfiguration 401 JWKS no elemento <PublicKey> é inválido. O motivo pode ser que o endpoint do URI JWKS não pode ser acessado pela instância da Apigee. Teste a conectividade com o endpoint criando um proxy de passagem e usando o endpoint JWKS como destino.
steps.jwt.InvalidSaltLength 401 O comprimento de sal usado no JWT criptografado não é igual ao comprimento de sal especificado na configuração da política "VerifyJWT". Isso se aplica apenas ao JWT que usa <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 A chave especificada não atendeu aos requisitos.
steps.jwt.InvalidPrivateKey 401 A chave especificada não atendeu aos requisitos.
steps.jwt.InvalidPublicKey 401 A chave especificada não atendeu aos requisitos.
steps.jwt.InvalidSecretKey 401 A chave especificada não atendeu aos requisitos.
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 Verify usa um JWKS como fonte 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 as 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 Verify usa um JWKS como fonte para chaves públicas, mas o kid no JWT assinado não está listado no 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 esta política.

Nome do erro Causa Correção
InvalidNameForAdditionalClaim A implantação falhará se a reivindicação usada no elemento filho <Claim> do elemento <AdditionalClaims> é 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 usado 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 Este 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 um valor compatível, a implantação falhará.
MissingConfigurationElement Esse erro ocorrerá se o elemento <PrivateKey> não for usado com algoritmos de 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> estiver 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 definida com um nome de variável de fluxo da Apigee.
InvalidPublicKeyValue Se o valor usado no elemento filho <JWKS> do elemento <PublicKey> não usa um formato válido, conforme especificado no RFC 7517, a implantação falhará.
InvalidConfigurationForActionAndAlgorithm Se o elemento <PrivateKey> é usado com os algoritmos da família HS ou o elemento <SecretKey> é usado com os 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 "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>