Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
O quê
Descodifica o cabeçalho JWS sem validar a assinatura no JWS e escreve cada cabeçalho numa variável de fluxo. Esta política é mais útil quando usada em conjunto com a política VerifyJWS, quando o valor de um cabeçalho do JWS tem de ser conhecido antes de validar a assinatura do JWS.
Um JWS pode ter uma carga útil anexada, como no seguinte formato:
header.payload.signature
Em alternativa, o JWS pode omitir a carga útil, denominada carga útil separada, e estar no seguinte formato:
header..signature
A política DecodeJWS funciona com ambos os formulários porque apenas descodifica a parte do cabeçalho do JWS. A política DecodeJWS também funciona independentemente do algoritmo usado para assinar o JWS.
Consulte o artigo Vista geral das políticas de JWS e JWT para ver uma introdução detalhada e uma vista geral do formato de um JWS.
Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.
Vídeo
Veja um breve vídeo para saber como descodificar um JWT. Embora este vídeo seja específico de um JWT, muitos dos conceitos são os mesmos para JWS.
Exemplo: descodifique um JWS
A política apresentada abaixo descodifica um JWS encontrado na variável de fluxo var.JWS. Esta variável tem de estar presente e conter um JWS viável (decifrável). A política pode obter 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 na parte do cabeçalho do JWS, a política define uma variável de fluxo denominada:
jws.policy-name.header.header-name
Se o JWS tiver um payload anexado, define a variável de fluxo jws.policy-name.header.payload
para o payload. Para um payload separado, payload
está vazio.
Consulte o artigo Variáveis de fluxo para ver uma lista completa das variáveis definidas por esta política.
Elemento de referência para descodificar JWS
A referência da política descreve os elementos e os 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 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 |
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 |
falso | Opcional |
ativada |
Defina como true para aplicar a política.
Defina como |
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 de gestão 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>JWS-variable</Source>
Se estiver presente, especifica a variável de fluxo na qual a política espera encontrar o JWS para descodificar.
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 sucesso, as políticas Verificar JWS e Decodificar JWS definem variáveis de contexto de acordo com esse padrão:
jws.{policy_name}.{variable_name}
Por exemplo, se o nome da política for verify-jws
, ela armazenará
o algoritmo especificado no JWS para esta variável de contexto:
jws.verify-jws.header.algorithm
Nome da variável | Descriçã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. |
header.algorithm |
O algoritmo de assinatura usado no JWS. 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 a JWS foi gerada. Consulte também "Como usar um conjunto de chaves da Web JSON (JWKS)" na Visão geral das políticas JWT e JWS para verificar uma JWS. Consulte Parâmetro de cabeçalho (ID da chave) para mais informações. |
header.type |
O valor do tipo de cabeçalho. Consulte Parâmetro de cabeçalho (tipo) para saber mais. |
header.name |
O valor do cabeçalho nomeado (padrão ou adicional). Um deles será definido para cada cabeçalho adicional na parte principal da JWS. |
header-json |
O cabeçalho no formato JSON. |
payload |
O payload JWS se ele tiver um payload anexado. Para um payload independente, essa variável está vazia. |
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, será falso.
No caso de DecodeJWS, essa variável não é definida. |
Referência de erro
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.
Nome do erro | 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>