Política DecodeJWS

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

Confira a documentação da Apigee Edge.

O que

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.

Vídeo

Observação: o vídeo a seguir mostra o editor clássico de proxy na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada no vídeo.

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	Presence
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 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.	false	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.	true	Opcional
async	Esse atributo está obsoleto.	false	Descontinuado

<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.
Presence	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.

Observação: por padrão, o JWS é recuperado da variável request.header.authorization. Nesse caso, a Apigee procura o JWS no cabeçalho Autorização da solicitação. Se você transmitir o JWS no cabeçalho de Autorização, não precisará incluir o elemento Source na política. No entanto, é necessário incluir Portador no cabeçalho de autenticação. Por exemplo, transmita o JWS no cabeçalho de Autorização desta forma:

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

É possível configurar a política para recuperar o JWS de uma variável de parâmetro de formulário ou consulta ou de qualquer outra variável. Se a variável não existir ou se a política não encontrar o JWS, a política retornará um erro.

Padrão	request.header.authorization. Consulte a observação acima para informações importantes sobre o padrão.
Presence	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

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	Occurs when
steps.jws.FailedToDecode	401	The policy was unable to decode the JWS. The JWS is possibly corrupted.
steps.jws.FailedToResolveVariable	401	Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jws.InvalidClaim	401	For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidJsonFormat	401	Invalid JSON found in the JWS header.
steps.jws.InvalidJws	401	This error occurs when the JWS signature verification fails.
steps.jws.InvalidPayload	401	The JWS payload is invalid.
steps.jws.InvalidSignature	401	<DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.MissingPayload	401	The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader	401	Occurs when the JWS omits the algorithm header.
steps.jws.UnknownException	401	An unknown exception occurred.

Deployment errors

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

Error name	Occurs when
InvalidAlgorithm	The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.
EmptyElementForKeyConfiguration FailedToResolveVariable InvalidConfigurationForActionAndAlgorithmFamily InvalidConfigurationForVerify InvalidEmptyElement InvalidFamiliesForAlgorithm InvalidKeyConfiguration InvalidNameForAdditionalClaim InvalidNameForAdditionalHeader InvalidPublicKeyId InvalidPublicKeyValue InvalidSecretInConfig InvalidTypeForAdditionalClaim InvalidTypeForAdditionalHeader InvalidValueForElement InvalidValueOfArrayAttribute InvalidVariableNameForSecret MissingConfigurationElement MissingElementForKeyConfiguration MissingNameForAdditionalClaim MissingNameForAdditionalHeader	Other possible deployment errors.

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>