Política GenerateJWS

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

Confira a documentação da Apigee Edge.

O que

Gera um JWS assinado, com um conjunto configurável de declarações. O JWS pode ser retornado aos clientes, transmitido para destinos de back-end ou usado de outras maneiras. Consulte a visão geral das políticas do JWS e do JWT para uma introdução detalhada.

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

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 gerar um JWT assinado. Este vídeo é específico para gerar um JWT, mas muitos dos conceitos são os mesmos para JWS.

Amostras

Gerar uma JWS assinada com HS256

Esta política de exemplo gera um JWS que é assinado usando o algoritmo HS256. O HS256 depende de um segredo compartilhado para assinar e verificar a assinatura. Essa JWS usa conteúdo "anexado", o que significa que o cabeçalho codificado, o payload e a assinatura são concatenados com ponto para produzir a JWS final:

[header].[payload].[signature]

Use o elemento <Payload> para especificar o payload JWS bruto e não codificado. Neste exemplo, uma variável contém o payload. Quando essa ação de política é acionada, a Apigee codifica o cabeçalho e o payload do JWS e adiciona a assinatura codificada para assinar o JWS digitalmente.

A configuração de política abaixo cria uma JWS a partir de um payload contido na variável my-payload e armazena a 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>

Gerar uma JWT assinada com HS256

Esse exemplo também gera uma JWS com conteúdo anexado que é assinado usando o algoritmo HS256. Nesse caso, o payload é JSON. Definir o cabeçalho typ como JWT resulta em uma JWS assinada que também é um JWT assinado. (referência)

A configuração de política abaixo cria uma JWS a partir de um payload contido na variável json-content e armazena a JWS resultante na variável output-variable. O resultado será uma JWT assinada apenas se a variável json-content tiver um payload JSON e as propriedades nele forem válidas para JWT. Por exemplo, a propriedade exp, se presente, precisará conter um valor numérico. A propriedade aud, se presente, precisará ser uma string ou uma matriz de strings. E assim por diante. Consulte o IETF RFC7519 para mais detalhes sobre os valores válidos para declaraçõ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>

Gerar uma JWS separada

Esta política de exemplo gera uma JWS com conteúdo removido, assinada usando o algoritmo RS256. A geração de uma assinatura RS256 depende de uma chave privada RSA, que precisa ser fornecida no formato codificado PEM.

Uma JWS com conteúdo removido omite o payload da JWS gerada:

[header]..[signature]

Consulte Partes de uma JWS/JWT para saber mais sobre a estrutura e o formato de uma JWS.

Use o elemento <Payload> para especificar o payload JWS bruto e não codificado. Quando essa política é acionada, a Apigee codifica o cabeçalho e o payload da JWS e os usa para gerar a assinatura codificada. No entanto, a JWS gerada omite o payload codificado da JWS serializada. Isso é útil quando o conteúdo assinado é grande ou binário, (como uma imagem ou um PDF), ou ambos. Para permitir a validação, é preciso transmitir os dois elementos, a JWS e o payload que foi incluído no conteúdo assinado, para a parte verificação. Se você estiver usando a política VerifyJWS para verificar a JWS, será possível especificar a variável que contém o payload 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>

Observação: é possível usar uma versão um pouco modificada deste exemplo para gerar uma JWS para os algoritmos PS* ou ES*. Mude o valor de <Algorithm>RS256</Algorithm> para PS256 ou ES256 etc. A chave especificada precisa ser compatível com o algoritmo. Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Como definir os elementos principais

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

Observação: os algoritmos RS*, PS* e ES* usam os mesmos elementos para especificar a chave. Os dados de chave que você fornecer precisam ser compatíveis com o algoritmo especificado. Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Algoritmo	Elementos-chave
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 <Password> e <Id> são opcionais.
^*Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Referência de elemento para gerar JWS

A referência de política descreve os elementos e atributos da política "Gerar 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.

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 pai de política.

Atributo	Descrição	Padrão	Presence
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.	false	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.	true	Opcional
async	Esse atributo está obsoleto.	false	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.
Presence	Opcional
Tipo	String

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica o algoritmo de criptografia para assinar o token.

Padrão	N/A
Presence	Obrigatório
Tipo	String
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>

Coloca os pares de nome/valor adicionais na declaração do cabeçalho da JWS.

O elemento <Claim> aceita o recurso de substituição de strings dinâmicas chamado modelo de mensagem quando type=map.

Padrão	N/A
Presence	Opcional
Valores válidos	Qualquer valor que você queira usar para uma reivindicação adicional. É possível especificar a declaração explicitamente como string, um número, um booleano, um mapa ou uma matriz.

O elemento <Claim> usa estes atributos:

• name: (obrigatório) o nome da declaração, também conhecido como parâmetro.
• 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

<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çalho que precisam ser conhecidos e reconhecidos pelo receptor JWS. Por exemplo, é possível usar esse elemento de configuração para produzir um cabeçalho JWS que, quando decodificado, fica assim:

{
  "typ": "...",
  "alg" : "...",
  "hyb" : "some-value-here",
  "crit" : [ "hyb" ],
}

Esse cabeçalho JWS afirma que o parâmetro de cabeçalho hyb é de importância fundamental e qualquer destinatário da JWS precisa entender o significado e o valor desse parâmetro.

De acordo com o IETF RFC 7515, o destinatário de uma JWS rejeitará a JWS como inválida se ele não entender um ou mais dos parâmetros mencionados no parâmetro crit. Na Apigee, a política VerifyJWS está em conformidade com esse comportamento. Para cada parâmetro listado no parâmetro crit, ele verifica se o elemento <KnownHeaders> da política VerifyJWS também lista esse parâmetro. Qualquer cabeçalho que a política VerifyJWS encontrar em crit que não esteja também listado em <KnownHeaders> faz com que a política VerifyJWS rejeite a JWS.

Observação: não faz sentido incluir qualquer parâmetro de cabeçalho que não exista no cabeçalho JWS real na lista de CriticalHeaders. Na verdade, <CriticalHeaders> não adiciona os parâmetros referenciados ao cabeçalho JWS. Ele define apenas o conteúdo do parâmetro crit. Use <AdditionalHeader/Claims> para adicionar as declarações ou os parâmetros de cabeçalho mencionados.

Padrão	N/A
Presence	Opcional
Tipo	Matriz separada por vírgulas de uma ou mais strings
Valores válidos	Pode ser uma matriz ou uma referência a uma variável que contenha a matriz.

<DetachContent>

<DetachContent>true|false</DetachContent>

Especifica se é necessário gerar a JWS com um payload separado, <DetachContent>true</DetachContent> ou não, <DetachContent>false</DetachContent>.

Se você especificar false, o padrão será o JWS gerado no formato:

[header].[payload].[signature]

Se você especificar "true" para criar uma JWS com um payload separado, a JWS gerada omitirá o payload e estará no formato:

[header]..[signature]

Com uma JWS usando um payload separado, cabe a você transmitir o payload não codificado original para a parte verificadora, junto com a JWS serializada.

Padrão	false
Presence	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	false
Presence	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 definirá com a JWS gerada. Por padrão, a política coloca a JWS na variável de contexto chamada jws.POLICYNAME.generated_jws.

Padrão	jws.POLICYNAME.generated_jws
Presence	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 bruto e não codificado. Especifique uma variável que contém o payload ou uma string.

O elemento <Payload> é compatível com o recurso de substituição de strings dinâmicas chamado modelo de mensagem. Um modelo de mensagem permite substituir strings variáveis na string payload-value. No exemplo a seguir, o payload seria criado a partir de uma combinação de texto e do valor de uma variável.

<Payload>fixed-text-{request.formparam.payload}-more-fixed-text</Payload>

Padrão	N/A
Presence	Obrigatório
Tipo	String, matriz de bytes, stream ou qualquer outra representação do payload JWS não codificado.
Valores válidos	Um modelo de mensagem ou uma referência a uma variável que contém o payload.

Elemento <PrivateKey>

Isso é opcional, para uso somente quando <Algorithm> for uma das opções RS*, PS* ou ES*. Ele especifica a chave privada a ser usada para assinar, além de outras informações relacionadas à chave privada. É usado quando o algoritmo é um algoritmo assimétrico.

<PrivateKey>
   <Value ref="private.privatekey"</Value>
</PrivateKey>

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir exatamente um dos elementos <PrivateKey> ou <SecretKey>. Use o elemento <PrivateKey> quando o algoritmo for RS*, PS* ou ES*, e 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.

Padrão	N/A
Presence	Opcional
Tipo	String
Valores válidos	Uma variável ou fluxo de fluxo

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Especifique a senha que a política deve usar para descriptografar a chave privada, se necessário. Use o atributo ref para passar a chave em uma variável de fluxo.

Padrão	N/A
Presence	Opcional
Tipo	String
Valores válidos	Uma variável de referência de fluxo. Observação: você precisa especificar uma variável de fluxo com o atributo ref. A Apigee rejeitará uma configuração de política inválida em que a senha é especificada em texto simples. A variável de fluxo precisa ter o prefixo "private". Por exemplo, private.mypassword

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Especifica uma chave privada codificada em PEM usada para assinar a JWS. Use o atributo ref para transmitir a chave em uma variável de fluxo.

Padrão	N/A
Presence	Obrigatório ao usar a política para gerar uma JWS usando 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 RSA codificado em PEM. Observação: a variável do fluxo precisa ter o prefixo "private". Por exemplo, private.mykey

<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 ser usada ao gerar 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 <PrivateKey> ou <SecretKey>. Use o elemento <PrivateKey> ao gerar um JWS assinado com um algoritmo assimétrico (um de RS*, PS* ou ES*) e use o elemento <SecretKey> ao gerar um JWS assinado com um algoritmo simétrico (como algoritmo HS*).

Filhos de <SecretKey>

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

Filho(a)	Presence	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="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> No exemplo acima, como a codificação é hex, se o conteúdo da variável private.secretkey for 494c6f766541504973, a chave será decodificada como um conjunto de 9 bytes, que no hex será 49 4c 6f 76 65 41 50 49 73. Observação: a Apigee impõe um nível mínimo de força. Consulte a documentação do elemento Value para mais detalhes.
ID (elemento)	Opcional	O identificador da chave. O valor pode ser qualquer string. É possível especificar o valor como um valor de texto literal ou indiretamente, por uma referência de variável, com o atributo ref. <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 incluirá esse identificador de chave como a declaração kid no cabeçalho do JWT gerado.
Valor (elemento)	Obrigatório	Uma chave do secret codificada. Especifica a chave do secret usada para assinar o payload. Use o atributo ref para fornecer a chave indiretamente usando uma variável, como private.secret-key. <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Observação: o nome da variável precisa incluir o prefixo private como mostrado no exemplo acima. 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.

<Tipo>

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

Elemento opcional em que o único valor permitido é Signed, especificando que a política gera 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
Presence	Opcional
Tipo	String
Valor válido	Signed

Variáveis de fluxo

A política de geração de JWS não define variáveis de fluxo.

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.GenerationFailed	401	A política não pôde gerar o JWS.
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.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 verificação usa um JWKS como fonte para chaves públicas, mas a JWS assinada 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.SigningFailed	401	Em GenerateJWS, para uma chave menor que o tamanho mínimo dos algoritmos HS384 ou HS512
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.
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>