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

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.
Presença	Opcional
Tipo	String
Valores válidos	Um nome de variável de fluxo da Apigee

Variáveis de fluxo

Após o êxito, as políticas Verify JWS e Decode JWS definem as variáveis de contexto de acordo com este padrão:

jws.{policy_name}.{variable_name}

Por exemplo, se o nome da política for verify-jws, a política armazena o algoritmo especificado no JWS nesta variável de contexto: jws.verify-jws.header.algorithm

Nome da variável	Descriçã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.
header.algorithm	O algoritmo de assinatura usado no JWS. 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 JWS foi gerado. Consulte também "Usar um conjunto de chaves Web JSON (JWKS)" na vista geral das políticas de JWT e JWS para validar um JWS. Consulte o parâmetro do cabeçalho(ID da chave) para mais informações.
header.type	O valor do tipo de cabeçalho. Para mais informações, consulte o artigo Parâmetro de cabeçalho(tipo).
header.name	O valor do cabeçalho com nome (padrão ou adicional). Um destes é definido para cada cabeçalho adicional na parte do cabeçalho do JWS.
header-json	O cabeçalho no formato JSON.
payload	O payload JWS, se o JWS tiver um payload anexado. Para uma carga útil separada, esta variável está vazia.
valid	No caso de VerifyJWS, 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 DecodeJWS, esta variável não está definida.

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

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 "TokenExpired"
JWS.failed	Todas as políticas JWS definem a mesma variável em caso de falha.	jws.JWS-Policy.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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>