Política chamada de retorno

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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.

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 interface de gerenciamento de borda aplica restrições, como a remoção automática de caracteres que não são alfanuméricos.

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

 N/A Obrigatório
continueOnError Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

 falso Opcional
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 Suspenso

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

Padrão Se você omitir esse elemento, o valor do atributo name da política será usado.
Presença Opcional
Tipo String

<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 do fluxo do Edge

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

Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta 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 Corrigir
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 de fluxo que contém o JWT a ser decodificado 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 "TokenExpired"
JWT.failed Todas as políticas do JWT definem a mesma variável em caso de falha. JWT.failed = true

Exemplo de resposta de erro

Códigos de falha de política JWT

Para gerenciar erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto em faultstring, porque ele pode mudar.

Exemplo de regra de falha

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>