Política GenerateJWT

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

Veja a documentação do Apigee Edge.

A política GenerateJWT gera um JWT assinado ou um JWT encriptado, com um conjunto configurável de afirmações. O JWT 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 ver uma introdução detalhada.

Se a política gera um JWT assinado ou encriptado, depende do elemento que usa para especificar o algoritmo que gera o JWT:

• Se usar o elemento <Algorithm>, a política gera um JWT assinado.
• Se usar o elemento <Algorithms>, a política gera um JWT encriptado.

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.

Gere um JWT assinado

Esta secção explica 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 seguintes ilustram como gerar um JWT assinado.

Algoritmo HS256

Esta política de exemplo gera um novo JWT e assina-o através do algoritmo HS256. O HS256 baseia-se num segredo partilhado para assinar e validar a assinatura.

Quando esta ação de política é acionada, o Apigee codifica o cabeçalho e o payload do JWT e, em seguida, assina digitalmente o JWT. Consulte o vídeo acima para ver um exemplo completo, incluindo como fazer um pedido à política.

A configuração da política aqui cria um JWT com um conjunto de reivindicações padrão, conforme definido pela especificação do JWT, incluindo um prazo de validade de 1 hora, bem como uma reivindicação adicional. Pode incluir todas as reivindicações adicionais que quiser. Consulte a Referência de elementos para ver detalhes sobre os requisitos e as opções de cada elemento nesta política de exemplo.

<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á este cabeçalho…

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

… e terá um payload com conteúdo semelhante ao seguinte:

{
  "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."
}

Os valores das reivindicações iat, exp e jti variam.

Algoritmo RS256

Nota: 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, também tem de especificar uma chave compatível com o algoritmo. Para mais informações sobre os principais requisitos, consulte o artigo Acerca dos algoritmos de encriptação de assinaturas.

Esta política de exemplo gera um novo JWT e assina-o 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 e que pode ser encriptada com uma palavra-passe. Consulte o vídeo acima para ver um exemplo completo, incluindo como fazer um pedido à política.

Quando esta ação de política é acionada, o Apigee codifica e assina digitalmente o JWT, incluindo as reivindicações. Para saber mais sobre as partes de um JWT e como são encriptadas e assinadas, consulte o 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>

Os exemplos acima usam o elemento <Algorithm>, pelo que geram um JWT assinado. O elemento <PrivateKey> especifica a chave criptográfica usada para assinar o JWT. Também existem outros elementos importantes. A que usa depende do algoritmo especificado pelo valor de <Algorithm>, conforme descrito na secção seguinte.

Definir os elementos principais de um JWT assinado

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

• <SecretKey>
• <PrivateKey>

O elemento que usa depende do algoritmo escolhido, conforme apresentado na tabela seguinte:

Nota: os algoritmos RS*, PS* e ES* usam todos os mesmos elementos para especificar a chave, mas os dados da chave ES* são diferentes dos usados pelos algoritmos RS* e PS*.

Algoritmo	Elementos principais
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 principais requisitos, consulte o artigo Acerca dos algoritmos de encriptação de assinatura.

Gere um JWT encriptado

Esta secção explica como gerar um JWT encriptado. Para um JWT encriptado, use o elemento <Algorithms> para especificar os algoritmos de assinatura da chave e do conteúdo.

Exemplo de um JWT encriptado

O exemplo seguinte mostra como gerar um JWT encriptado. O exemplo usa o elemento <Algorithms>, pelo que gera um JWT encriptado.

RSA-OAEP-256

No exemplo abaixo:

• A chave está encriptada com o algoritmo RSA-OAEP-256.
• O conteúdo está encriptado com o algoritmo A128GCM.

O elemento <PublicKey> especifica a chave usada para a encriptação de chaves.

<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 está encriptada com o algoritmo A128KW.
• O conteúdo está encriptado com o algoritmo A128GCM.

O elemento <SecretKey> especifica a chave usada para a encriptação de chaves.

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

Definir os elementos principais de um JWT encriptado

Use exatamente um dos seguintes elementos para especificar a chave de encriptação para GenerateJWT quando quiser gerar um JWT encriptado:

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

O elemento que usa depende do algoritmo de encriptação de chaves escolhido, conforme mostrado na tabela seguinte:

Algoritmo de encriptação de chaves	Elementos principais
RSA-OAEP-256	<PublicKey> <Value ref="rsa_publickey"/> </PublicKey> Nota: a chave tem de ser resolvida para uma chave pública RSA.
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> <Value ref="ec_publickey"/> </PublicKey> Nota: a chave tem de ser resolvida para 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 principais requisitos, consulte o artigo Acerca dos algoritmos de encriptação de assinatura.

Referência do elemento para gerar JWT

A referência da política descreve os elementos e os atributos da política Generate JWT.

Nota: a configuração varia ligeiramente consoante o algoritmo de encriptação que usar. Consulte os exemplos de um JWT assinado ou os exemplos de um JWT encriptado para ver exemplos que demonstram configurações para exemplos de utilização específicos.

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 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	Defina 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 anexada 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 criptográfico usado para assinar o token. Use o elemento <Algorithm> para gerar um JWT assinado.

Nota: use exatamente um dos elementos <Algorithm> e <Algorithms>.

Predefinição	N/A
Presença	Opcional. É necessário um dos seguintes campos: <Algorithm> ou <Algorithms>.
Tipo	String
Valores válidos	HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 e PS512

<Algorithms>

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

Especifica os algoritmos criptográficos para a encriptação de chaves e conteúdo. Use o elemento <Algorithms> para gerar um JWT encriptado.

Nota: use exatamente um dos elementos <Algorithm> e <Algorithms>.

Predefinição	N/A
Opcional. É necessário um dos seguintes campos: <Algorithm> ou <Algorithms>.	Obrigatória
Tipo	String

Elementos secundários de <Algorithms>

A tabela seguinte fornece uma descrição geral dos elementos subordinados de <Algorithms>:

Elemento secundário	Obrigatório?	Descrição
<Key>	Obrigatória	Especifica o algoritmo de encriptação da chave.
<Content>	Obrigatória	Especifica o algoritmo de encriptação do conteúdo.

Algoritmos de encriptação de chaves

A tabela seguinte lista os algoritmos disponíveis para a encriptação de chaves.

Valor de <Key> (algoritmo de encriptação de chaves)	Elemento principal obrigatório
dir	<DirectKey>
RSA-OAEP-256	<PublicKey> (que tem de ser resolvido para 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 tem de ser resolvido para uma chave pública de curva elíptica)

Consulte o artigo Gere um JWT encriptado para ver um exemplo em que o algoritmo de encriptação de chaves é RSA-OAEP-256, pelo que usa o elemento <PublicKey> com o valor que é resolvido para uma chave pública RSA.

Algoritmos de encriptação de conteúdo

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

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

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

A política gera um JWT que contém uma reivindicação aud definida para o valor especificado. Esta reivindicação identifica os destinatários a quem se destina o JWT. Esta é uma das reivindicações registadas mencionadas na RFC7519.

Predefinição	N/A
Presença	Opcional
Tipo	Matriz (uma lista de valores separados por vírgulas)
Valores válidos	Qualquer elemento 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 pares de nome/valor de reivindicação adicionais na carga útil do JWT. Pode especificar a reivindicação explicitamente como uma string, um número, um valor booleano, um mapa ou uma matriz. Um mapa é simplesmente um conjunto de pares de nome/valor.

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.
  Nota: não use nenhum dos nomes de reivindicações registados neste elemento. As reivindicações registadas são especificadas no RFC7519. Incluem: "iss", "sub", "aud", "iat", "exp", "nbf" e "jti".
• 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.

Quando inclui o elemento <Claim>, os nomes das reivindicações são definidos estaticamente quando configura a política. Em alternativa, pode transmitir um objeto JSON para especificar os nomes das reivindicações. Uma vez que o objeto JSON é transmitido como uma variável, os nomes das reivindicações no JWT gerado são determinados no tempo de execução.

Por 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 reivindicações no objeto JSON.

É importante ter em atenção o seguinte comportamento relativamente à utilização de uma referência de variável e um valor de reivindicação explícito no elemento Claim:

O Apigee não gera uma reivindicação nestas condições:

• Se existir uma referência a uma variável, mas não for resolvida, e
• Se não especificar um valor explícito (um valor predefinido) e
• se o atributo da política IgnoreUnresolvedVariables for true.

Se IgnoreUnresolvedVariables for false, o Apigee gera um erro nas condições acima.

O Apigee gera uma reivindicação nas seguintes condições:

• Se estiver presente uma referência a uma variável, mas não for resolvida, e
• Se especificar um valor explícito (um valor predefinido) 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>

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

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.
  Nota: não use nenhum dos nomes de reivindicações registados neste elemento. As reivindicações registadas são especificadas no RFC7519. Incluem: "iss", "sub", "aud", "iat", "exp", "nbf" e "jti".
• 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.

<Compress>

<Compress>true</Compress>

Especifica se o texto é comprimido antes da encriptação. Este elemento só é válido quando gera um JWT encriptado.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Adiciona o cabeçalho crítico, crit, ao cabeçalho JWT. O cabeçalho crit é uma matriz de nomes de cabeçalhos que têm de ser conhecidos e reconhecidos pelo recetor JWT. Por exemplo:

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

De acordo com a especificação, as partes de validação têm de examinar o cabeçalho crit e verificar 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, verifica se o elemento <KnownHeaders> da política VerifyJWT também lista esse cabeçalho. Qualquer cabeçalho que a política VerifyJWT encontre em crit que também não esteja listado em <KnownHeaders> faz com que a política VerifyJWT falhe.

Nota: o <CriticalHeaders> não adiciona realmente os cabeçalhos ao JWT. Apenas define o conteúdo do cabeçalho crit. Pode usar o <AdditionalHeader/Claims> para adicionar os cabeçalhos.

Predefiniçã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>

Nota: atualmente, é inserido um elemento CustomClaims quando adiciona uma nova política GenerateJWT através da IU. Este elemento não é funcional e é ignorado. O elemento correto a usar é <AdditionalClaims>. A IU vai ser atualizada para inserir os elementos corretos mais tarde.

<DirectKey>

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

Especifica uma chave direta para encriptar um JWT quando o algoritmo de encriptação é dir ("encriptação direta").

Elementos secundários de <DirectKey>

A tabela seguinte fornece uma descrição geral dos elementos subordinados de <DirectKey>:

Elemento secundário	Obrigatório?	Descrição
ID	Opcional	Identificador da chave
Valor	Obrigatória	Especifique uma referência a uma variável com o atributo ref. O conteúdo da variável referenciada tem de ser uma codificação de string de uma matriz de bytes, codificada através de um dos seguintes métodos: hexadecimal (base16), base64 ou base64url.

Com a encriptação de chaves direta, pode fornecer diretamente uma série de bytes que atuam como a chave de encriptação de conteúdo (CEK). Tem de especificar a matriz de bytes como uma string codificada. O comprimento necessário da matriz de bytes depende da robustez do algoritmo de encriptação de conteúdo selecionado. Por exemplo, para A256CBC-HS512, tem de fornecer uma chave de exatamente 512 bits ou 64 bytes.

O conteúdo da variável private.directkey tem de ser uma string codificada, através de hexadecimal (base16), base64 ou base64url. Por exemplo, aqui está uma chave de 32 bytes codificada em 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

Para a codificação hexadecimal, os espaços em branco são aceites, mas não necessários, e são aceites letras maiúsculas ou minúsculas (B7 é o mesmo que b7).

O equivalente codificado em base64url do exemplo acima é:

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

Para as variantes base64*, não são aceites espaços em branco e as letras maiúsculas e minúsculas são importantes. Se não especificar uma codificação, a política assume que a codificação é base64.

A seguir, é descrita a duração das chaves necessárias:

Algoritmo de encriptação 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)

Nota: a chave de encriptação de conteúdo fornecida através do elemento <DirectKey> tem de ter exatamente o comprimento certo para o algoritmo de encriptação de conteúdo especificado. Para qualquer algoritmo de encriptação de chaves que não seja o dir, a política gera uma CEK aleatória com o comprimento correto, mas, para o dir, a configuração tem de fornecer uma chave com o tamanho correto explicitamente.

<ExpiresIn>

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

or:

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

Especifica a duração do JWT em milissegundos, segundos, minutos, horas ou dias. Especifique a validade através do elemento XML ou do atributo ref, mas não de ambos.

Nota: trata-se de um intervalo de tempo e não de um valor de tempo absoluto. A quantidade pode ser um valor numérico simples, caso em que é interpretada como milissegundos.

Predefiniçã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 que contém o valor. As unidades de tempo podem ser especificadas da seguinte forma: ms = milissegundos (predefinição) s = segundos m = minutos h = horas d = dias Por exemplo, um ExpiresIn=10d é equivalente a um ExpiresIn de 864000s.

<Id>

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

Gera um JWT com a reivindicação jti específica. Quando o valor de texto e o atributo ref estão ambos vazios, a política gera um jti que contém um UUID aleatório. A reivindicação do ID JWT (jti) é um identificador exclusivo do JWT. Para mais informações sobre jti, consulte o RFC7519.

Predefiniçã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 quiser que a política apresente um erro quando qualquer variável referenciada especificada na política não for resolvível. Defina como true para tratar qualquer variável não resolúvel como uma string vazia (nula).

Predefinição	Falso
Presença	Opcional
Tipo	Booleano
Valores válidos	verdadeiro ou falso

<Issuer>

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

A política gera um JWT que contém uma reivindicação com o nome iss e um valor definido para o valor especificado. Uma reivindicação que identifica o emissor do JWT. Esta é uma das reivindicações registadas mencionadas na RFC7519.

Predefiniçã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 a hora em que o token se torna válido. O token é inválido até à hora especificada. Pode especificar um valor de tempo absoluto ou um tempo relativo ao momento em que o token é gerado.

Predefiniçã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 absolutos

Nome	Formato	Exemplo
ordená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	Seg, 14 de ago de 2017 11:00:21 PDT
RFC 850	EEEE, dd-MMM-yy HH:mm:ss zzz	Segunda-feira, 14-ago-17 às 11:00:21 PDT
ANCI-C	EEE MMM d HH:mm:ss yyyy	Mon Aug 14 11:00:21 2017

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

• 10s
• 60m
• 12h

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Especifica onde colocar o JWT gerado por esta política. Por predefinição, é colocada na variável de fluxo jwt.POLICYNAME.generated_jwt.

Predefiniçã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 encriptar um JWT quando o algoritmo de encriptação é um dos seguintes:

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

Para cada um destes algoritmos principais, tem de fornecer uma palavra-passe a partir da qual a chave de encriptação da chave é derivada através da variável private.password no elemento <Value ref="private.password"/>.

Elementos secundários de <PasswordKey>

A tabela seguinte apresenta uma descrição geral dos elementos subordinados de <PasswordKey>:

Elemento secundário	Presença	Descrição
ID	Opcional	Identificador da chave
Valor	Obrigatória	Especifica a palavra-passe usada para gerar a chave de encriptação de chaves. Use um atributo ref e especifique uma variável, como private.password .
SaltLength	Opcional	Comprimento do sal. Predefinição: 8 bytes.
PBKDF2Iterations	Opcional	Contagem de iterações do PBKDF2: predefiniçã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 usar quando gera um JWT assinado, e o Algorithm é uma variante RSA ou de curva elíptica (EC), uma de RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

Elementos secundários de <PrivateKey>

A tabela seguinte fornece uma descrição dos elementos subordinados de <PrivateKey>:

Elemento secundário	Presença	Descrição
ID	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. A política vai incluir este identificador de chave como a reivindicação kid no cabeçalho do JWT gerado.
Valor	Obrigatória	Uma chave privada codificada em PEM. Especifica a chave privada usada para assinar a carga útil. Use um atributo ref e especifique uma variável, como private.private-key . Se o elemento <Algorithm> contiver uma variante RSA, RS256/RS384/RS512 ou PS256/PS384/PS512, tem de fornecer uma chave privada RSA codificada. Se o elemento <Algorithm> contiver uma variante EC, uma de ES256/ES384/ES512, tem de fornecer uma chave privada de curva elíptica para a curva adequada.
Palavra-passe	Opcional	A palavra-passe que a política deve usar para desencriptar a chave privada, se necessário. Use o atributo ref para transmitir a palavra-passe através de uma variável de fluxo. Nota: tem de especificar uma variável de fluxo. O Apigee rejeita como inválida uma configuração de política em que a palavra-passe é especificada em texto simples. A variável de fluxo tem de 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 usar quando gera um JWT encriptado, e o algoritmo Key é uma variante RSA ou de curva elíptica (EC) – RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW ou ECDH-ES+A256KW.

Elementos secundários de <PublicKey>

Forneça exatamente um dos seguintes elementos: Value, Certificate ou JWKS. Se especificar JWKS, também tem de especificar Id. A tabela seguinte fornece uma descrição destes elementos subordinados de <PublicKey>:

Elemento secundário	Descrição
Valor	Uma chave pública codificada em PEM. Especifica a chave pública que a política deve usar para encriptar a chave de encriptação de conteúdo. Pode especificar a chave literalmente ou indiretamente através de 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 tem de indicar uma chave RSA se usar o algoritmo RSA-OAEP-256 ou uma chave EC da curva adequada se usar um algoritmo EC.
Certificado	Um certificado X.509 codificado em PEM, que envolve uma chave pública. O Apigee extrai a chave pública do certificado e, em seguida, usa essa chave para encriptar a chave de encriptação de conteúdo. Pode especificar o certificado literalmente ou indiretamente através de 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 tem de indicar uma chave RSA se usar o algoritmo RSA-OAEP-256 ou uma chave EC da curva adequada se usar um algoritmo EC. Nota: o Apigee não valida as datas de validade no certificado que fornece, nem valida a cadeia de fidedignidade no certificado. O Apigee trata todos os certificados que especificar com este elemento como válidos e fidedignos.
JWKS	Uma origem JWKS de chaves públicas. Esta será uma lista de chaves seguindo o formato descrito em IETF RFC 7517 – Chave Web JSON (JWK). Pode especificar o JWKS de uma das quatro formas seguintes: 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 deve conter uma string que represente um JWKS. indiretamente através de 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 através de 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, quando especificar um elemento JWKS em GenerateJWT para gerar um JWT encriptado, também tem de 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. Em tempo de execução, o Apigee obtém uma chave do JWKS que tem um campo kid que corresponde a este valor. O elemento Id é obrigatório se usar o elemento JWKS em 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 secreta a usar quando gera um JWT assinado que usa um algoritmo simétrico (HS*) ou quando gera um JWT encriptado que usa um algoritmo simétrico (AES) para a encriptação de chaves.

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="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 é hex e o conteúdo da variável private.secretkey é 494c6f766541504973, a chave é descodificada como um conjunto de 9 bytes, que em hexadecimal é 49 4c 6f 76 65 41 50 49 73. Por outro lado, quando o atributo de codificação é base64 e o conteúdo da variável private.secretkey é VGhpcy1pcy1hLXNlY3JldA, a chave é descodificada como um conjunto de 16 bytes, em hexadecimal: 54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74. 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 JWT 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 força provoca um erro de tempo de execução.

<Subject>

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

ou

<Subject ref="flow_variable" />

Por exemplo:

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

A política gera um JWT que contém uma reivindicação sub, definida para o valor especificado.Esta reivindicação identifica ou faz uma declaração sobre o assunto do JWT. Esta é uma das reivindicações padrão mencionadas no IETF RFC 7519.

Predefinição	N/A
Presença	Opcional
Tipo	String
Valores válidos	Qualquer valor que identifique de forma exclusiva um assunto ou uma variável de fluxo que se refira a um valor.

<Type>

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

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

• Se o elemento <Type> estiver presente:
  • Se o valor de <Type> for Signed, a política gera um JWT assinado e o elemento <Algorithm> tem de estar presente.
  • Se o valor de <Type> for Encrypted, a política gera um JWT encriptado e o elemento <Algorithms> tem de estar presente.
• Se o elemento <Type> estiver ausente:
  • Se o elemento <Algorithm> estiver presente, a política assume que <Type> é Signed.
  • Se o elemento <Algorithms> estiver presente, a política assume que <Type> é Encrypted.
• Se não estiver presente nem <Algorithm> nem <Algorithms>, a configuração é inválida.

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

Variáveis de fluxo

A política Generate JWT não define variáveis de fluxo.

Referência de erro

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration	401	Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch	401	The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.EncryptionFailed	401	Creation of an encrypted JWT failed for a non-specific reason
steps.jwt.FailedToDecode	401	The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed	401	The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength	401	For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim	401	For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration	401	Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve	401	The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidJsonFormat	401	Invalid JSON found in the header or payload.
steps.jwt.InvalidPasswordKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidToken	401	This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch	401	The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch	401	The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch	401	The subject claim failed on token verification.
steps.jwt.KeyIdMissing	401	The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed	401	The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader	401	Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey	401	The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed	401	In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired	401	The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid	401	The token is not yet valid.
steps.jwt.UnhandledCriticalHeader	401	A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException	401	An unknown exception occurred.
steps.jwt.WrongKeyType	401	Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidNameForAdditionalClaim	The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim	If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim	If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader	This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader	If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute	This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidConfigurationForActionAndAlgorithm	If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.
InvalidValueForElement	If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement	This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration	If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration	If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidVariableNameForSecret	This error occurs if the flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidSecretInConfig	This error occurs if the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidTimeFormat	If the value specified in the<NotBefore> element does not use a supported format, the deployment will fail.

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "InvalidToken"
JWT.failed	Todas as políticas de JWT definem a mesma variável em caso de falha.	JWT.failed = true

Exemplo de resposta de erro

Para o processamento de erros, a prática recomendada é captar a parte errorcode da resposta de erro. Não confie no texto em faultstring, porque pode mudar.

Exemplo de regra de falha

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>