Política VerifyJWT

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política VerifyJWT valida um JWT assinado ou desencripta e valida um JWT encriptado recebido de clientes ou outros sistemas. Esta política também extrai as reivindicações para variáveis de contexto, para que as políticas ou as condições subsequentes possam examinar esses valores para tomar decisões de autorização ou encaminhamento. Consulte a vista geral das políticas de JWS e JWT para ver uma introdução detalhada.

Quando esta política é executada, no caso de um JWT assinado, o Apigee valida a assinatura do JWT através da chave de validação fornecida. No caso de um JWT encriptado, o Apigee desencripta o JWT através da chave de desencriptação. Em qualquer dos casos, o Apigee verifica posteriormente se o JWT é válido de acordo com as horas de validade e de início, se estiverem presentes. Opcionalmente, a política também pode validar os valores de reivindicações específicas no JWT, como o assunto, o emissor, o público-alvo ou o valor de reivindicações adicionais.

Se o JWT for validado e for válido, todas as reivindicações contidas no JWT são extraídas para variáveis de contexto para utilização por políticas ou condições subsequentes, e o pedido pode prosseguir. Se não for possível validar a assinatura JWT ou se o JWT for inválido devido a um dos registos de data/hora, todo o processamento é interrompido e é devolvido um erro na resposta.

Se a política valida um JWT assinado ou encriptado, depende do elemento que usa para especificar o algoritmo que valida o JWT:

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

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

Valide um JWT assinado

Esta secção explica como validar um JWT assinado. Para um JWT assinado, use o elemento <Algorithm> para especificar o algoritmo de assinatura da chave.

Exemplos de um JWT assinado

Os exemplos seguintes ilustram como validar um JWT assinado.

Algoritmo HS256

Esta política de exemplo valida um JWT que foi assinado com o algoritmo de encriptação HS256, HMAC usando uma soma de verificação SHA-256. O JWT é transmitido no pedido de proxy através de um parâmetro de formulário denominado jwt. A chave está contida numa variável denominada private.secretkey. Consulte o vídeo acima para ver um exemplo completo, incluindo como fazer um pedido à política.

A configuração da política inclui as informações de que o Apigee precisa para descodificar e avaliar o JWT, como onde encontrar o JWT (numa variável de fluxo especificada no elemento Source), o algoritmo de assinatura necessário, onde encontrar a chave secreta (armazenada numa variável de fluxo do Apigee, que pode ter sido obtida no KVM do Apigee, por exemplo) e um conjunto de reivindicações necessárias e os respetivos 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 escreve o respetivo resultado em variáveis de contexto para que as políticas ou as condições subsequentes no proxy de API possam examinar esses valores. Consulte o artigo Variáveis de fluxo para ver uma lista das variáveis definidas por esta política.

Algoritmo RS256

Esta política de exemplo valida um JWT que foi assinado com o algoritmo RS256. Para validar, tem de fornecer a chave pública. O JWT é transmitido no pedido de proxy através de um parâmetro de formulário denominado jwt. A chave pública está contida numa variável denominada public.publickey. Consulte o vídeo acima para ver um exemplo completo, incluindo como fazer um pedido à política.

Consulte a Referência de elementos para ver detalhes sobre os requisitos e as opções de cada elemento nesta política de exemplo.

<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 esta carga útil…

{
  "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."
}

… vai ser considerada válida se a assinatura puder ser validada 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."
}

… vai ser considerada inválida, mesmo que seja possível validar a assinatura, porque a reivindicação "sub" incluída no JWT não corresponde ao valor necessário do elemento "Subject" conforme especificado na configuração da política.

A política escreve o respetivo resultado em variáveis de contexto para que as políticas ou as condições subsequentes no proxy de API possam examinar esses valores. Consulte o artigo Variáveis de fluxo para ver uma lista das variáveis definidas por esta política.

Os exemplos acima usam o elemento <Algorithm>, pelo que validam um JWT assinado. O elemento <PrivateKey> especifica a chave usada para assinar o JWT. Também existem outros elementos importantes. A que usa depende do algoritmo especificado pelo valor de <Algorithm>, conforme descrito na secção seguinte.

Definir os elementos principais para validar um JWT assinado

Os seguintes elementos especificam a chave usada para validar um JWT assinado:

O elemento que usa depende do algoritmo escolhido, conforme apresentado na tabela seguinte:

Algoritmo Elementos principais
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 chaves, consulte o artigo Acerca dos algoritmos de encriptação de assinaturas.

Valide um JWT encriptado

Esta secção explica como validar um JWT encriptado. Para um JWT encriptado, use o elemento <Algorithms> para especificar os algoritmos de assinatura da chave e do conteúdo.

Exemplo de um JWT encriptado

O exemplo seguinte mostra como validar um JWT encriptado (com <Type> definido como Encrypted), em que:

  • A chave está encriptada com o algoritmo RSA-OAEP-256.
  • O conteúdo está encriptado 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>

O exemplo acima usa o elemento <Algorithms>, pelo que valida um JWT encriptado. O elemento <PrivateKey> especifica a chave que vai ser usada para desencriptar o JWT. Também existem outros elementos importantes. A que usa depende do algoritmo especificado pelo valor de <Algorithms>, conforme descrito na secção seguinte.

Definir os elementos principais para validar um JWT encriptado

Os seguintes elementos especificam a chave usada para validar um JWT encriptado:

O elemento que usa depende do algoritmo de encriptação de chaves escolhido, conforme mostrado na tabela seguinte:

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

Nota: a variável que especificar tem de ser resolvida para uma chave privada RSA no formato codificado em PEM.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

Nota: a variável que especificar tem de ser resolvida para uma chave privada de curva elíptica no formato com codificação 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 principais requisitos, consulte o artigo Acerca dos algoritmos de encriptação de assinatura.

Referência do elemento

A referência da política descreve os elementos e os atributos da política Verify JWT.

Nota: a configuração varia ligeiramente consoante o algoritmo de encriptação que usar. Consulte as amostras para ver exemplos que demonstram configurações para exemplos de utilização 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 principais da política.

Atributo Descrição Predefinição Presença
nome O nome interno da política. Os carateres que pode usar no nome estão restritos a: A-Z0-9._\-$ %. No entanto, a IU do Apigee aplica restrições adicionais, como a remoção automática de carateres que não sejam alfanuméricos.

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

 N/A Obrigatória
continueOnError Defina como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas.

Definido como true para que a execução do fluxo continue mesmo depois de 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 é aplicada, mesmo que permaneça anexada a um fluxo.

 verdadeiro Opcional
assíncrono Este atributo foi descontinuado. falso Descontinuado

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

Predefinição Se omitir este elemento, é usado o valor do atributo name da política.
Presença Opcional
Tipo String

<Algorithm>

<Algorithm>HS256</Algorithm>

Especifica o algoritmo criptográfico usado para validar o token. Use o elemento <Algorithm> para validar um JWT assinado.

Os algoritmos RS*/PS*/ES* usam um par de chaves pública/secreta, enquanto os algoritmos HS* usam um segredo partilhado. Consulte também Acerca dos algoritmos de encriptação de assinaturas.

Pode especificar vários valores separados por vírgulas. Por exemplo, "HS256, HS512" ou "RS256, PS256". No entanto, não pode combinar algoritmos HS* com outros nem algoritmos ES* com outros, porque requerem um tipo de chave específico. Pode combinar algoritmos RS* e PS*.

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

<Algorithms>

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

Use o elemento <Algorithms> para validar um JWT encriptado. Este elemento especifica o algoritmo criptográfico para a encriptação de chaves que tem de ter sido usado quando o JWT encriptado foi criado. Também especifica opcionalmente o algoritmo para a encriptação de conteúdo.

Predefinição N/A
Presença Obrigatório quando valida um JWT encriptado
Tipo Complexo

Elementos secundários de <Algorithms>

A tabela seguinte apresenta uma descrição geral dos elementos subordinados de <Algorithms>:

Elemento secundário Obrigatório? Descrição
<Key> Obrigatória Especifica o algoritmo de encriptação da chave.
<Content> Opcional Especifica o algoritmo de encriptação do conteúdo.

A validação falha se:

  • O algoritmo declarado na propriedade alg no cabeçalho do JWT encriptado é diferente do algoritmo de encriptação de chaves especificado aqui no elemento <Key>.
  • A política especifica um elemento <Content> e o algoritmo afirmado na propriedade enc no cabeçalho do JWT encriptado é diferente do especificado no elemento <Content>.

Por exemplo, para validar um JWT encriptado e verificar 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 validar um JWT encriptado e verificar se o algoritmo de chave é RSA-OAEP-256 e não aplicar uma restrição ao algoritmo de conteúdo:

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

Algoritmos de encriptação de chaves

A tabela seguinte apresenta os algoritmos disponíveis para a encriptação de chaves, bem como o tipo de chave que tem de especificar para validar um JWT através desse algoritmo de encriptação de chaves.

Valor de <Key> (algoritmo de encriptação de chaves) Elemento essencial necessário para a validaçã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 o artigo Validar um JWT encriptado para ver um exemplo em que o algoritmo de encriptação de chaves é RSA-OAEP-256, pelo que usa o elemento <PrivateKey>.

Algoritmos de encriptação de conteúdo

A política VerifyJWT não requer que especifique um algoritmo para a encriptação de conteúdo. Se quiser especificar o algoritmo usado para a encriptação de conteúdo, faça-o com o elemento filho<Content> do elemento <Algorithms>.

Independentemente do algoritmo de encriptação de chaves, os seguintes algoritmos, todos simétricos e baseados em AES, são suportados para a encriptação de conteúdo:

  • 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 reivindicação de público no JWT corresponde ao valor especificado na configuração. Se não houver correspondência, a política gera um erro. Esta reivindicação identifica os destinatários a quem o JWT se destina. Esta é uma das reivindicações registadas mencionadas na RFC7519.

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

<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 a carga útil do JWT contém as reivindicações adicionais especificadas e se os valores das reivindicações afirmadas correspondem.

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

Predefiniçã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. Predefinição: false
Valores válidos Qualquer valor que queira usar para uma reivindicação adicional.

O elemento <Claim> aceita os seguintes atributos:

  • name: (obrigatório) o nome da reivindicação.
  • ref: (opcional) o nome de uma variável de fluxo. Se estiver presente, a política usa o valor desta variável como a reivindicação. Se forem especificados um atributo ref e um valor de reivindicação explícito, o valor explícito é o predefinido e é usado se a variável de fluxo referenciada não for resolvida.
  • type: (opcional) um dos seguintes: string (predefinição), number, boolean ou map
  • array: (opcional) defina como verdadeiro para indicar se o valor é uma matriz de tipos. Predefinição: false.

Quando inclui o elemento <Claim>, os nomes das reivindicações são definidos estaticamente quando configura a política. Em alternativa, pode transmitir um objeto JSON para especificar os nomes das reivindicações. Uma vez que o objeto JSON é transmitido como uma variável, os nomes das reivindicações são determinados no momento da execução.

Por exemplo:

<AdditionalClaims ref='json_claims'/>

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

{
  "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 de reivindicação adicionais especificados e se os valores de reivindicação afirmados correspondem.

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

Predefinição N/A
Presença Opcional
Tipo

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

O tipo é predefinido como String se não for especificado nenhum tipo.
Array Defina como true para indicar se o valor é uma matriz de tipos. Predefinição: false
Valores válidos Qualquer valor que queira usar para uma reivindicação adicional.

O elemento <Claim> aceita os seguintes atributos:

  • name: (obrigatório) o nome da reivindicação.
  • ref: (opcional) o nome de uma variável de fluxo. Se estiver presente, a política usa o valor desta variável como a reivindicação. Se forem especificados um atributo ref e um valor de reivindicação explícito, o valor explícito é o predefinido e é usado se a variável de fluxo referenciada não for resolvida.
  • type: (opcional) um dos seguintes: string (predefinição), number, boolean ou map
  • array: (opcional) defina como verdadeiro para indicar se o valor é uma matriz de tipos. Predefinição: false.

<CustomClaims>

Nota: atualmente, é inserido um elemento CustomClaims quando adiciona uma nova política GenerateJWT através da IU. Este elemento não é funcional e é ignorado. O elemento correto a usar é <AdditionalClaims>. A IU vai ser atualizada para inserir os elementos corretos mais tarde.

<Id>

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

Verifica se o JWT tem a reivindicação jti específica. Quando o valor de texto e o atributo ref estão ambos vazios, a política gera um jti que contém um UUID aleatório. A reivindicação de ID do JWT (jti) é um identificador exclusivo do JWT. Para mais informações sobre jti, consulte o RFC7519.

Predefiniçã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 falso se quiser que a política apresente um erro quando qualquer cabeçalho listado no cabeçalho crit do JWT não estiver listado no elemento <KnownHeaders>. Defina como verdadeiro para fazer com que a política VerifyJWT ignore o cabeçalho crit.

Um dos motivos para definir este elemento como verdadeiro é se estiver num ambiente de teste e ainda não estiver preparado para processar uma falha num cabeçalho em falta.

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Defina como falso (predefinição) se quiser que a política apresente um erro quando um JWT contém uma reivindicação iat (Emitido em) que especifica uma hora no futuro. Defina como verdadeiro para fazer com que a política ignore o iat durante a validação.

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Defina como falso se quiser que a política apresente um erro quando qualquer variável referenciada especificada na política não for resolvível. Defina como true para tratar qualquer variável não resolúvel como uma string vazia (nula).

Predefiniçã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 reivindicação iss) corresponde à string especificada no elemento de configuração. A reivindicação iss é uma das reivindicações registadas mencionadas na RFC 7519 da IETF.

Predefiniçã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 num 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, verifica se o elemento <KnownHeaders> também lista esse cabeçalho. O elemento <KnownHeaders> pode conter um superconjunto dos itens listados em crit. Só é necessário que todos os cabeçalhos indicados em crit estejam indicados no elemento <KnownHeaders>. Qualquer cabeçalho que a política encontre em crit que também não esteja listado em <KnownHeaders> faz com que a política VerifyJWT falhe.

Opcionalmente, pode configurar a política VerifyJWT para ignorar o cabeçalho crit definindo o elemento <IgnoreCriticalHeaders> como true.

Predefiniçã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 duração de um token não excede um limite especificado. Pode especificar o limite usando um número seguido de um caráter, que indica o número de segundos, minutos, horas, dias ou semanas. Os seguintes carateres são válidos:

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

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

A política calcula a duração real do token subtraindo o valor not-before (nbf) do valor de validade (exp). Se exp ou nbf estiver em falta, a política gera uma falha. Se a duração do token exceder o período especificado, a política gera uma falha.

Pode definir o atributo opcional useIssueTime como true para usar o valor iat em vez do valor nbf ao calcular a duração do token.

A utilização do elemento MaxLifespan é opcional. Se usar este elemento, só o pode usar uma vez.

<PrivateKey>

Use este elemento para especificar a chave privada que pode ser usada para validar um JWT encriptado com um algoritmo assimétrico. Segue-se uma descrição dos possíveis elementos secundários.

<Password>

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

Um elemento secundário do elemento <PrivateKey>. Especifica a palavra-passe que a política deve usar para desencriptar a chave privada, se necessário, ao validar um JWT encriptado. Use o atributo ref para transmitir a palavra-passe numa variável de fluxo.

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

Nota: tem de especificar uma variável de fluxo. O Apigee rejeita como inválida uma configuração de política em que a palavra-passe é especificada em texto simples. A variável de fluxo tem de ter o prefixo "private". Por exemplo, private.mypassword

<Value>

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

Elemento subordinado do elemento <PrivateKey>. Especifica uma chave privada codificada em PEM que a política vai usar para validar um JWT encriptado. Use o atributo ref para transmitir a chave numa variável de fluxo.

Predefinição N/A
Presença Necessário para validar um JWT que foi encriptado com um algoritmo de encriptação de chaves assimétricas.
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.

Nota: a variável de fluxo tem de ter o prefixo "private". Por exemplo, private.mykey

<PublicKey>

Especifica a origem da chave pública usada para validar um JWT assinado com um algoritmo assimétrico. Os algoritmos de suporte incluem: RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512. Segue-se uma descrição dos possíveis elementos subordinados.

<Certificate>

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

-or-

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

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

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

<JWKS>

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

Um elemento secundário do elemento <PublicKey>. Especifica um JWKS como uma origem de chaves públicas. Esta será uma lista de chaves seguindo o formato descrito no documento IETF RFC 7517 – Chave Web JSON (JWK).

Se o JWT de entrada tiver um ID da chave presente no JWKS, a política usa a chave pública correta para validar a assinatura do JWT. Para ver detalhes acerca desta funcionalidade, consulte o artigo Usar um conjunto de chaves Web JSON (JWKS) para validar um JWT.

Se obtiver o valor de um URL público, o Apigee armazena em cache o JWKS durante um período de 300 segundos. Quando a cache expira, o Apigee obtém novamente o JWKS.

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

Pode especificar o JWKS de uma das quatro formas seguintes:

  • 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 deve conter uma string que represente um JWKS.

  • Indiretamente através de um URI estático, com o atributo uri:

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

  • Indiretamente através de 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 elemento secundário do elemento <PublicKey>. Especifica a chave pública a usar para validar a assinatura num JWT assinado. Use o atributo ref para transmitir a chave numa variável de fluxo ou especifique a chave codificada em PEM diretamente. Certifique-se de que alinha a chave pública à esquerda, conforme mostrado no exemplo de referência.

Predefinição N/A
Presença Opcional. Para validar um JWT assinado com um algoritmo assimétrico, tem de usar o elemento <Certificate>, o elemento <JWKS> ou o elemento <Value> para fornecer a chave pública.
Tipo String
Valores válidos Uma variável de fluxo ou uma 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. Especifica uma lista de nomes separados por vírgulas de reivindicações que têm de estar presentes na carga útil do JWT quando se valida um JWT. O elemento garante que o JWT apresentado contém as reivindicações necessárias, mas não valida o conteúdo das reivindicações. Se alguma das reivindicações indicadas não estiver presente, a política VerifyJWT gera uma falha em tempo de execução.

Predefinição N/A
Presença Opcional
Tipo String
Valores válidos Uma lista de nomes de reivindicações separados por vírgulas.

<SecretKey>

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

O elemento SecretKey é opcional. Especifica a chave secreta a usar quando validar um JWT assinado que usa um algoritmo simétrico (HS*) ou quando validar um JWT encriptado que usa um algoritmo simétrico (AES) para a encriptação de chaves.

Filhos de <SecretKey>

A tabela seguinte fornece uma descrição dos elementos e atributos secundários de <SecretKey>:

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

Especifica como a chave é codificada na variável referenciada. Por predefinição, quando não está presente o atributo encoding, 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, uma vez que a codificação é hex, se o conteúdo da variável private.secretkey for 494c6f766541504973, a chave é descodificada como um conjunto de 9 bytes, que em hexadecimal é 49 4c 6f 76 65 41 50 49 73.

Valor (elemento) Obrigatória

Uma chave secreta codificada. Especifica a chave secreta que vai ser usada para validar a carga útil. Use o atributo ref para fornecer a chave indiretamente através de uma variável, como private.secret-key .

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

O Apigee aplica uma intensidade mínima da chave para os algoritmos HS256/HS384/HS512. O comprimento mínimo da chave para HS256 é de 32 bytes, para HS384 é de 48 bytes e para HS512 é de 64 bytes. A utilização de uma chave de menor força provoca um erro de tempo de execução.

<Source>

<Source>jwt-variable</Source>

Se presente, especifica a variável de fluxo na qual a política espera encontrar o JWT para validar.

Com este elemento, pode configurar a política para obter o JWT de um formulário ou de uma variável de parâmetro de consulta ou qualquer outra variável. Quando este elemento está presente, a política não remove nenhum prefixo Bearer que possa estar presente. Se a variável não existir ou se a política não encontrar um JWT na variável especificada, a política devolve um erro.

Por predefinição, quando não está presente nenhum elemento <Source>, a política obtém o JWT lendo a variável request.header.authorization e removendo o prefixo Bearer. Se transmitir o JWT no cabeçalho de autorização como um token de portador (com o prefixo Bearer), não especifique o elemento <Source> na configuração da política. Por exemplo, não usaria nenhum elemento <Source> na configuração da política se passasse o JWT no cabeçalho de autorização da seguinte forma:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
Predefinição request.header.authorization (Consulte a nota acima para ver informações importantes acerca da predefinição).
Presença Opcional
Tipo String
Valores válidos Um nome de variável de fluxo do 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 reivindicação sub) corresponde à string especificada na configuração da política. A reivindicação sub é uma das reivindicações registadas descritas na RFC7519.

Predefinição N/A
Presença Opcional
Tipo String
Valores válidos Qualquer valor que identifique 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 tolerância" para horas, para ter em conta a diferença de tempo entre o emissor e o validador de um JWT. Isto aplica-se tanto à data de validade (a reivindicação exp) como ao not-before-time (a reivindicação nbf). Por exemplo, se o tempo permitido estiver configurado para 30s, um JWT expirado é tratado como ainda válido durante 30 segundos após a validade declarada. O not-before-time é avaliado de forma semelhante.

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

<Type>

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

Descreve se a política valida um JWT assinado ou um JWT encriptado. O elemento <Type> é opcional. Pode usá-lo para informar os leitores da configuração se a política gera um JWT assinado ou encriptado.

  • Se o elemento <Type> estiver presente:
    • Se o valor de <Type> for Signed, a política valida um JWT assinado e o elemento <Algorithm> tem de estar presente.
    • Se o valor de <Type> for Encrypted, a política valida um JWT encriptado e o elemento <Algorithms> tem de estar presente.
  • Se o elemento <Type> estiver ausente:
    • Se o elemento <Algorithm> estiver presente, a política assume que <Type> é Signed.
    • Se o elemento <Algorithms> estiver presente, a política assume que <Type> é Encrypted.
  • Se não estiver presente nem <Algorithm> nem <Algorithms>, a configuração é inválida.
Predefinição N/A
Presença Opcional
Tipo String
Valores válidos Signed ou Encrypted

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name Description
claim.audience The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer The JWT issuer claim.
claim.notbefore If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject The JWT subject claim.
claim.name The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type Will be set to JWT.
header.name The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json The header in JSON format.
is_expired true or false
payload-claim-names An array of claims supported by the JWT.
payload-json
The payload in JSON format.
seconds_remaining The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false.

In the case of DecodeJWT, this variable is not set.

Referência de erro

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.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "InvalidToken"
JWT.failed All JWT policies set the same variable in the case of a failure. JWT.failed = true

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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