Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
Conteúdo
Decodifica o cabeçalho JWS sem verificar a assinatura no JWS e grava cada cabeçalho em uma variável de fluxo. Essa política é mais útil quando usada em conjunto com a política VerifyJWS, quando o valor de um cabeçalho do JWS precisa ser conhecido antes de verificar a assinatura do JWS.
Um JWS pode ter um payload anexado, como no formato a seguir:
header.payload.signature
Ou o JWS pode omitir o payload, chamado de payload desanexado, e estar neste formato:
header..signature
A política DecodeJWS funciona com os dois formulários porque só decodifica a parte do cabeçalho referente ao JWS. A política DecodeJWS também funciona independentemente do algoritmo usado para assinar o JWS.
Consulte a visão geral das políticas de JWS e JWT para uma introdução detalhada e uma visão geral do formato de um JWS.
Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.
Video
Assista a um vídeo curto para saber como decodificar um JWT. Embora esse vídeo seja específico para um JWT, muitos dos conceitos são iguais para o JWS.
Amostra: decodificar um JWS
A política mostrada abaixo decodifica um JWS encontrado na variável de fluxo var.JWS. Essa variável precisa estar presente e conter um JWS viável (decodificável). A política pode receber o JWS de qualquer variável de fluxo.
<DecodeJWS name="JWS-Decode-HS256">
<DisplayName>JWS Verify HS256</DisplayName>
<Source>var.JWS</Source>
</DecodeJWS>
Para cada cabeçalho do JWS, a política define uma variável de fluxo chamada:
jws.policy-name.header.header-name
Se o JWS tiver um payload anexado, ele definirá a variável de fluxo jws.policy-name.header.payload
para o payload. Para um payload desanexado, payload fica em branco.
Consulte Variáveis de fluxo para uma lista completa das variáveis definidas por essa política.
Referência de elementos para decodificar JWS
A referência de política descreve os elementos e atributos da política Decode JWS.
Atributos que se aplicam ao elemento de nível superior
<DecodeJWS name="JWS" 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 |
|---|---|---|---|
| name |
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 |
| ativada |
Defina como true para aplicar a política.
Defina como |
true | Opcional |
| async | Esse atributo está obsoleto. | falso | Obsoleto |
<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>JWS-variable</Source>
Se presente, especifica a variável de fluxo em que a política espera encontrar o JWS 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 |
Flow variables
Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:
jws.{policy_name}.{variable_name}
For example, if the policy name is verify-jws, then the policy will store
the algorithm specified in the JWS to this context variable:
jws.verify-jws.header.algorithm
| Variable name | Description |
|---|---|
decoded.header.name |
The JSON-parsable value of a header in the payload. One variable is set for
every header in the payload. While you can also use the header.name flow variables,
this is the recommended variable to use to access a header. |
header.algorithm |
The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more. |
header.kid |
The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more. |
header.type |
The header type value. See (Type) Header Parameter for more. |
header.name |
The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWS. |
header-json |
The header in JSON format. |
payload |
The JWS payload if the JWS has an attached payload. For a detached paylod, this variable is empty. |
valid |
In the case of VerifyJWS, this variable will be true when the signature is verified, and
the current time is before the token expiry, and after the token notBefore value, if they
are present. Otherwise false.
In the case of DecodeJWS, this variable is not set. |
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 falha para lidar com falhas. 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 | Ocorre quando |
|---|---|---|
steps.jws.FailedToDecode |
401 |
A política não conseguiu decodificar o JWS. A JWS está possivelmente corrompida. |
steps.jws.FailedToResolveVariable |
401 |
Ocorre quando a variável de fluxo especificada no elemento <Source> da
política não existe. |
steps.jws.InvalidClaim |
401 |
Uma falta de reivindicação ou incompatibilidade de reivindicação ou falta de cabeçalho ou cabeçalho incompatível. |
steps.jws.InvalidJsonFormat |
401 |
JSON inválido encontrado no cabeçalho JWS. |
steps.jws.InvalidJws |
401 |
Esse erro ocorre quando a verificação de assinatura do JWS falha. |
steps.jws.InvalidPayload |
401 |
O payload do JWS é inválido. |
steps.jws.InvalidSignature |
401 |
<DetachedContent> é omitido e o JWS tem um payload de conteúdo separado. |
steps.jws.MissingPayload |
401 |
O payload do JWS está ausente. |
steps.jws.NoAlgorithmFoundInHeader |
401 |
Ocorre quando a JWS omite o cabeçalho do algoritmo. |
steps.jws.UnknownException |
401 |
Ocorreu uma exceção desconhecida. |
Erros de implantação
Esses erros podem ocorrer quando você implanta um proxy que contém esta política.
| Erro de nome | Ocorre quando |
|---|---|
InvalidAlgorithm |
Os únicos valores válidos são: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512. |
|
|
Outros erros de implantação possíveis. |
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" |
JWS.failed |
Todas as políticas de JWS definem a mesma variável em caso de falha. | jws.JWS-Policy.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="JWS Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "TokenExpired")</Condition>
</Step>
<Condition>JWS.failed=true</Condition>
</FaultRule>
</FaultRules>