Política GenerateJWT

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

Confira a documentação da Apigee Edge.

O que

Gera um JWT assinado ou um JWT criptografado, com um conjunto configurável de declarações. O JWT 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.

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.

Como

Para gerar um JWT assinado ou criptografado, a política depende do elemento usado para especificar o algoritmo que gera o JWT:

• Se você usa o elemento <Algorithm>, a política gera um JWT assinado.
• Se você usa o elemento <Algorithms>, a política gera um JWT criptografado.

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.

Gerar um JWT assinado

Nesta seção, explicamos como gerar um JWT assinado. Para um JWT assinado, use o elemento <Algorithm> para especificar o algoritmo de assinatura da chave.

Exemplos de um JWT assinado

Os exemplos a seguir ilustram como gerar um JWT assinado.

Algoritmo HS256

Essa política de exemplo gera um novo JWT e o assina usando o algoritmo HS256. O HS256 depende de um segredo compartilhado para assinar e verificar a assinatura.

Quando essa ação de política é acionada, a Apigee codifica o cabeçalho e o payload do JWT e assina digitalmente o JWT. Veja o vídeo acima para ver um exemplo completo, incluindo como fazer uma solicitação à política.

A configuração da política criará um JWT com um conjunto de declarações padrão, conforme definido pela especificação JWT, incluindo uma expiração de uma hora, bem como uma declaração adicional. Você pode incluir quantas reivindicações adicionais quiser. Consulte a referência de elemento para detalhes sobre os requisitos e as opções de cada elemento desta política de amostra.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Type>Signed</Type>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

O JWT resultante terá esse cabeçalho…

{
  "typ" : "JWT",
  "alg" : "HS256",
  "kid" : "1918290"
}

... e terão um payload com conteúdo como este:

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-JWT-policy-test",
  "aud" : "fans",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

O valor das declarações iat, exp e jTI varia.

Algoritmo RS256

Observação: use este mesmo exemplo para gerar um JWT para o algoritmo PS256 ou ES256. Basta alterar o valor de <Algorithm>RS256</Algorithm> para PS256 ou ES256. Para ES256, você também precisa especificar uma chave compatível com o algoritmo. Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Esta política de exemplo gera um novo JWT e o assina usando o algoritmo RS256. A geração de uma assinatura RS256 depende de uma chave privada RSA, que precisa ser fornecida em formato codificado em PEM e pode ser criptografada por senha. Veja no vídeo acima um exemplo completo, incluindo como fazer uma solicitação à política.

Quando essa ação de política é acionada, a Apigee codifica e assina digitalmente o JWT, incluindo as declarações. Para saber mais sobre as partes de um JWT e como elas são criptografadas e assinadas, consulte RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <Type>Signed</Type>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

As amostras acima usam o elemento <Algorithm>. Portanto, elas geram um JWT assinado. O elemento <PrivateKey> especifica a chave criptográfica usada para assinar o JWT. Há outros elementos-chave também. Qual você usa depende do algoritmo especificado pelo valor de <Algorithm>, conforme descrito na próxima seção.

Como configurar os elementos-chave de um JWT assinado

Use exatamente um dos elementos a seguir para especificar a chave usada para gerar um JWT assinado:

• <SecretKey>
• <PrivateKey>

O elemento que você usa depende 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, mas os dados de chave ES* são diferentes daqueles usados pelos RS. * e algoritmos PS*.

Algoritmo	Elementos-chave
HS{256/384/512}^*	<SecretKey> <Value ref="private.secretkey"/> <Id ref="secretkey-id">key-1918290</Id> </SecretKey>
RS/PS/ES{256/384/512}^*	<PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="privatekey-id">key-1918290</Id> </PrivateKey>

Nos exemplos acima, os elementos <Password> e <Id> são opcionais.

Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Gerar um JWT criptografado

Nesta seção, explicamos como gerar um JWT criptografado. Para um JWT criptografado, use o elemento <Algorithms> para especificar os algoritmos de assinatura da chave e do conteúdo.

Exemplo de um JWT criptografado

O exemplo a seguir mostra como gerar um JWT criptografado. O exemplo usa o elemento <Algorithms> para gerar um JWT criptografado.

RSA-OAEP-256

No exemplo abaixo:

• a chave é criptografada com o algoritmo RSA-OAEP-256.
• o conteúdo é criptografado com o algoritmo A128GCM.

O elemento <PublicKey> especifica a chave usada para a criptografia da chave.

<GenerateJWT name="gjwt-1">
  <Type>Encrypted</Type>
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <PublicKey>
    <Value ref="rsa_publickey"/>
  </PublicKey>
  <Subject>[e-mail]</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

A128KW

No exemplo abaixo:

• a chave é criptografada com o algoritmo A128KW.
• o conteúdo é criptografado com o algoritmo A128GCM.

O elemento <SecretKey> especifica a chave usada para a criptografia da chave.

<GenerateJWT name='gjwt-2'>
  <Algorithms>
    <Key>A128KW</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey>
    <Value ref='private.secretkey'/>
  </SecretKey>
  <Subject>[e-mail]</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

Como configurar os elementos-chave de um JWT criptografado

Use exatamente um dos elementos a seguir para especificar a chave de criptografia para GenerateJWT quando quiser gerar um JWT criptografado:

• <PublicKey>
• <SecretKey>
• <PasswordKey>
• <DirectKey>

O elemento que você usa depende do algoritmo de criptografia de chaves escolhido, conforme mostrado na tabela a seguir:

Algoritmo de criptografia de chaves	Elementos-chave
RSA-OAEP-256	<PublicKey> <Value ref="rsa_publickey"/> </PublicKey> Observação: a chave precisa resolver com uma chave pública RSA.
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> <Value ref="ec_publickey"/> </PublicKey> Observação: a chave precisa resolvida com uma chave pública de curva elíptica.
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey> <Id>optional key identifier here</Id> <Value ref="private.secretkey"/> </SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey> <Id>optional key identifier here</Id> <Value ref="private.passwordkey"/> <SaltLength> <PBKDF2Iterations> </PasswordKey>
dir	<DirectKey> <Id>optional key identifier here</Id> <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/> </DirectKey>

Para mais informações sobre os requisitos de chave, consulte Sobre algoritmos de criptografia de assinatura.

Referência de elemento para "Gerar JWT"

A referência de política descreve os elementos e atributos da política "Gerar JWT".

Observação: a configuração varia um pouco dependendo do algoritmo de criptografia utilizado. Para demonstrações de configuração de casos de uso específicos, consulte Exemplos de um JWT assinado ou Exemplo de um JWT criptografado.

Atributos que se aplicam ao elemento de nível superior

<GenerateJWT name="JWT" 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 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.	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	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.
Presença	Opcional
Tipo	String

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica o algoritmo de criptografia usado para assinar o token. Use o elemento <Algorithm> para gerar um JWT assinado.

Observação: use exatamente um dos elementos <Algorithm> e <Algorithms>.

Padrão	N/A
Presença	Opcional. É preciso especificar <Algorithm> ou <Algorithms>.
Tipo	String
Valores válidos	HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Especifica os algoritmos de criptografia de chaves e conteúdo. Use o elemento <Algorithms> para gerar um JWT criptografado.

Observação: use exatamente um dos elementos <Algorithm> e <Algorithms>.

Padrão	N/A
Opcional. É preciso especificar <Algorithm> ou <Algorithms>.	Obrigatório
Tipo	String

Elementos filhos de <Algorithms>

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <Algorithms>:

Elemento filho	Obrigatório?	Descrição
<Key>	Obrigatório	Especifica o algoritmo de criptografia de chaves.
<Content>	Obrigatório	Especifica o algoritmo de criptografia de conteúdo.

Algoritmos de criptografia de chaves

A tabela a seguir lista os algoritmos disponíveis para a criptografia de chaves.

Valor de <Key> (algoritmo de criptografia de chaves)	Elemento-chave obrigatório
dir	<DirectKey>
RSA-OAEP-256	<PublicKey> (que precisa resolver com uma chave pública RSA)
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey>
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> (que precisa resolver com uma chave pública de curva elíptica)

Consulte Gerar um JWT criptografado para ver um exemplo do algoritmo de criptografia de chaves RSA-OAEP-256, em que você usa o elemento <PublicKey> com um valor resolvido com uma chave pública RSA.

Algoritmos de criptografia de conteúdo

Os seguintes algoritmos (simétricos, baseados em AES) estão disponíveis para criptografia de conteúdo:

• A128CBC-HS256
• A192CBC-HS384
• A256CBC-HS512
• A128GCM
• A192GCM
• A256GCM

Para mais informações sobre todos esses algoritmos, consulte RFC7518.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

A política gera um JWT contendo uma declaração aud definida como o valor especificado. Essa declaração identifica os destinatários para os quais o JWT é destinado. Esta é uma das declarações registradas mencionadas em RFC7519.

Padrão	N/A
Presença	Opcional
Tipo	Matriz (uma lista de valores separados por vírgula)
Valores válidos	Qualquer conteúdo que identifique o público-alvo.

<AdditionalClaims/Claim>

<AdditionalClaims>
    <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'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Permite especificar outros pares de nome/valor de declaração no payload do JWT. É possível especificar a declaração explicitamente como string, um número, um booleano, um mapa ou uma matriz. Um mapa é simplesmente um conjunto de pares de nome/valor.

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

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.
  Observação: não use nenhum nome de declaração registrado nesse elemento. As declarações registradas são especificadas na RFC7519. Elas incluem: "iss", "sub", "aud", "iat", "exp", "nbf" e "jti".
• 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

Quando você inclui o elemento <Claim>, os nomes das declarações são definidos estaticamente quando você configura a política. Como alternativa, você pode passar um objeto JSON para especificar os nomes das declarações. Como o objeto JSON é transmitido como uma variável, os nomes das declarações no JWT gerado são determinados no ambiente de execução.

Exemplo:

<AdditionalClaims ref='json_claims'/>

Em que a variável json_claims contém um objeto JSON no formato:

{
  "sub" : "[e-mail]",
  "iss" : "urn://[e-mail]",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

O JWT gerado inclui todas as declarações no objeto JSON.

É importante observar o comportamento a seguir em relação ao uso de uma referência de variável e um valor de declaração explícito no elemento Claim:

A Apigee não gerará uma declaração nas seguintes condições:

• se uma referência de variável estiver presente, mas não for resolvida;
• Se você não especificar um valor explícito (um valor padrão) e
• se o atributo de política IgnoreUnresolvedVariables for true.

Se IgnoreUnresolvedVariables for false, a Apigee gerará um erro nas condições acima.

A Apigee gerará uma reivindicação sob estas condições:

• se uma referência de variável estiver presente, mas não for resolvida, e
• se você especificar um valor explícito (um valor padrão) e
• se IgnoreUnresolvedVariables for true ou false

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

Colocar os pares de nome/valor adicionais de declaração no cabeçalho do JWT.

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

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.
  Observação: não use nenhum nome de declaração registrado nesse elemento. As declarações registradas são especificadas na RFC7519. Elas incluem: "iss", "sub", "aud", "iat", "exp", "nbf" e "jti".
• 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

<Compress>

<Compress>true</Compress>

Especifica se o texto será compactado antes da criptografia. Esse elemento só é válido ao gerar um JWT criptografado.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Adiciona o cabeçalho crítico, crit, ao cabeçalho do JWT. O cabeçalho crit é uma matriz de nomes de cabeçalho que precisam ser conhecidos e reconhecidos pelo receptor do JWT. Exemplo:

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

De acordo com a especificação, as partes verificadoras examinam o cabeçalho crit e verificam se cada um desses cabeçalhos é compreendido. Por exemplo, a política VerifyJWT examina o cabeçalho crit. Para cada item listado no cabeçalho crit, é verificado se o elemento <KnownHeaders> da política VerifyJWT também lista esse cabeçalho. Qualquer cabeçalho que a política VerifyJWT encontrar em crit que também não esteja listado em <KnownHeaders> faça com que a política VerifyJWT falhe.

Observação: o <CriticalHeaders> não adiciona os cabeçalhos ao JWT. Ele define apenas o conteúdo do cabeçalho crit. É possível usar o <AdditionalHeader/Claims> para adicionar os cabeçalhos.

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.

<CustomClaims>

Observação: atualmente, um elemento CustomClaims é inserido quando você adiciona uma nova política GenerateJWT por meio da IU. Esse elemento não é funcional e é ignorado. O elemento correto a ser usado é <AdditionalClaims>. A IU será atualizada para inserir os elementos corretos posteriormente.

<DirectKey>

<DirectKey>
  <Id>A12345</Id>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

Especifica uma chave direta para criptografar um JWT quando o algoritmo de criptografia é dir ("criptografia direta").

Elementos filhos de <DirectKey>

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <DirectKey>:

Elemento filho	Obrigatório?	Descrição
ID	Opcional	Identificador de chave
Valor	Obrigatório	Especifique uma referência a uma variável com o atributo ref. O conteúdo da variável referenciada precisa ser uma codificação de string de uma matriz de bytes, codificada por um dos hexadecimais (base16), base64 ou base64url.

Com a criptografia de chave direta, é possível fornecer diretamente uma série de bytes que atuarão como chave de criptografia de conteúdo (CEK, na sigla em inglês). É preciso especificar a matriz de bytes como uma string codificada. O comprimento obrigatório da matriz de bytes depende da força do algoritmo de criptografia de conteúdo selecionado. Por exemplo, para A256CBC-HS512, é necessário fornecer uma chave de exatamente 512 bits, ou 64 bytes.

O conteúdo da variável private.directkey precisa ser uma string codificada por hexadecimal (base16), base64 ou base64url. Este é um exemplo de chave de 32 bytes com codificação hexadecimal:

96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11

A codificação hexadecimal aceita espaço em branco, mas não é obrigatório, e letras maiúsculas e minúsculas (B7 é igual a b7).

O equivalência com a codificação base64url do exemplo acima é:

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

As variantes base64* não aceitam espaço em branco e diferenciam letras maiúsculas de minúsculas. Se você não especifica uma codificação, a política presume que a codificação é base64.

Veja abaixo os comprimentos obrigatórios das chaves:

Algoritmo de criptografia de conteúdo	Requisito de comprimento da chave
A128CBC-HS256	256 bits (32 bytes)
A192CBC-HS384	384 (48)
A256CBC-HS512	512 (64)
A128GCM	128 (16)
A192GCM	192 (24)
A256GCM	256 (32)

Observação: a chave de criptografia de conteúdo fornecida pelo elemento <DirectKey> precisa ter o comprimento exato para o algoritmo de criptografia de conteúdo especificado. Para qualquer algoritmo de criptografia de chaves diferente de dir, a política gera um CEK aleatório com o comprimento exato. No entanto, para dir, a configuração precisa fornecer explicitamente uma chave com o tamanho exato.

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

or:

<ExpiresIn ref='time-value-here'/>

Especifica a vida útil do JWT em milissegundos, segundos, minutos, horas ou dias. Especifique a expiração usando o elemento XML ou o atributo ref, mas não ambos.

Observação: este é um período, não um valor de tempo absoluto. A quantidade pode ser um valor numérico simples. Nesse caso, ela é interpretada como milissegundos.

Padrão	N/A
Presença	Opcional
Tipo	Número inteiro
Valores válidos	Um valor ou uma referência a uma variável de fluxo contendo o valor. As unidades de tempo podem ser especificadas da seguinte maneira: ms = milissegundos (padrão) s = segundos m = minutos h = horas d = dias Por exemplo, um ExpiresIn=10 é equivalente a uma ExpiresIn de 864000s.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Gera um JWT com a declaração jTI específica. Quando o valor de texto e o atributo de referência estão vazios, a política gerará um jti contendo um UUID aleatório. A declaração JWT ID (jTI) é um identificador exclusivo do JWT. Para mais informações sobre jti, consulte RFC7519.

Padrão	N/A
Presença	Opcional
Tipo	String ou referência.
Valores válidos	Uma string ou o nome de uma variável de fluxo que contém o ID.

<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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

A política gera um JWT contendo uma declaração com o nome iss, com um valor definido como o valor especificado. Uma declaração que identifica o emissor do JWT. Este é um dos conjuntos registrados de declarações mencionadas na RFC7519.

Padrão	N/A
Presença	Opcional
Tipo	String ou referência
Valores válidos	Qualquer

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Especifica o horário em que o token se torna válido. O token é inválido até o tempo especificado. É possível especificar um valor de tempo absoluto ou um horário relativo em que o token é gerado.

Padrão	N/A
Presença	Opcional
Tipo	String
Valores válidos	Veja abaixo.

Valores de tempo válidos para o elemento NotBefore para valores de tempo absoluto

Nome	Formato	Exemplo
classificável	yyyy-MM-dd'T'HH:mm:ss.SSSZ	2017-08-14T11:00:21.269-0700
RFC 1123	EEE, dd MMM yyyy HH:mm:ss zzz	Mon, 14 Aug 2017 11:00:21 PDT
RFC 850	EEEE, dd-MMM-yy HH:mm:ss zzz	Monday, 14-Aug-17 11:00:21 PDT
ANCI-C	EEE MMM d HH:mm:ss yyyy	Mon Aug 14 11:00:21 2017

Para valores de tempo relativo, especifique um número inteiro e um período, por exemplo:

• 10s
• 60min
• 12h

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Especifica onde colocar o JWT gerado por essa política. Por padrão, ele é colocado na variável de fluxo jwt.POLICYNAME.generated_jwt.

Padrão	jwt.POLICYNAME.generated_jwt
Presença	Opcional
Tipo	String (um nome de variável de fluxo)

<PasswordKey>

<PasswordKey>
  <Id>abcdefg</Id>
  <Value ref="private.password"/>
  <SaltLength>8</SaltLength>
  <PBKDF2Iterations>10000</PBKDF2>
</PasswordKey>

Especifica uma chave para criptografar um JWT quando o algoritmo de criptografia é um destes:

• PBES2-HS256+A128KW
• PBES2-HS384+A192KW
• PBES2-HS512+A256KW

Para cada um desses algoritmos de chave, você precisa fornecer uma senha que derivará a chave de criptografia de chaves pela variável private.password no elemento <Value ref="private.password"/>.

Elementos filhos de <PasswordKey>

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <PasswordKey>:

Elemento filho	Presença	Descrição
ID	Opcional	Identificador de chave
Valor	Obrigatório	Especifica a senha usada para gerar a chave de criptografia de chaves. Use um atributo ref e especifique uma variável, como private.password.
SaltLength	Opcional	Comprimento de sal. Padrão: 8 bytes.
PBKDF2Iterations	Opcional	Contagem de iterações PBKDF2: padrão: 10.000.

<PrivateKey>

<PrivateKey>
  <Id ref="privatekey-id"/>
  <Value ref="private.pem-encoded-privatekey"/>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Especifica a chave privada a ser usada ao gerar um JWT assinado, e o Algorithm é uma variante de RSA ou curva elíptica (EC, na sigla em inglês), uma entre RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Elementos filhos de <PrivateKey>

A tabela a seguir descreve os elementos filhos de <PrivateKey>:

Elemento filho	Presença	Descrição
ID	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. A política incluirá esse identificador de chave como a declaração kid no cabeçalho do JWT gerado.
Valor	Obrigatório	Uma chave privada codificada em PEM. Especifica a chave privada usada para assinar o payload. Use um atributo ref e especifique uma variável, como private.private-key. Se o elemento <Algorithm> tiver uma variante RSA, RS256/RS384/RS512 ou PS256/PS384/PS512, será necessário fornecer um RSA privado codificado de dados. Se o elemento <Algorithm> tiver uma variante EC, ES256/ES384/ES512, será necessário fornecer uma chave privada de curva elíptica para a curva apropriada.
Senha	Opcional	A senha que a política deve usar para descriptografar a chave privada, se necessário. Use o atributo ref para transmitir a senha usando uma variável de fluxo. Observação: é necessário especificar uma variável de fluxo. 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

<PublicKey>

<PublicKey>
  <!-- specify exactly one of the following -->
  <Value ref="variable-containing-encoded-publickey"/>
  <Value>PEM encoded public key</Value>
  <Certificate ref="variable-containing-encoded-x509-certificate"/>
  <Certificate>PEM encoded X509 certificate</Certificate>
  <JWKS>jwks-content</JWKS>
  <JWKS ref="variable-containing-jwks-content"/>
  <JWKS uri="variable-containing-jwks-content"/>
  <JWKS uriRef="variable-containing-uri"/>
</PublicKey>

Especifica a chave pública a ser usada ao gerar um JWT criptografado, e o algoritmo Key é uma variante RSA ou de curva elíptica (EC, na sigla em inglês): RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW ou ECDH-ES+A256KW.

Elementos filhos de <PublicKey>

Forneça exatamente uma entre Value, Certificate ou JWKS. Se você especificar JWKS, também precisará especificar Id. A tabela a seguir descreve esses elementos filhos de <PublicKey>:

Elemento filho	Descrição
Valor	Uma chave pública codificada em PEM. Especifica a chave pública que a política precisa usar para criptografar a chave de criptografia de conteúdo. É possível especificar a chave literalmente ou indiretamente usando uma referência de variável. <PublicKey> <Value ref="public.publickey"/> </PublicKey> ou <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW 2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey> A chave pública codificada precisará indicar uma Chave RSA se você usar o algoritmo RSA-OAEP-256 ou uma chave EC da curva apropriada se você usar um algoritmo EC.
Certificado	Um certificado X.509 codificado em PEM, que encapsula uma chave pública. A Apigee vai extrair a chave pública do certificado e usá-la para criptografar a chave de criptografia de conteúdo. É possível especificar o certificado literalmente ou indiretamente usando uma referência de variável. <PublicKey> <Certificate ref="public.pem-encoded-certificate"/> </PublicKey> ou <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC 2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv ... YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8 rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw== -----END CERTIFICATE----- </Certificate> </PublicKey> A chave pública codificada precisará indicar uma Chave RSA se você usar o algoritmo RSA-OAEP-256 ou uma chave EC da curva apropriada se você usar um algoritmo EC. Observação: a Apigee não valida as datas de validade no certificado fornecido, nem valida a cadeia de confiança no certificado. A Apigee trata todos os certificados especificados com esse elemento como válidos e confiáveis.
JWKS	Uma origem de chaves públicas JWKS. Essa será uma lista de chaves que seguem o formato descrito em IETF RFC 7517 - JSON Web Key (JWK). É possível especificar o JWKS de quatro maneiras: literalmente, como um valor de texto: <PublicKey> <JWKS>jwks-content-here</JWKS> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> indiretamente, com o atributo ref, especificando uma variável de fluxo: <PublicKey> <JWKS ref="variable-containing-jwks-content"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> A variável referenciada precisa conter uma string que representa um JWKS. indiretamente, usando um URI estático, com o atributo uri: <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> indiretamente, usando um URI determinado dinamicamente, com o atributo uriRef: <PublicKey> <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> Em todos os casos, ao especificar um elemento JWKS dentro de GenerateJWT para gerar um JWT criptografado, você também precisará especificar o elemento PublicKey/Id. <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey>
ID	Uma string que representa o identificador da chave. No ambiente de execução, a Apigee recupera uma chave do JWKS que tem um campo kid correspondente a esse valor. O elemento Id será obrigatório se você usar o elemento JWKS dentro de GenerateJWT.

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.variable-here"/>
</SecretKey>

O elemento SecretKey é opcional. Especifica a chave do secret que será usada ao gerar um JWT assinado que usa um algoritmo simétrico (HS*) ou ao gerar um JWT criptografado que usa um algoritmo simétrico (AES) para criptografia de chaves.

Filhos de <SecretKey>

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

Filho(a)	Presença	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="VALUE_HERE" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> No exemplo acima, quando o atributo de codificação for hex e o conteúdo da variável private.secretkey for 494c6f766541504973, a chave será decodificada como um conjunto de 9 bytes, que em hexadecimal será 49 4c 6f 76 65 41 50 49 73. Por outro lado, quando o atributo de codificação for base64 e o conteúdo da variávelprivate.secretkey for VGhpcy1pcy1hLXNlY3JldA, a chave será decodificada como um conjunto de 16 bytes, em hexadecimal: 54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74. 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 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 tamanho mínimo da 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.

<Subject>

<Subject>subject-string-here</Subject>

ou

<Subject ref="flow_variable" />

Exemplo:

<Subject ref="apigee.developer.email"/>

A política gera um JWT contendo uma declaração sub, definida como o valor especificado.Essa declaração identifica ou faz uma instrução sobre o assunto do JWT. Esse é um dos conjuntos padrão de declarações mencionados no IETF RFC 7519.

Padrão	N/A
Presença	Opcional
Tipo	String
Valores válidos	Qualquer valor que identifica exclusivamente um assunto ou uma variável de fluxo referente a um valor.

<Type>

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

Descreve se a política gera um JWT assinado ou um criptografado. O elemento <Type> é opcional. É possível usá-lo para informar os leitores da configuração se a política gera um JWT assinado ou criptografado.

• Se o elemento <Type> estiver presente:
  • Se o valor de <Type> é Signed, a política gera um JWT assinado, e o elemento <Algorithm> precisa estar presente.
  • Se o valor de <Type> é Encrypted, a política gera um JWT criptografado, e o elemento <Algorithms> precisa estar presente.
• Se o elemento <Type> estiver ausente:
  • Se o elemento <Algorithm> estiver presente, a política presumirá que <Type> é Signed.
  • Se o elemento <Algorithms> estiver presente, a política presumirá que <Type> é Encrypted.
• Se <Algorithm> e <Algorithms> não estiverem presentes, a configuração será inválida.

Padrão	N/A
Presença	Opcional
Tipo	String
Valores válidos	Signed ou Encrypted

Variáveis de fluxo

A política "Gerar JWT" 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 falhas para lidar com elas. 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.jwt.AlgorithmInTokenNotPresentInConfiguration	401	Ocorre quando a política de verificação tem vários algoritmos.
steps.jwt.AlgorithmMismatch	401	O algoritmo especificado na política de geração não corresponde ao esperado na política de verificação. Os algoritmos especificados precisam corresponder.
steps.jwt.EncryptionFailed	401	Falha na criação de um JWT criptografado por um motivo não específico
steps.jwt.FailedToDecode	401	A política não conseguiu decodificar o JWT. É possível que o JWT esteja corrompido.
steps.jwt.GenerationFailed	401	A política não pôde gerar o JWT.
steps.jwt.InsufficientKeyLength	401	Para uma chave com menos de 32 bytes para o algoritmo HS256, menos de 48 bytes para o algoritmo HS386 e menos de 64 bytes para o algoritmo HS512.
steps.jwt.InvalidClaim	401	Uma falta de reivindicação ou incompatibilidade de reivindicação ou falta de cabeçalho ou cabeçalho incompatível.
steps.jwt.InvalidConfiguration	401	Os elementos <Algorithm> e <Algorithms> estão presentes.
steps.jwt.InvalidCurve	401	A curva especificada pela chave não é válida para o algoritmo de curva elíptica.
steps.jwt.InvalidJsonFormat	401	JSON inválido encontrado no cabeçalho ou payload.
steps.jwt.InvalidPasswordKey	401	A chave especificada não atendeu aos requisitos.
steps.jwt.InvalidPrivateKey	401	A chave especificada não atendeu aos requisitos.
steps.jwt.InvalidPublicKey	401	A chave especificada não atendeu aos requisitos.
steps.jwt.InvalidSecretKey	401	A chave especificada não atendeu aos requisitos.
steps.jwt.InvalidToken	401	Esse erro ocorre quando a verificação de assinatura do JWT falha.
steps.jwt.JwtAudienceMismatch	401	A declaração de público falhou na verificação do token.
steps.jwt.JwtIssuerMismatch	401	A declaração do emissor falhou na verificação do token.
steps.jwt.JwtSubjectMismatch	401	A declaração do assunto falhou na verificação do token.
steps.jwt.KeyIdMissing	401	A política de verificação usa um JWKS como fonte para chaves públicas, mas o JWT assinado não inclui uma propriedade kid no cabeçalho.
steps.jwt.KeyParsingFailed	401	Não foi possível analisar a chave pública com as informações de chave fornecidas.
steps.jwt.NoAlgorithmFoundInHeader	401	Ocorre quando o JWT não contém cabeçalho de algoritmo.
steps.jwt.NoMatchingPublicKey	401	A política de verificação usa uma JWKS como fonte para chaves públicas, mas o kid no JWT assinado não está listado na JWKS.
steps.jwt.SigningFailed	401	Em GenerateJWT, para uma chave menor que o tamanho mínimo para os algoritmos HS384 ou HS512
steps.jwt.TokenExpired	401	A política tenta verificar um token expirado.
steps.jwt.TokenNotYetValid	401	O token ainda não é válido.
steps.jwt.UnhandledCriticalHeader	401	Um cabeçalho encontrado pela política de verificação de JWT no cabeçalho crit não está listado em KnownHeaders.
steps.jwt.UnknownException	401	Ocorreu uma exceção desconhecida.
steps.jwt.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.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

Nome do erro	Causa	Correção
InvalidNameForAdditionalClaim	A implantação falhará se a reivindicação usada no elemento filho <Claim> do elemento <AdditionalClaims> é um dos seguintes nomes registrados: kid, iss, sub, aud, iat, exp, nbf ou jti.
InvalidTypeForAdditionalClaim	Se a declaração usada no elemento filho <Claim> do elemento <AdditionalClaims> não for do tipo string, number, boolean ou map, a implantação falhará.
MissingNameForAdditionalClaim	Se o nome da declaração não for especificado no elemento filho <Claim> do elemento <AdditionalClaims>, a implantação falhará.
InvalidNameForAdditionalHeader	Esse erro ocorre quando o nome da declaração usado no elemento filho <Claim> do elemento <AdditionalClaims> é alg ou typ.
InvalidTypeForAdditionalHeader	Se o tipo de declaração usado no elemento filho <Claim> do elemento <AdditionalClaims> não for do tipo string, number, boolean ou map, a implantação falhará.
InvalidValueOfArrayAttribute	Este erro ocorre quando o valor do atributo de matriz no elemento filho <Claim> do elemento <AdditionalClaims> não está definido como true ou false.
InvalidConfigurationForActionAndAlgorithm	Se o elemento <PrivateKey> é usado com os algoritmos da família HS ou o elemento <SecretKey> é usado com os algoritmos da família RSA, a implantação falhará.
InvalidValueForElement	Se o valor especificado no elemento <Algorithm> não for um valor compatível, a implantação falhará.
MissingConfigurationElement	Esse erro ocorrerá se o elemento <PrivateKey> não for usado com algoritmos de família RSA ou se o elemento <SecretKey> não for usado com algoritmos da família HS.
InvalidKeyConfiguration	Se o elemento filho <Value> não estiver definido nos elementos <PrivateKey> ou <SecretKey>, a implantação falhará.
EmptyElementForKeyConfiguration	Se o atributo de referência do elemento filho <Value> dos elementos <PrivateKey> ou <SecretKey> estiver vazio ou não especificado, a implantação falhará.
InvalidVariableNameForSecret	Esse erro ocorrerá se o nome da variável de fluxo especificado no atributo ref do elemento filho <Value> dos elementos <PrivateKey> ou <SecretKey> não incluir o prefixo privado ((private.)).
InvalidSecretInConfig	Esse erro ocorrerá se o elemento filho <Value> dos elementos <PrivateKey> ou <SecretKey> não contiver o prefixo privado (private.).
InvalidTimeFormat	Se o valor especificado no elemento <NotBefore> não usar um formato compatível, a implantação falhará.

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 "InvalidToken"
JWT.failed	Todas as políticas do JWT definem a mesma variável em caso de falha.	JWT.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="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>