Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Ver documentação do
Apigee Edge.
A política GenerateJWS gera um JWS assinado com um conjunto configurável de reivindicações. O JWS pode ser devolvido aos clientes, transmitido a destinos de back-end ou usado de outras formas. Consulte a vista geral das políticas de JWS e JWT para uma introdução detalhada.
Para saber mais sobre as partes de um JWS e como são encriptadas e assinadas, consulte o RFC7515.
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.
Amostras
Gere um JWS assinado com HS256
Esta política de exemplo gera um JWS assinado com o algoritmo HS256. O HS256 baseia-se num segredo partilhado para assinar e validar a assinatura. Este JWS usa conteúdo "anexado", o que significa que o cabeçalho, o payload e a assinatura codificados são concatenados com pontos para produzir o JWS final:
[header].[payload].[signature]
Use o elemento <Payload> para especificar a carga útil JWS não processada nem codificada.
Neste exemplo, uma variável contém o payload. Quando esta ação de política é acionada,
o Apigee codifica o cabeçalho e a carga útil do JWS e, em seguida, adiciona a assinatura codificada para assinar digitalmente o JWS.
A configuração da política abaixo cria um JWS a partir de uma carga útil contida na variável
my-payload e armazena o JWS resultante na variável
output-variable.
<GenerateJWS name="JWS-Generate-HS256"> <DisplayName>JWS Generate HS256</DisplayName> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> <Payload ref="my-payload"/> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
Gere um JWT assinado com HS256
Este exemplo também gera um JWS com conteúdo anexado que é assinado através do algoritmo HS256. Neste caso, o payload é JSON. Definir o cabeçalho typ como JWT
resulta num JWS assinado que também é um JWT assinado.
(referência)
A configuração da política abaixo cria um JWS a partir de uma carga útil contida na variável
json-content e armazena o JWS resultante na variável
output-variable. O resultado é um JWT assinado se e só se a variável json-content contiver um payload JSON e as propriedades nesse payload JSON forem válidas para JWT. Por exemplo, a propriedade exp, se estiver
presente, tem de conter um valor numérico. A propriedade aud, se estiver presente,
tem de ser uma string ou uma matriz de strings. E assim sucessivamente. Consulte o
IETF RFC7519 para ver
detalhes sobre os valores válidos para reivindicações JWT.
<GenerateJWS name="JWS-Generate-HS256-JWT"> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> <Payload ref="json-content"/> <AdditionalHeaders> <Claim name="typ">JWT</Claim> </AdditionalHeaders> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
Gere um JWS separado
Esta política de exemplo gera um JWS com conteúdo separado, assinado através do algoritmo RS256. A geração de uma assinatura RS256 baseia-se numa chave privada RSA, que tem de ser fornecida no formato codificado em PEM.
Um JWS com conteúdo separado omite a carga útil do JWS gerado:
[header]..[signature]
Use o elemento <Payload> para especificar a carga útil JWS não processada nem codificada.
Quando esta política é acionada, o Apigee codifica o cabeçalho e a carga útil do JWS e, em seguida, usa-os
para gerar a assinatura codificada. No entanto, o JWS gerado omite a carga útil codificada do
JWS serializado. Isto é útil quando o conteúdo assinado é grande ou binário (como uma imagem ou um PDF), ou ambos. Para permitir a validação, tem de transmitir ambos os elementos, o JWS e o payload incluído no conteúdo assinado, à parte que está a fazer a validação. Se estiver a usar a
política VerifyJWS para validar o JWS, pode especificar a variável que contém a carga útil
com o elemento <DetachedContent> da política VerifyJWS.
<GenerateJWS name="JWS-Generate-RS256"> <DisplayName>JWS Generate RS256</DisplayName> <Algorithm>RS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> <Payload ref="my-payload"/> <DetachContent>true</DetachContent> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
Definir os elementos principais
Os elementos que usa para especificar a chave usada para gerar o JWS dependem do algoritmo escolhido, conforme mostrado na tabela seguinte:
| Algoritmo | Elementos principais | |
|---|---|---|
| HS{256/384/512}* | <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> |
|
| RS/PS/ES{256/384/512}* | <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> Os elementos |
|
| *Para mais informações sobre os requisitos de chaves, consulte o artigo Acerca dos algoritmos de encriptação de assinaturas. | ||
Referência de elemento para gerar JWS
A referência da política descreve os elementos e os atributos da política Generate JWS.
Nota: a configuração varia ligeiramente consoante o algoritmo de encriptação que usar. Consulte as amostras para ver exemplos que demonstram configurações para exemplos de utilização específicos.
Atributos que se aplicam ao elemento de nível superior
<GenerateJWS 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>algorithm-here</Algorithm>
Especifica o algoritmo de encriptação para assinar o token.
| Predefinição | N/A |
| Presença | Obrigatória |
| Tipo | String |
| Valores válidos | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 e 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>
Coloca os pares de nome/valor de reivindicação adicionais no cabeçalho do JWS.
| Predefinição | N/A |
| Presença | Opcional |
| Valores válidos | Qualquer valor que queira usar para uma reivindicação adicional. Pode especificar a reivindicação explicitamente como uma string, um número, um valor booleano, um mapa ou uma matriz. |
O elemento <Claim> aceita os seguintes atributos:
- name: (obrigatório) o nome da reivindicação, também conhecido como parâmetro.
- 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.
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref="variable_containing_headers"/>
Adiciona o cabeçalho crítico, crit, ao JWS. O cabeçalho crit é uma matriz de nomes de cabeçalhos que têm de ser conhecidos e reconhecidos pelo recetor JWS. Por exemplo, pode usar este elemento de configuração para produzir um cabeçalho JWS que, quando descodificado, tem o seguinte aspeto:
{
"typ": "...",
"alg" : "...",
"hyb" : "some-value-here",
"crit" : [ "hyb" ],
}Este cabeçalho JWS afirma que o parâmetro de cabeçalho hyb é de importância crítica e que qualquer destinatário do JWS tem de compreender o significado e o valor desse parâmetro.
De acordo com a norma IETF RFC 7515, o destinatário de um JWS deve rejeitar o JWS como inválido se não compreender um ou mais dos parâmetros referenciados no parâmetro crit. No Apigee, a política VerifyJWS está em conformidade com este comportamento.
Para cada parâmetro indicado no parâmetro crit, verifica se o elemento
<KnownHeaders> da política VerifyJWS também indica esse parâmetro.
Qualquer cabeçalho que a política VerifyJWS encontre em crit e que não esteja também listado
em <KnownHeaders> faz com que a política VerifyJWS rejeite o JWS.
| Predefinição | N/A |
| Presença | Opcional |
| Tipo | Matriz separada por vírgulas de uma ou mais strings |
| Valores válidos | Uma matriz ou uma referência a uma variável que contém a matriz. |
<DetachContent>
<DetachContent>true|false</DetachContent>
Especifica se deve gerar o JWS com um payload separado, <DetachContent>true</DetachContent>,
ou não, <DetachContent>false</DetachContent>.
Se especificar false, o valor predefinido, o JWS gerado tem o seguinte formato:
[header].[payload].[signature]
Se especificar verdadeiro para criar um JWS com uma carga útil separada, o JWS gerado omite a carga útil e está no seguinte formato:
[header]..[signature]
Com um JWS que usa uma carga útil separada, cabe-lhe a si transmitir a carga útil original não codificada à parte de validação, juntamente com o JWS serializado.
| 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 true 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 |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
Especifica o nome da variável de contexto que a política vai definir com o JWS gerado.
Por predefinição, a política coloca o JWS na variável de contexto denominada
jws.POLICYNAME.generated_jws.
| Predefinição | jws.POLICYNAME.generated_jws |
| Presença | Opcional |
| Tipo | String (um nome de variável de fluxo) |
<Payload>
<Payload ref="flow-variable-name-here" /> or <Payload>payload-value</Payload>
Especifica o payload JWS não processado nem codificado. Especifique uma variável que contenha o payload ou uma string.
| Predefinição | N/A |
| Presença | Obrigatória |
| Tipo | String, matriz de bytes, stream ou qualquer outra representação da carga útil JWS não codificada. |
| Valores válidos | Um modelo de mensagem ou uma referência a uma variável que contém o payload. |
Elemento <PrivateKey>
Isto é opcional e só deve ser usado quando o <Algorithm> é uma das opções RS*, PS* ou ES*. Especifica a chave privada a usar para a assinatura, bem como outras informações
relacionadas com a chave privada. É usado quando o algoritmo é um algoritmo assimétrico.
<PrivateKey> <Value ref="private.privatekey"</Value> </PrivateKey>
| Predefinição: | N/A |
| Presença: | Opcional. No entanto, tem de incluir exatamente um dos elementos <PrivateKey> ou <SecretKey>.
Use o elemento <PrivateKey> quando o algoritmo for RS*, PS* ou ES* e use o elemento <SecretKey> quando o algoritmo for HS*.
|
| Tipo: | N/A |
<PrivateKey/Id>
<PrivateKey> <Id ref="flow-variable-name-here"/> </PrivateKey> or <PrivateKey> <Id>your-id-value-here</Id> </PrivateKey>
Especifica o ID da chave (kid) a incluir no cabeçalho JWS.
| Predefinição | N/A |
| Presença | Opcional |
| Tipo | String |
| Valores válidos | Uma variável ou uma string de fluxo |
<PrivateKey/Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
Especifique a palavra-passe que a política deve usar para desencriptar a chave privada, se necessário. Use o atributo ref para transmitir a chave numa variável de fluxo.
| Predefinição | N/A |
| Presença | Opcional |
| Tipo | String |
| Valores válidos |
Uma referência de variável de fluxo. Nota: tem de especificar uma variável de fluxo
com o atributo ref. O Apigee rejeita como inválida uma configuração de política na qual a palavra-passe é especificada em texto simples. A variável de fluxo
tem de ter o prefixo "private". Por exemplo, |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
Especifica uma chave privada codificada em PEM usada para assinar o JWS. Use o atributo ref para transmitir a chave numa variável de fluxo.
| Predefinição | N/A |
| Presença | Obrigatório quando usa a política para gerar um JWS com um dos algoritmos RS*, PS* ou ES*. |
| Tipo | String |
| Valores válidos |
Uma variável de fluxo que contém uma string que representa um valor de chave privada codificado em PEM.
Nota: a variável de fluxo tem de ter o prefixo "private". Por exemplo,
|
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
Especifica a chave secreta a usar quando gerar 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 <PrivateKey> ou <SecretKey>.
Use o elemento <PrivateKey> quando gerar um JWS assinado com um algoritmo assimétrico (um de RS*, PS* ou ES*) e use o elemento <SecretKey> quando gerar um JWS assinado com um algoritmo simétrico (algoritmo como 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="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> No exemplo acima, uma vez que a codificação é |
| Id (elemento) | Opcional | O identificador da chave. O valor pode ser qualquer string. Pode especificar o valor como um valor de texto literal ou, indiretamente, através de uma referência de variável, com o atributo <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> A política vai incluir este identificador principal como a reivindicação |
| Valor (elemento) | Obrigatória | Uma chave secreta codificada. Especifica a chave secreta usada para assinar a carga útil.
Use o atributo <SecretKey> <Id ref="flow-variable-name-here"/> <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 força provoca um erro de tempo de execução. |
<Type>
<Type>type-string-here</Type>
Elemento opcional cujo único valor permitido é Signed, que especifica que a política
gera 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
A política Generate JWS não define variáveis de fluxo.
Referência de erro
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. É importante conhecer estas informações se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte o artigo O que precisa de saber sobre 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.GenerationFailed |
401 |
Não foi possível gerar o JWS pela política. |
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.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.SigningFailed |
401 |
Em GenerateJWS, para uma chave inferior ao tamanho mínimo para os algoritmos HS384 ou HS512 |
steps.jws.UnknownException |
401 |
Ocorreu uma exceção desconhecida. |
steps.jws.WrongKeyType |
401 |
Foi especificado um tipo de chave incorreto. 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. |
|
|
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>