Política GenerateJWS

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X.
informações

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.

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 um JWS anexado assinado com o algoritmo HS256

Esta política de exemplo gera um JWS anexado e o assina usando o algoritmo HS256. O HS256 depende de um segredo compartilhado para assinar e verificar a assinatura.

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

header.payload.signature

Defina <DetachContent> como verdadeiro para gerar conteúdo separado. Consulte Partes de um JWS/JWT para saber mais sobre a estrutura e o formato de um JWS.

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 for acionada, O Edge codifica o cabeçalho e o payload da 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 um payload contido na variável private.payload.

<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="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Gerar um JWS desconectado com o algoritmo RS256

Esta política de exemplo gera uma JWS separada e a assina 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 separada omite a carga do JWS:

header..signature

Use o elemento <Payload> para especificar o payload JWS bruto e não codificado. Quando essa política é acionada, o Edge codifica o cabeçalho e o payload da JWS, e as usa para gerar a assinatura codificada. No entanto, a JWS gerada omite o payload. Você é responsável por passar o payload para a política VerifyJWS usando 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="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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:

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 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 interface de gerenciamento de borda aplica 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 de gerenciamento 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 Suspenso

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento 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

<Algoritmo>S

<Algorithm>algorithm-here</Algorithm>

Especifica o algoritmo de criptografia para assinar o token.

Padrão N/A
Presença 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.

Padrão N/A
Presença 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.
  • 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. Exemplo:

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

No ambiente de execução, a política VerifyJWS examina o cabeçalho crit. Para cada cabeçalho listado no cabeçalho crítico, ele verifica se o elemento <KnownHeaders> da política VerifyJWS também lista esse cabeçalho. Qualquer cabeçalho que a política VerifyJWS encontrar em crit que não esteja listado em <KnownHeaders> causará falha da política VerifyJWS.

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.

<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 um payload separado, o JWS gerado omite o payload e está no formato:

header..signature

Com um payload independente, você decide passar o payload não codificado original para a política VerifyJWS usando o elemento <DetachedContent> da política VerifyJWS.

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Especifica onde colocar a JWS gerada por esta política. Por padrão, ele é colocado na variável de fluxo jws.POLICYNAME.generated_jws.

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

Padrão N/A
Presença Obrigatório
Tipo String, matriz de bytes, stream ou qualquer outra representação do payload JWS não codificado.

<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. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Padrão N/A
Presença 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. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Padrão N/A
Presença Opcional
Tipo String
Valores válidos Uma variável de referência de fluxo.

Observação: é necessário especificar uma variável de fluxo. O Edge será rejeitado como inválido configuração de política em que a senha é especificada em texto simples. A variável de fluxo precisa ter o prefixo "particular". 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. Use somente quando o algoritmo for um RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Padrão N/A
Presença Obrigatório para gerar um JWS usando o algoritmo RS256.
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/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Especifica o código da chave (filho) a ser incluído no cabeçalho JWS de um JWS assinado com um algoritmo HMAC. Use somente quando o algoritmo for HS256/HS384/HS512.

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

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Fornece a chave secreta usada para verificar ou assinar tokens com um algoritmo HMAC. Use somente quando o algoritmo for um de HS256/HS384/HS512. Use o atributo ref para transmitir a chave em uma variável de fluxo.

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

Padrão N/A
Presença Obrigatório para algoritmos HMAC.
Tipo String
Valores válidos Uma variável de fluxo que se refere a uma string

Observação: se uma variável de fluxo, ela precisa ter o prefixo "particular". Por exemplo, private.mysecret

Variáveis de fluxo

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

Referência de erros

Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta 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 Para uma reivindicação ausente ou incompatibilidade de reivindicação ou um cabeçalho ou cabeçalho ausente.
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 "Verificar" usa um JWKS como uma 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 base nas 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.

Erro de nome 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>