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
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 |
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 |
falso | Opcional |
ativado |
Defina como true para aplicar a política.
Defina como |
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.
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. | build |
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. |
build |
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.
|
build |
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>