Política VerifyJWS

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

Confira a documentação da Apigee Edge.

Ícone da política

O que é

Verifica a assinatura em um JWS recebido de clientes ou outros sistemas. Essa política também extrai cabeçalhos em variáveis de contexto para que políticas ou condições subsequentes possam examinar esses valores para tomar decisões de autorização ou roteamento. Consulte a visão geral das políticas do JWS e do JWT para uma introdução detalhada.

Se o JWS foi verificado e é válido, a solicitação pode continuar. Se a assinatura JWS não puder ser verificada ou se o JWS for inválido devido a algum tipo de erro, todo o processamento será interrompido e um erro será retornado na resposta.

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.

Para saber mais sobre as partes de um JWS e como elas são criptografadas e assinadas, consulte RFC7515.

Video

Assista a um vídeo curto para saber como verificar a assinatura em um JWS. Embora esse vídeo seja específico para verificar um JWT, muitos dos conceitos são iguais para o JWS.

Amostras

Verificar um JWS anexado assinado com o algoritmo HS256

Essa política de exemplo verifica um JWS anexado que foi assinado com o algoritmo de criptografia HS256 HMAC usando uma soma de verificação SHA-256. O JWS é transmitido na solicitação de proxy usando um parâmetro de formulário chamado JWS. A chave está contida em uma variável chamada private.secretkey.

Um JWS anexado contém o cabeçalho, o payload e a assinatura codificados:

header.payload.signature

A configuração da política inclui as informações que a Apigee precisa para decodificar e avaliar o JWS, por exemplo, onde encontrar o JWS (em uma variável de fluxo especificada no elemento <Source>), o algoritmo de assinatura necessário e onde encontrar a chave secreta (armazenada em uma variável de fluxo da Apigee, que pode ter sido recuperada da KVM da Apigee, por exemplo).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

A política grava a saída em variáveis de contexto para que as políticas ou condições subsequentes no proxy de API possam examinar esses valores. Consulte Variáveis de fluxo para ver uma lista das variáveis definidas por essa política.

Verificar um JWS separado assinado com o algoritmo RS256

Esta política de exemplo verifica um JWS separado que foi assinado com o algoritmo RS256. Para verificar, você precisa fornecer a chave pública. O JWS é transmitido na solicitação de proxy usando um parâmetro de formulário chamado JWS. A chave pública está contida em uma variável chamada public.publickey.

Uma JWS separada omite a carga do JWS:

header..signature

Cabe a você transmitir o payload para a política VerifyJWS especificando o nome da variável que contém o payload para o elemento <DetachedContent>. O conteúdo especificado em <DetachedContent> precisa estar no formato não codificado original quando a assinatura do JWS foi criada.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

A política grava a saída em variáveis de contexto para que as políticas ou condições subsequentes no proxy de API possam examinar esses valores. Consulte Variáveis de fluxo para ver uma lista das variáveis definidas por essa política.

Como definir os elementos principais

Os elementos usados para especificar a chave usada para verificar o JWS dependem do algoritmo escolhido, conforme mostrado na tabela a seguir:

Algoritmo elementos-chave
HS* 
<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>
RS*, ES*, PS* 
<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

ou

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>
*Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Referência de elemento

A referência de política descreve os elementos e atributos da política de verificação de JWS.

Observação: a configuração varia um pouco dependendo do algoritmo de criptografia utilizado. Consulte os Amostras para ver exemplos que demonstram configurações para casos de uso específicos.

S

Atributos que se aplicam ao elemento de nível superior

<VerifyJWS 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 da Apigee 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 da Apigee 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

<Algorithm>

<Algorithm>HS256</Algorithm>

Especifica o algoritmo de criptografia para assinar o token. Os algoritmos RS*/PS*/ES* empregam um par de chaves públicas/secretas, enquanto os algoritmos HS* empregam um secret compartilhado. Consulte também Sobre algoritmos de criptografia de assinatura.

É possível especificar vários valores separados por vírgulas. Por exemplo, "HS256, HS512" ou "RS256, PS256". No entanto, não é possível combinar algoritmos HS* e ES* com nenhum outro porque eles exigem um tipo de chave específico. É possível combinar algoritmos RS* e PS*.

Padrão N/A
Presença Obrigatório
Tipo String de valores separados por vírgulas
Valores válidos HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Valida se o cabeçalho JWS contém os pares de nome/valor de declaração adicionais especificados e se os valores declarados correspondem.

Uma declaração adicional usa um nome que não é um dos nomes de declaração padrão do JWS registrados. O valor de uma declaração adicional pode ser uma string, um número, um booleano, um mapa ou uma matriz. Um mapa é simplesmente um conjunto de pares de nome/valor. O valor de uma declaração de qualquer um desses tipos pode ser especificado explicitamente na configuração da política ou indiretamente por meio de uma referência a uma variável de fluxo.

Padrão N/A
Presença Opcional
Tipo

String (padrão), número, booleano ou mapa.

O tipo padrão será String se nenhum tipo for especificado.
Array Defina como true para indicar se o valor é uma matriz de tipos. Padrão: false
Valores válidos Qualquer valor que você queira usar para uma reivindicação adicional.

O elemento <Claim> usa estes atributos:

  • name: obrigatório. O nome da declaração.
  • ref: (opcional) o nome de uma variável de fluxo. Se presente, a política usará o valor dessa variável como a declaração. Se um atributo ref e um valor de declaração explícito forem especificados, o valor explícito será o padrão e será usado se a variável de fluxo referenciada não for resolvida.
  • type: (opcional) uma das seguintes opções: string (padrão), número, booleano ou mapa.
  • array: (opcional) defina como true para indicar se o valor é uma matriz de tipos. Padrão: false

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

Um JWS gerado com um payload de conteúdo está no formato:

header.payload.signature

Se você usar a política GenerateJWS para criar um payload separado, o JWS gerado omitirá o payload e estará no formato:

header..signature

Para um payload separado, você precisa transmitir o payload à política VerifyJWS usando o elemento <DetachedContent>. O payload de conteúdo especificado precisa estar no formato não codificado original de quando a assinatura JWS foi criada.

A política gera um erro quando:

  • <DetachedContent> é especificado quando o JWS não contém um payload de conteúdo separado (o código da falha é steps.jws.ContentIsNotDetached).
  • <DetachedContent> é omitido e o JWS tem um payload de conteúdo separado (o código da falha é steps.jws.InvalidSignature).
Padrão N/A
Presença Opcional
Tipo Referência da variável

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Defina como falso se você quiser que a política gere um erro quando qualquer cabeçalho listado no cabeçalho crit do JWS não estiver listado no elemento <KnownHeaders>. Defina como verdadeiro para fazer com que a política VerifyJWS ignore o cabeçalho crit.

Uma razão para definir esse elemento como verdadeiro é se você estiver em um ambiente de teste e não quiser que a política falhe devido a um cabeçalho ausente.

Padrão falso
Presença Opcional
Tipo Booleano
Valores válidos verdadeiro ou falso

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Defina como falso se você quiser que a política gere um erro quando qualquer variável referenciada especificada na política não for resolvida. Defina como "true" para tratar qualquer variável não resolvida como uma string vazia (null).

Padrão falso
Presença Opcional
Tipo Booleano
Valores válidos verdadeiro ou falso

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

A política GenerateJWS usa o elemento <CriticalHeaders> para preencher o cabeçalho crit em um token. Exemplo:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

A política VerifyJWS examina o cabeçalho crit no JWS, se ele existir, e para cada item listado, ele verifica se o elemento <KnownHeaders> também lista esse cabeçalho. O elemento <KnownHeaders> pode conter um superconjunto dos itens listados em crit. Só é necessário que todos os cabeçalhos listados em crit estejam listados no elemento <KnownHeaders>. Qualquer cabeçalho que a política encontre em crit que também não esteja listado em <KnownHeaders> causará falha na política VerifyJWS.

Opcionalmente, você pode configurar a política VerifyJWS para ignorar o cabeçalho crit definindo o elemento <IgnoreCriticalHeaders> como true.

Padrão N/A
Presença Opcional
Tipo Matriz de strings separadas por vírgulas
Valores válidos Uma matriz ou o nome de uma variável que contém a matriz.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Especifica um valor no formato JWKS (RFC 7517, em inglês) que contém um conjunto de chaves públicas. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Se o JWS de entrada tiver um ID de chave presente no conjunto de JWKS, a política usará a chave pública correta para verificar a assinatura do JWS. Para detalhes sobre esse recurso, consulte Como usar um conjunto de chaves da Web JSON (JWKS, na sigla em inglês) para verificar um JWS.

Se você buscar o valor de um URL público, a Apigee armazenará o JWKS em cache por um período de 300 segundos. Quando o cache expira, a Apigee busca o JWKS novamente.

Padrão N/A
Presença Para verificar um JWS usando um algoritmo RSA, use o elemento JWKS ou Value.
Tipo String
Valores válidos Uma variável de fluxo, valor de string ou URL.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

Especifica a chave pública usada para verificar a assinatura no JWS. Use o atributo ref para passar a chave em uma variável de fluxo ou especifique a chave codificada em PEM diretamente. Use somente quando o algoritmo for um RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Padrão N/A
Presença Para verificar um JWS assinado com um algoritmo RSA, use os elementos JWKS ou Value.
Tipo String
Valores válidos Uma variável de fluxo ou string.

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Value ref="private.your-variable-name"/>
</SecretKey>

Especifica a chave secreta a ser usada ao verificar um JWS que usa um algoritmo simétrico (HS*), um dos tipos HS256, HS384 ou HS512.

Este elemento é opcional. No entanto, você precisa incluir exatamente um dos elementos <PublicKey> ou <SecretKey>. Use o elemento <PublicKey> ao verificar um JWS com o algoritmo RS*, PS* ou ES* e usa o elemento <SecretKey> ao verificar um JWS com o algoritmo HS*

Filhos de <SecretKey>

A tabela a seguir fornece uma descrição dos elementos e atributos filhos de <SecretKey>:

Filho(a) Presença Descrição
encoding (atributo) Opcional

Especifica como a chave é codificada na variável referenciada. Por padrão, quando nenhum atributo encoding está presente, a codificação da chave é tratada como UTF-8. Os valores válidos para o atributo são: hex, base16, base64 ou base64url. Os valores de codificação hex e base16 são sinônimos.

<SecretKey encoding="base64" >
  <Value ref="private.secretkey"/>
</SecretKey>

No exemplo acima, como a codificação é base64, se o conteúdo da variável private.secretkey for SUxvdmVBUElz, a chave será decodificada como um conjunto de 9 bytes, que no hex será 49 4c 6f 76 65 41 50 49 73.

Valor (elemento) Obrigatório

Uma chave do secret codificada. Especifica a chave de secret que será usada para verificar o payload. Use o atributo ref para fornecer a chave indiretamente usando uma variável, como private.secret-key.

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

A Apigee aplica uma força mínima fundamental aos algoritmos HS256/HS384/HS512. O comprimento mínimo de chave para HS256 é 32 bytes, para HS384 é 48 bytes e para HS512 é 64 bytes. O uso de uma chave de força mais baixa causa um erro de tempo de execução.

<Source>

<Source>JWS-variable</Source>

Se presente, especifica a variável de fluxo em que a política espera encontrar o JWS para verificar.

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.

<Type>

<Type>type-string-here</Type>

Elemento opcional em que o único valor permitido é Signed, especificando que a política verifica um JWS assinado. <Type> é fornecido apenas para correspondência do respectivo elemento das políticas GenerateJWT e VerifyJWT, em que ele pode assumir um destes valores: Signed ou Encrypted.

Padrão N/A
Presença Opcional
Tipo String
Valor válido Signed

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

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha Estado de HTTP Ocorre quando
steps.jws.AlgorithmInTokenNotPresentInConfiguration 401 Ocorre quando a política de validação tem vários algoritmos
steps.jws.AlgorithmMismatch 401 O algoritmo especificado no cabeçalho pela política Generate não correspondeu ao esperado na política Verify. Os algoritmos especificados têm de corresponder.
steps.jws.ContentIsNotDetached 401 <DetachedContent> é especificado quando o JWS não contém um payload de conteúdo separado.
steps.jws.FailedToDecode 401 A política não conseguiu descodificar o JWS. O JWS está possivelmente danificado.
steps.jws.InsufficientKeyLength 401 Para uma chave inferior a 32 bytes para o algoritmo HS256
steps.jws.InvalidClaim 401 Para uma reivindicação em falta ou uma incompatibilidade de reivindicação, ou um cabeçalho em falta ou uma incompatibilidade de cabeçalho.
steps.jws.InvalidCurve 401 A curva especificada pela chave não é válida para o algoritmo de curva elíptica.
steps.jws.InvalidJsonFormat 401 Foi encontrado um JSON inválido no cabeçalho JWS.
steps.jws.InvalidJws 401 Este erro ocorre quando a validação da assinatura JWS falha.
steps.jws.InvalidPayload 401 A carga útil JWS é inválida.
steps.jws.InvalidSignature 401 <DetachedContent> é omitido e o JWS tem um payload de conteúdo separado.
steps.jws.KeyIdMissing 401 A política Verify usa um JWKS como origem para chaves públicas, mas o JWS assinado não inclui uma propriedade kid no cabeçalho.
steps.jws.KeyParsingFailed 401 Não foi possível analisar a chave pública a partir das informações da chave fornecidas.
steps.jws.MissingPayload 401 O payload JWS está em falta.
steps.jws.NoAlgorithmFoundInHeader 401 Ocorre quando o JWS omite o cabeçalho do algoritmo.
steps.jws.NoMatchingPublicKey 401 A política Verify usa um JWKS como origem para chaves públicas, mas o kid no JWS assinado não está listado no JWKS.
steps.jws.UnhandledCriticalHeader 401 Um cabeçalho encontrado pela política Verify JWS no cabeçalho crit não está listado em KnownHeaders.
steps.jws.UnknownException 401 Ocorreu uma exceção desconhecida.
steps.jws.WrongKeyType 401 Foi especificado o tipo de chave errado. Por exemplo, se especificar uma chave RSA para um algoritmo de curva elíptica ou uma chave de curva para um algoritmo RSA.

Erros de implementação

Estes erros podem ocorrer quando implementa 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 possíveis erros de implementação.

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>