Política chamada de retorno

Política padrão

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

Confira a documentação da Apigee Edge.

A política DecodeJWT decodifica um JWT sem verificar a assinatura nele. 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. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

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.

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

流变量

验证成功后，验证 JWT 和解码 JWT 政策将根据以下模式设置上下文变量：

jwt.{policy_name}.{variable_name}

例如，如果政策名称为 jwt-parse-token，则该政策会将 JWT 中指定的主题存储在名为 jwt.jwt-parse-token.decoded.claim.sub 的上下文变量中。（为实现向后兼容性，jwt.jwt-parse-token.claim.subject 中也提供此主题）

变量名称 说明
claim.audience JWT 目标对象声明。此值可以是字符串，也可以是字符串数组。
claim.expiry 到期日期/时间（自新纪元开始算起，以毫秒为单位）。
claim.issuedat 令牌的签发日期（自新纪元开始算起，以毫秒为单位）。
claim.issuer JWT 签发者声明。
claim.notbefore 如果 JWT 包含 nbf 声明，则此变量将包含该值（自新纪元开始算起，以毫秒为单位）。
claim.subject JWT 主题声明。
claim.name 载荷中已命名声明（标准或附加）的值。为载荷中的每个声明设置其中一个值。
decoded.claim.name 载荷中已命名声明（标准或附加）的 JSON 可解析值。为载荷中的每个声明设置一个变量。例如，您可以使用 decoded.claim.iat 检索 JWT 的颁发时间（自新纪元开始算起，以秒为单位）。虽然您还可以使用 claim.name 流变量，但这也是用来访问声明的推荐变量。
decoded.header.name 载荷中标头的 JSON 可解析值。为载荷中的每个标头设置一个变量。虽然您还可以使用 header.name 流变量，但建议使用此变量来访问标头。
expiry_formatted 到期日期/时间，以人类可读的字符串的形式表示。示例：2017-09-28T21:30:45.000+0000
header.algorithm JWT 中使用的签名算法。例如 RS256、HS384 等。如需了解详情，请参阅（算法）标头参数。
header.kid 密钥 ID（如果生成 JWT 时添加了的话）。另请参阅 JWT 政策概览中的“使用 JSON 网络密钥集 (JWKS)”来验证 JWT。如需了解详情，请参阅（密钥 ID）标头参数。
header.type 将设为 JWT。
header.name 已命名标头的值（标准或附加）。将为 JWT 的标头部分中的每个附加标头设置其中一个值。
header-json JSON 格式的标头。
is_expired true 或 false
payload-claim-names JWT 支持的一组声明。
payload-json
JSON 格式的载荷。
seconds_remaining 令牌过期前的秒数。如果令牌过期，此数字将为负数。
time_remaining_formatted 令牌过期前的剩余时间（以人类可读的字符串的形式表示）。示例：00:59:59.926
valid 对于 VerifyJWT，在验证签名时，此变量为 true，而且当前时间在令牌有效期之前且在令牌 notBefore 值之后（如果两者存在）。否则为 false。

对于 DecodeJWT，无需设置此变量。

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.jwt.FailedToDecode 401 Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
steps.jwt.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jwt.InvalidToken 401 Occurs when the flow variable specified in the <Source> element of the policy is out of scope or can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidEmptyElement Occurs when the flow variable containing the JWT to be decoded is not specified in the <Source> element of the policy.

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

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 "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>