Política DecodeJWS

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política DecodeJWS 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 verificar a assinatura do JWS.

Um JWS pode ter uma carga útil anexada, como no formulário:

header.payload.signature

Em alternativa, o JWS pode omitir a carga útil, denominada carga útil desanexada, e estar no seguinte formato:

header..signature

A política DecodeJWS funciona com ambas as formas 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 a 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.

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 <displayname></displayname> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Defina como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar.	falso	Opcional
ativada	Defina como true para aplicar a política. Defina como false para "desativar" a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.	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.

Nota: por predefinição, o JWS é obtido a partir da variável request.header.authorization. Neste caso, o Apigee procura o JWS no cabeçalho de autorização do pedido. Se transmitir o JWS no cabeçalho de autorização, não precisa de incluir o elemento Source na política. No entanto, tem de incluir Bearer no cabeçalho de autorização. Por exemplo, passaria o JWS no cabeçalho de autorização da seguinte forma:

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

Pode configurar a política para obter o JWS a partir de um formulário ou de uma variável de parâmetro de consulta, ou de qualquer outra variável. Se a variável não existir ou se a política não conseguir encontrar o JWS, a política devolve um erro.

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

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 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.
EmptyElementForKeyConfiguration FailedToResolveVariable InvalidConfigurationForActionAndAlgorithmFamily InvalidConfigurationForVerify InvalidEmptyElement InvalidFamiliesForAlgorithm InvalidKeyConfiguration InvalidNameForAdditionalClaim InvalidNameForAdditionalHeader InvalidPublicKeyId InvalidPublicKeyValue InvalidSecretInConfig InvalidTypeForAdditionalClaim InvalidTypeForAdditionalHeader InvalidValueForElement InvalidValueOfArrayAttribute InvalidVariableNameForSecret MissingConfigurationElement MissingElementForKeyConfiguration MissingNameForAdditionalClaim MissingNameForAdditionalHeader	Outros erros de implantação possíveis.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "TokenExpired"
JWS.failed	All JWS policies set the same variable in the case of a failure.	jws.JWS-Policy.failed = true

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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