Política DecodeJWT

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

Veja a documentação do Apigee Edge.

O quê

Descodifica um JWT sem validar a assinatura no JWT. Isto é mais útil quando usado em conjunto com a política VerifyJWT, quando o valor de uma reivindicação do JWT tem de ser conhecido antes de validar a assinatura do JWT.

A política de descodificação de JWT funciona independentemente do algoritmo usado para assinar o JWT. Consulte a vista geral das políticas de JWS e JWT para uma introdução detalhada.

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.

Vídeo

Nota: o vídeo seguinte mostra o editor de proxy clássico na IU do Apigee. A Apigee está a introduzir uma nova versão do Proxy Editor, que tem um design diferente da versão clássica apresentada no vídeo.

Veja um breve vídeo para saber como descodificar um JWT.

Exemplo: descodifique um JWT

A política apresentada abaixo descodifica um JWT encontrado na variável de fluxo var.jwt. Esta variável tem de estar presente e conter um JWT viável (decodificável). A política pode obter 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 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.

Referência de elemento para descodificar JWT

A referência da política descreve os elementos e os atributos da política Decode 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 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 do Apigee com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido 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 associada 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 do Apigee 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

<Source>

<Source>jwt-variable</Source>

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

Nota: por predefinição, o JWT é obtido a partir da variável request.header.authorization. Neste caso, o Apigee procura o JWT no cabeçalho de autorização do pedido. Se transmitir o JWT no cabeçalho de autorização, não precisa de incluir o elemento Source na política. No entanto, tem de incluir Bearer no cabeçalho de autorização. Por exemplo, passaria o JWT no cabeçalho de autorização da seguinte forma:

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

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

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

Variáveis de fluxo

Após o êxito, as políticas Verify JWT e Decode 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 armazena o assunto especificado no JWT na variável de contexto denominada jwt.jwt-parse-token.decoded.claim.sub. (Para retrocompatibilidade, também estará disponível em jwt.jwt-parse-token.claim.subject)

Nome da variável	Descrição
claim.audience	A reivindicação de público do JWT. Este valor pode ser uma string ou uma matriz de strings.
claim.expiry	A data/hora de validade, expressa em milissegundos desde a época.
claim.issuedat	A data em que o token foi emitido, expressa em milissegundos desde epoch.
claim.issuer	A reivindicação do emissor do JWT.
claim.notbefore	Se o JWT incluir uma reivindicação nbf, esta variável vai conter o valor, expresso em milissegundos desde a época.
claim.subject	A reivindicação de assunto do JWT.
claim.name	O valor da reivindicação com nome (padrão ou adicional) na carga útil. Um destes valores vai ser definido para cada reclamação no payload.
decoded.claim.name	O valor analisável em JSON da reivindicação com nome (padrão ou adicional) na carga útil. Uma variável é definida para cada reivindicação na carga útil. Por exemplo, pode usar decoded.claim.iat para obter a hora de emissão do JWT, expressa em segundos desde a época. Embora também possa usar as variáveis de fluxo claim.name, esta é a variável recomendada para usar para aceder a uma reivindicação.
decoded.header.name	O valor analisável em JSON de um cabeçalho no payload. É definida uma variável para cada cabeçalho na carga útil. Embora também possa usar as header.namevariáveis de fluxo, esta é a variável recomendada para usar para aceder a 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, etc. Consulte o parâmetro de cabeçalho(algoritmo) para mais informações.
header.kid	O ID da chave, se tiver sido adicionado quando o JWT foi gerado. Consulte também "Usar um conjunto de chaves Web JSON (JWKS)" na vista geral das políticas JWT para validar um JWT. Consulte o parâmetro do cabeçalho(ID da chave) para mais informações.
header.type	Vai ser definido como JWT.
header.name	O valor do cabeçalho com nome (padrão ou adicional). Um destes 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 reivindicações suportadas pelo JWT.
payload-json	O payload no formato JSON.
seconds_remaining	O número de segundos antes de o token expirar. Se o token tiver expirado, este número é negativo.
time_remaining_formatted	O tempo restante antes de o token expirar, formatado como uma string legível. Exemplo: 00:59:59.926
valid	No caso de VerifyJWT, esta variável é verdadeira quando a assinatura é validada e a hora atual é anterior à data de validade do token e posterior ao valor notBefore do token, se estiverem presentes. Caso contrário, devolve false. No caso de DecodeJWT, esta variável não está definida.

Referência de erro

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. É importante conhecer estas informações se estiver a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha	Estado de HTTP	Causa	Corrigir
steps.jwt.FailedToDecode	401	Ocorre quando a política não consegue descodificar o JWT. O JWT pode ter um formato incorreto, ser inválido ou não ser 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 âmbito ou não pode ser resolvida.

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Nome do erro	Causa	Corrigir
InvalidEmptyElement	Ocorre quando a variável de fluxo que contém o JWT a descodificar não é especificada no elemento <Source> da política.

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo 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 de JWT definem a mesma variável em caso de falha.	JWT.failed = true

Exemplo de resposta de erro

Para o processamento de erros, a prática recomendada é captar a parte errorcode da resposta de erro. Não confie no texto em faultstring, porque 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>