Política VerifyJWT

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

Confira a documentação da Apigee Edge.

O que

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

• Se você usar o elemento <Algorithm>, a política verificará um JWT assinado.
• Se você usar o elemento <Algorithms>, a política verificará um JWT criptografado.

Video

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.

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

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

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

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

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

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:

• <SecretKey>
• <PublicKey>

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

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

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

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>

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:

• <PrivateKey>
• <SecretKey>
• <PasswordKey>
• <DirectKey>

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

<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

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

<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>

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

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

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

<Algoritmos>

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

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

Elementos filhos de <Algorithms>

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

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.

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.

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

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.

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.

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

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

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

<Issuer>

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

  or:

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

  or:

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

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

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

<MaxLifespan>

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

  or:

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

  or:

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

  or:

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

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

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

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

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

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

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

<PrivateKey>

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

<Password>

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

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

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

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

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

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

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

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

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

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

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

<Subject>

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

  or:

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

  or:

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

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

<TimeAllowance>

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

  or:

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

  or:

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

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

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

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.

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.

Erros de implantação

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

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.

Exemplo de resposta de erro

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>