Política chamada de retorno

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

Confira a documentação da Apigee Edge.

O que

Decodifica um JWT sem verificar a assinatura no JWT. Isso é mais útil quando usado em conjunto com a política VerifyJWT, quando o valor de uma declaração dentro do JWT precisa ser conhecido antes de verificar a assinatura do JWT.

A política de decodificação do JWT funciona independentemente do algoritmo usado para assinar o JWT. 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.

Vídeo

Observação: o vídeo a seguir mostra o editor clássico de proxy na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada no vídeo.

Assista a um vídeo curto para saber como decodificar um JWT.

Amostra: decodificar um JWT

A política mostrada abaixo decodifica um JWT encontrado na variável de fluxo var.jwt. Essa variável precisa estar presente e conter um JWT viável (decodificável). A política pode receber o JWT de qualquer variável de fluxo.

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

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.

Referência de elemento para decodificar JWT

A referência de política descreve os elementos e atributos da política "Decodificação de JWT".

Atributos que se aplicam ao elemento de nível superior

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

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

Atributo	Descrição	Padrão	Presença
nome	O nome interno da política. Os caracteres que podem ser usados no nome são restritos a: A-Z0-9._\-$ %. No entanto, a IU da Apigee impõe outras restrições, como a remoção automática de caracteres que não são alfanuméricos. Opcionalmente, use o elemento <displayname></displayname> para rotular a política no editor de proxy da IU da Apigee com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.	falso	Opcional
ativado	Defina como true para aplicar a política. Defina como false para "desativar" a política. A política não será aplicada mesmo se permanecer anexada a um fluxo.	verdadeiro	Opcional
async	Esse atributo está obsoleto.	falso	Descontinuado

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU da Apigee 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

<Source>

<Source>jwt-variable</Source>

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

Observação: por padrão, o JWT é recuperado da variável request.header.authorization. Nesse caso, a Apigee procura o JWT no cabeçalho Autorização da solicitação. Se você transmitir o JWT no cabeçalho de Autorização, não precisará incluir o elemento de origem na política. No entanto, é necessário incluir Portador no cabeçalho de autenticação. Por exemplo, transmita o JWT no cabeçalho de Autorização desta forma:

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

É possível configurar a política para recuperar o JWT de uma variável de parâmetro de formulário ou consulta ou de qualquer outra variável. Se a variável não existir ou se a política não encontrar o JWT, a política retornará um erro.

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

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	Causa	Correção
steps.jwt.FailedToDecode	401	Ocorre quando a política não pode decodificar o JWT. O JWT pode estar incorreto, inválido ou não descodificável.
steps.jwt.FailedToResolveVariable	401	Ocorre quando a variável de fluxo especificada no elemento <Source> da política não existe.
steps.jwt.InvalidToken	401	Ocorre quando a variável de fluxo especificada no elemento <Source> da política está fora do escopo ou não pode ser resolvida.

Erros na implantação

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

Nome do erro	Causa	Correção
InvalidEmptyElement	Ocorre quando a variável do fluxo que contém o JWT a ser decodificada não é especificada no elemento <Source> da 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.

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

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>