Política GenerateJWT

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

Veja a documentação do Apigee Edge.

O quê

Gera um JWT assinado ou um JWT encriptado, com um conjunto configurável de reivindicaçõ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 uma introdução detalhada.

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.

Como

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.

Vídeo

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

Veja um vídeo curto para saber como gerar um JWT assinado.

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 usa. 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	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar.	falso	Opcional
ativada	Defina como true para aplicar a política. Defina como false para "desativar" a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
assíncrono	Este atributo foi descontinuado.	falso	Descontinuado

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU do Apigee com um nome diferente em linguagem natural.

Predefinição	Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica o algoritmo 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, PS512

<Algorithms>

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

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 apresenta 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 para a 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 documento 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 nestas 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 apresenta 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 direta de chaves, 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, 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 resolúvel. Defina como verdadeiro para tratar qualquer variável não resolúvel como uma string vazia (nula).

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

<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 principal é 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, uma de 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 apresenta uma descrição destes elementos secundários 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 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 no 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 intensidade 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

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

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>