Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
O quê
Valida a assinatura num JWS recebido de clientes ou outros sistemas. Esta política também extrai cabeçalhos para variáveis de contexto para que as políticas ou as condições subsequentes possam examinar esses valores para tomar decisões de autorização ou encaminhamento. Consulte a vista geral das políticas de JWS e JWT para uma introdução detalhada.
Se o JWS for validado e for válido, o pedido pode prosseguir. Se não for possível validar a assinatura JWS ou se o JWS for inválido devido a algum tipo de erro, todo o processamento é interrompido e é devolvido um erro na resposta.
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.
Para saber mais sobre as partes de um JWS e como são encriptadas e assinadas, consulte o RFC7515.
Vídeo
Veja um vídeo curto para saber como validar a assinatura num JWS. Embora este vídeo seja específico para a validação de um JWT, muitos dos conceitos são os mesmos para JWS.
Exemplos
- Valide um JWS anexado assinado com o algoritmo HS256
- Valide um JWS separado assinado com o algoritmo RS256
Valide um JWS anexado assinado com o algoritmo HS256
Esta política de exemplo valida um JWS anexado que foi assinado com o algoritmo de encriptação HS256, HMAC
usando uma soma de verificação SHA-256. O JWS é transmitido no pedido de proxy através de um parâmetro de formulário denominado
JWS
. A chave está contida numa variável denominada private.secretkey
.
Um JWS em anexo contém o cabeçalho, o payload e a assinatura codificados:
header.payload.signature
A configuração da política inclui as informações de que o Apigee precisa para descodificar e avaliar o JWS, como onde encontrar o JWS (numa variável de fluxo especificada no elemento <Source>
), o algoritmo de assinatura necessário e onde encontrar a chave secreta (armazenada numa variável de fluxo do Apigee, que pode ter sido obtida, por exemplo, a partir do KVM do Apigee).
<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 escreve o respetivo resultado em variáveis de contexto para que as políticas ou as condições subsequentes no proxy de API possam examinar esses valores. Consulte o artigo Variáveis de fluxo para ver uma lista das variáveis definidas por esta política.
Valide um JWS separado assinado com o algoritmo RS256
Esta política de exemplo valida um JWS separado que foi assinado com o algoritmo RS256. Para validar,
tem de indicar a chave pública. O JWS é transmitido no pedido de proxy através de um parâmetro de formulário
denominado JWS
. A chave pública está contida numa variável denominada public.publickey
.
Um JWS separado omite a carga útil do JWS:
header..signature
É da sua responsabilidade transmitir a carga útil à política VerifyJWS especificando o nome da variável que contém a carga útil no elemento <DetachedContent>
. O conteúdo especificado em <DetachedContent>
tem de estar no formato original não codificado em que se encontrava quando a assinatura 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 escreve o respetivo resultado em variáveis de contexto para que as políticas ou as condições subsequentes no proxy de API possam examinar esses valores. Consulte o artigo Variáveis de fluxo para ver uma lista das variáveis definidas por esta política.
Definir os elementos principais
Os elementos que usa para especificar a chave usada para validar o JWS dependem do algoritmo escolhido, conforme mostrado na tabela seguinte:
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 chaves, consulte o artigo Acerca dos algoritmos de encriptação de assinaturas. |
Referência do elemento
A referência da política descreve os elementos e os atributos da política Verify JWS.
Nota: a configuração varia ligeiramente consoante o algoritmo de encriptação que usa. Consulte as amostras para ver exemplos que demonstram configurações para exemplos de utilização específicos.
SAtributos 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 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 |
N/A | Obrigatória |
continueOnError |
Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas.
Definido como |
falso | Opcional |
ativada |
Defina como true para aplicar a política.
Defina como |
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 do Apigee 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 |
<Algorithm>
<Algorithm>HS256</Algorithm>
Especifica o algoritmo de encriptação para assinar o token. Os algoritmos RS*/PS*/ES* usam um par de chaves pública/secreta, enquanto os algoritmos HS* usam um segredo partilhado. Consulte também Acerca dos algoritmos de encriptação de assinatura.
Pode especificar vários valores separados por vírgulas. Por exemplo, "HS256, HS512" ou "RS256, PS256". No entanto, não pode combinar algoritmos HS* com outros nem algoritmos ES* com outros, porque requerem um tipo de chave específico. Pode combinar algoritmos RS* e PS*.
Predefinição | N/A |
Presença | Obrigatória |
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 reivindicação adicionais especificados e se os valores de reivindicação afirmados correspondem.
Uma reivindicação adicional usa um nome que não é um dos nomes de reivindicações JWS padrão registados. O valor de uma reivindicação adicional pode ser uma string, um número, um valor booleano, um mapa ou uma matriz. Um mapa é simplesmente um conjunto de pares de nome/valor. O valor de uma reivindicação de qualquer um destes tipos pode ser especificado explicitamente na configuração da política ou indiretamente através de uma referência a uma variável de fluxo.
Predefinição | N/A |
Presença | Opcional |
Tipo |
String (predefinição), número, booleano ou mapa. O tipo é predefinido como String se não for especificado nenhum tipo. |
Array | Defina como true para indicar se o valor é uma matriz de tipos. Predefinição: false |
Valores válidos | Qualquer valor que queira usar para uma reivindicação adicional. |
O elemento <Claim>
aceita os seguintes atributos:
- name: (obrigatório) o nome da reivindicação.
- ref: (opcional) o nome de uma variável de fluxo. Se estiver presente, a política usa o valor desta variável como a reivindicação. Se forem especificados um atributo ref e um valor de reivindicação explícito, o valor explícito é o predefinido e é usado se a variável de fluxo referenciada não for resolvida.
- type: (opcional) um dos seguintes: string (predefinição), number, boolean ou map
- array: (opcional) defina como verdadeiro para indicar se o valor é uma matriz de tipos. Predefinição: false.
<DetachedContent>
<DetachedContent>variable-name-here</DetachedContent>
Um JWS gerado com uma carga útil de conteúdo tem o seguinte formato:
header.payload.signature
Se usar a política GenerateJWS para criar uma carga útil separada, o JWS gerado omite a carga útil e tem o seguinte formato:
header..signature
Para uma carga útil separada, cabe-lhe a si transmitir a carga útil para a política VerifyJWS através do elemento <DetachedContent>
. A carga útil de conteúdo especificada tem de estar no formato original não codificado em que se encontrava 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 de falha ésteps.jws.ContentIsNotDetached
).<DetachedContent>
é omitido e o JWS tem uma carga útil de conteúdo desanexada (o código de falha ésteps.jws.InvalidSignature
).
Predefinição | N/A |
Presença | Opcional |
Tipo | Referência de variável |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Definido como falso se quiser que a política apresente 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.
Um dos motivos para definir este elemento como verdadeiro é se estiver num ambiente de teste e não quiser que a política falhe devido a um cabeçalho em falta.
Predefinição | falso |
Presença | Opcional |
Tipo | Booleano |
Valores válidos | verdadeiro ou falso |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Defina como falso se quiser que a política apresente um erro quando qualquer variável referenciada especificada na política não for resolúvel. Defina como verdadeiro para tratar qualquer variável não resolúvel como uma string vazia (nula).
Predefiniçã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 num token. Por exemplo:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
A política VerifyJWS examina o cabeçalho crit no JWS, se existir, e, para cada item listado, 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 indicados em crit estejam indicados no elemento
<KnownHeaders>
. Qualquer cabeçalho que a política encontre em crit
que também não esteja listado em <KnownHeaders>
faz com que a política VerifyJWS falhe.
Opcionalmente, pode configurar a política VerifyJWS para ignorar o cabeçalho crit definindo o elemento <IgnoreCriticalHeaders>
como true
.
Predefiniçã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) que contém um conjunto de chaves públicas. Use apenas quando o algoritmo for um de RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.
Se o JWS de entrada tiver um ID da chave presente no conjunto de JWKS, a política usa a chave pública correta para validar a assinatura JWS. Para ver detalhes acerca desta funcionalidade, consulte Usar um conjunto de chaves Web JSON (JWKS) para validar uma JWS.
Se obtiver o valor de um URL público, o Apigee armazena em cache o JWKS durante um período de 300 segundos. Quando a cache expira, o Apigee obtém novamente o JWKS.
Predefinição | N/A |
Presença | Para validar um JWS através de um algoritmo RSA, tem de usar o elemento JWKS ou Value. |
Tipo | String |
Valores válidos | Uma variável de fluxo, um valor de string ou um 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 validar a assinatura no JWS. Use o atributo ref para transmitir a chave numa variável de fluxo ou especificar a chave codificada em PEM diretamente. Use apenas quando o algoritmo for um de RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.
Predefinição | N/A |
Presença | Para validar um JWS assinado com um algoritmo RSA, tem de usar os elementos JWKS ou Value. |
Tipo | String |
Valores válidos | Uma variável de fluxo ou uma string. |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Value ref="private.your-variable-name"/> </SecretKey>
Especifica a chave secreta a usar quando validar um JWS que usa um algoritmo simétrico (HS*), um de HS256, HS384 ou HS512.
Este elemento é opcional. No entanto, tem de incluir exatamente um dos elementos <PublicKey>
ou <SecretKey>
.
Use o elemento <PublicKey>
quando validar um JWS para o qual o algoritmo é RS*, PS* ou ES* e use o elemento <SecretKey>
quando validar um JWS para o qual o algoritmo é HS*.
Filhos de <SecretKey>
A tabela seguinte fornece uma descrição dos elementos e atributos secundários de
<SecretKey>
:
Filho | Presença | Descrição |
---|---|---|
codificação (atributo) | Opcional | Especifica como a chave é codificada na variável referenciada. Por predefinição, quando não está presente o atributo
<SecretKey encoding="base64" > <Value ref="private.secretkey"/> </SecretKey> No exemplo acima, uma vez que a codificação é |
Valor (elemento) | Obrigatória | Uma chave secreta codificada. Especifica a chave secreta que vai ser usada
para validar a carga útil. Use o atributo <SecretKey> <Value ref="private.my-secret-variable"/> </SecretKey> O Apigee aplica uma intensidade mínima da chave para os algoritmos HS256/HS384/HS512. O comprimento mínimo da chave para HS256 é de 32 bytes, para HS384 é de 48 bytes e para HS512 é de 64 bytes. A utilização de uma chave de menor intensidade provoca um erro de tempo de execução. |
<Source>
<Source>JWS-variable</Source>
Se presente, especifica a variável de fluxo na qual a política espera encontrar o JWS a verificar.
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. |
<Type>
<Type>type-string-here</Type>
Elemento opcional cujo único valor permitido é Signed
, que especifica que a política
valida um JWS assinado. <Type>
é fornecido apenas para corresponder ao elemento correspondente para as políticas GenerateJWT e VerifyJWT (onde pode assumir qualquer um dos valores Signed
ou Encrypted
).
Predefinição | N/A |
Presença | Opcional |
Tipo | String |
Valor válido | Signed |
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 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.AlgorithmInTokenNotPresentInConfiguration |
401 |
Ocorre quando a política de verificação tem vários algoritmos |
steps.jws.AlgorithmMismatch |
401 |
O algoritmo especificado no cabeçalho pela política Generate não correspondia ao esperado na
política Verify . Os algoritmos especificados precisam 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 decodificar o JWS. A JWS está possivelmente corrompida. |
steps.jws.InsufficientKeyLength |
401 |
Para uma chave menor que 32 bytes para o algoritmo HS256 |
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.InvalidCurve |
401 |
A curva especificada pela chave não é válida para o algoritmo de curva elíptica. |
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.KeyIdMissing |
401 |
A política de Verify usa um JWKS como fonte 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 com as informações de chave fornecidas. |
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.NoMatchingPublicKey |
401 |
A política de Verify usa um JWKS como fonte 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 |
Tipo incorreto de chave especificado. Por exemplo, se você especificar uma chave RSA para um algoritmo de curva elíptica ou uma chave de curva para um algoritmo RSA. |
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 . |
|
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>