Política GenerateJWT

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

O que

Gera um JWT assinado 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.

Vídeo

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

Amostras

• Gerar um JWT assinado com o algoritmo HS256
• Gerar um JWT assinado com o algoritmo RS256

Gerar um JWT assinado com o 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, o Edge codifica o cabeçalho e o payload do JWT assina o JWT. Veja no vídeo acima 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>
    <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-edge-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-edge-JWT-policy-test",
  "aud" : "show",
  "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.

Gerar um JWT assinado com o algoritmo RS256

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 no formato codificado PEM. Veja no vídeo acima um exemplo completo, incluindo como fazer uma solicitação à política.

Quando essa ação de política é acionada, o Edge 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">
    <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-edge-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>

Como definir os elementos principais

Os elementos usados para especificar a chave usada para gerar o JWT dependem do algoritmo escolhido, conforme mostrado na tabela a seguir:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

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

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. Consulte os Amostras para ver exemplos que demonstram configurações para casos de uso específicos.

Atributos que se aplicam ao elemento de nível superior

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

Os seguintes atributos são comuns a todos os elementos pai de política.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<Algoritmo>S

<Algorithm>algorithm-here</Algorithm>

Especifica o algoritmo de criptografia para assinar o token.

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

<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> usa estes atributos:

• name: obrigatório. O nome da declaração.
• ref: (opcional) o nome de uma variável de fluxo. Se presente, a política usará o valor dessa variável como a declaração. Se um atributo ref e um valor de declaração explícito forem especificados, o valor explícito será o padrão e será usado se a variável de fluxo referenciada não for resolvida.
• type: (opcional) uma das seguintes opções: string (padrão), número, booleano ou mapa.
• array: (opcional) defina como true para indicar se o valor é uma matriz de tipos. Padrão: false

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" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "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.

<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> usa estes atributos:

• name: obrigatório. O nome da declaração.
• ref: (opcional) o nome de uma variável de fluxo. Se presente, a política usará o valor dessa variável como a declaração. Se um atributo ref e um valor de declaração explícito forem especificados, o valor explícito será o padrão e será usado se a variável de fluxo referenciada não for resolvida.
• type: (opcional) uma das seguintes opções: string (padrão), número, booleano ou mapa.
• array: (opcional) defina como true para indicar se o valor é uma matriz de tipos. Padrão: false

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Adiciona o cabeçalho crítico, crit, ao 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” ],
}

No ambiente de execução, a política Verify JWT examina o cabeçalho crit. Para cada item listado no cabeçalho crit, ele verifica 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.

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

<ExpiresIn>

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

Especifica a vida útil do JWT em milissegundos, segundos, minutos, horas ou dias.

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

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

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

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

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

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

• 10s
• 60m
• 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.

<PrivateKey/Id>

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

or

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

Especifica o ID da chave (kid) a ser incluído no cabeçalho do JWT. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Especifique a senha que a política deve usar para descriptografar a chave privada, se necessário. Use o atributo ref para passar a chave em uma variável de fluxo. Use somente quando o algoritmo for RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Especifica uma chave privada codificada em PEM usada para assinar o JWT. Use o atributo ref para transmitir a chave em uma variável de fluxo. Use somente quando o algoritmo for um RS256/RS384/RS512, PS256/PS384/PS512 ou ES256/ES384/ES512.

<SecretKey/Id>

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

or

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

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

<SecretKey/Value>

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

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

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

<Subject>

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

<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 mencionadas na RFC7519.

Variáveis de fluxo

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

Referência de erros

Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de 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.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém essa política.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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