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

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.

Erro de nome	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.

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>