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

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 erro

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>