GenerateJWS policy

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O quê

Gera um JWS assinado com um conjunto configurável de reivindicações. Em seguida, 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.

Vídeo

Nota: o vídeo seguinte mostra o editor de proxy clássico na IU do Apigee. A Apigee está a introduzir uma nova versão do Proxy Editor, que tem um design diferente da versão clássica apresentada no vídeo.

Veja um vídeo curto para saber como gerar um JWT assinado. Embora este vídeo seja específico para gerar um JWT, muitos dos conceitos são os mesmos para JWS.

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 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 apenas 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]

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

Use o elemento <Payload> para especificar a carga útil JWS não 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 a carga útil incluída no conteúdo assinado, à parte de 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>

Nota: pode usar uma versão ligeiramente modificada deste exemplo para gerar um JWS para os algoritmos PS* ou ES*. Basta alterar o valor de <Algorithm>RS256</Algorithm> para PS256 ou ES256, etc. A chave que especificar tem de ser compatível com o algoritmo. Para mais informações sobre os requisitos das chaves, consulte Acerca dos algoritmos de encriptação de assinatura.

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:

Nota: os algoritmos RS*, PS* e ES* usam todos os mesmos elementos para especificar a chave. Os dados de chave que fornece têm de ser compatíveis com o algoritmo que especifica. Para mais informações sobre os principais requisitos, consulte o artigo Acerca dos algoritmos de encriptação de assinaturas.

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 <Password> e <Id> são opcionais.
^*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 usa. 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 <displayname></displayname> para etiquetar a política no editor de proxy da IU do Apigee com um nome diferente em linguagem natural.	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 true para que a execução do fluxo continue mesmo depois de uma política falhar.	falso	Opcional
ativada	Defina como true para aplicar a política. Defina como false para "desativar" a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	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, 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.

O elemento <Claim> suporta a funcionalidade de substituição de strings dinâmicas denominada modelos de mensagens quando type=map.

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.

Nota: não faz sentido incluir na lista de CriticalHeaders parâmetros de cabeçalho que não existam no cabeçalho JWS real. O <CriticalHeaders> não adiciona realmente os parâmetros referenciados ao cabeçalho JWS. Define apenas o conteúdo do parâmetro crit. Pode usar o elemento <AdditionalHeader/Claims> para adicionar as reivindicações de cabeçalho referenciadas ou parâmetros.

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

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

O elemento <Payload> suporta a funcionalidade de substituição de strings dinâmicas denominada modelos de mensagens. Um modelo de mensagem permite-lhe fazer a substituição de strings variáveis na string payload-value. No exemplo seguinte, a carga útil seria criada 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>

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>

Este elemento é opcional e só deve ser usado quando o elemento <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 de fluxo ou uma string

<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, private.mypassword

<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 usar 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, 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 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 encoding, 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, uma vez que a codificação é hex, se o conteúdo da variável private.secretkey for 494c6f766541504973, a chave é descodificada como um conjunto de 9 bytes, que em hexadecimal é 49 4c 6f 76 65 41 50 49 73. Nota: o Apigee aplica uma força mínima da chave. Consulte a documentação do elemento Value para ver detalhes.
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 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 vai incluir este identificador de chave como a reivindicação kid no cabeçalho do JWS gerado.
Valor (elemento)	Obrigatória	Uma chave secreta codificada. Especifica a chave secreta usada para assinar a carga útil. Use o atributo ref para fornecer a chave indiretamente através de uma variável, como private.secret-key . <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Nota: o nome da variável tem de incluir o prefixo private, conforme mostrado no exemplo acima. 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.

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

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>