Usar tokens OAuth JWT

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

Veja a documentação do Apigee Edge.

Esta funcionalidade está disponível para o Apigee e o Apigee híbrido.

Este tópico explica como gerar, validar e atualizar tokens de acesso JWT através da política OAuthV2.

Introdução

As operações JWT permitem que a política OAuthV2 gere, valide e atualize tokens de acesso em conformidade com a IETF RFC 9068, uma norma que descreve como emitir tokens de acesso no formato JWT. Os JWTs são usados frequentemente para partilhar reivindicações ou afirmações entre aplicações ligadas. A emissão de tokens de acesso OAuthV2 no formato JWT é uma alternativa à emissão de tokens de acesso opacos.

Quando configurada para JWT, a política OAuthV2 gera e devolve um JWT codificado em Base64 que consiste num cabeçalho, num payload e numa assinatura separados por pontos. Por exemplo:

Figura 1: formato serializado JWT composto por cabeçalho, payload e assinatura separados por pontos.

Os conteúdos codificados destes elementos dependem da forma como configura a política OAuthV2. Na política, especifica parâmetros como o algoritmo de assinatura e os elementos de conteúdo, como o assunto e o nome. Por exemplo, o cabeçalho pode ser descodificado como {"alg":"HS256","typ":"at+JWT"} e o conteúdo pode ser descodificado como: {"sub":"ABC1234567","iat":1516239022}.

Cabeçalho

O cabeçalho especifica uma reivindicação typ (sempre "at+JWT) e a reivindicação alg, indicando o algoritmo usado para assinar o JWT. O Apigee suporta algoritmos RSA e HMAC: RS(256,384,512) e HS(256,384,512).

Payload

O payload consiste em reivindicações sobre a entidade. Algumas reivindicações têm de ser fornecidas na configuração da política, enquanto outras são geradas automaticamente pelo tempo de execução do Apigee. A política suporta as seguintes reivindicações:

Reivindicar	Descrição	Disponibilizado por
iss	O emissor do token. Este valor é definido da seguinte forma: (http|https)://{domain-name-for-proxy}/{proxy-basePath}. Por exemplo: https://api.mycompany.com/auth/v2.	Apigee
sub	O ID de cliente ou o ID do proprietário do recurso (no caso de tipos de concessão de autorização ou palavra-passe). Se o parâmetro appEndUserId for fornecido no pedido, esse valor é usado como o ID do proprietário do recurso. Pode controlar onde este valor é definido através do elemento <AppEndUser> da política OAuthV2.	Programador de APIs
jti	Um ID exclusivo, representado como uma string aleatória suportada por UUID para identificar o token de forma exclusiva.	Apigee
exp	A hora de validade, ou seja, a hora após a qual o token tem de ser considerado inválido. O valor é expresso em tempo epoch (em segundos).	Apigee
iat	A hora de emissão, a hora em que o token foi criado. O valor é expresso em tempo epoch (em segundos).	Apigee
client_id	O identificador exclusivo da aplicação cliente.	Programador de APIs
scope	O âmbito do OAuth atribuído ao token. Consulte também o artigo Trabalhar com âmbitos do OAuth.	Programador de APIs

Assinatura

A assinatura é gerada através do cabeçalho codificado, da carga útil, da chave secreta/privada e do algoritmo. A assinatura é usada para garantir que o conteúdo do token não foi adulterado.

Para mais informações acerca das chaves de acesso de OAuth 2.0 no formato JWT, consulte o IETF RFC 9068: perfil do símbolo da Web JSON (JWT) para chaves de acesso de OAuth 2.0.

Pré-requisitos

Este documento pressupõe que compreende como gerar e validar tokens de acesso OAuthV2 através da política OAuthV2. Quer use as operações JWT ou as operações tradicionais que criam tokens de string opacos, a utilização básica da política OAuthV2 é a mesma. Pode usar tokens de acesso JWT com todos os tipos de autorização OAuthV2 suportados. Consulte também a Introdução ao OAuth 2.0.

A gerar

Use as operações GenerateJWTAccessToken e GenerateJWTAccessTokenImplicitGrant para gerar um token de acesso JWT com a política OAuthV2. Estas operações são semelhantes às operações tradicionais GenerateAccessToken e GenerateAccessTokenImplicitGrant da política. A principal diferença é que a operação JWT devolve um token de acesso formatado em JWT em vez de um token de string opaco. Consulte também o artigo Obtenha tokens OAuth 2.0.

Os exemplos seguintes mostram como usar estas operações na política OAuthV2. Os exemplos usam o client_credentials tipo de autorização; no entanto, pode usar qualquer um dos tipos de autorização suportados com estas operações.

Nota: além de um token de acesso JWT, a resposta da política também inclui um token de atualização opaco.

Gerar um símbolo no formato JWT assinado com um algoritmo HMAC

Especifique o elemento <Algorithm> com um dos algoritmos HMAC (HS256/HS384/HS512). Indique também o <SecretKey>. O exemplo seguinte mostra uma política configurada para gerar um JWT assinado com o algoritmo HS512, usando a chave secreta especificada.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

As chaves secretas são segredos. Para proteger segredos, é uma prática recomendada que o proxy de API os obtenha de um mapa de valores-chave (KVM) com âmbito de ambiente. Consulte também o artigo Usar mapas de chaves-valores.

Gerar um símbolo no formato JWT assinado com um algoritmo RSA

Especifique um dos algoritmos RSA (um de RS256/RS384/RS512) no elemento <Algorithm> e faculte a chave privada no elemento <PrivateKey>. O exemplo seguinte mostra uma política configurada para gerar um JWT assinado com uma chave privada RSA através do algoritmo RS256.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

As chaves privadas RSA são segredos. Para proteger segredos, é uma prática recomendada que o proxy de API os obtenha de um mapa de valores-chave (KVM) com âmbito de ambiente. Consulte também o artigo Usar mapas de chaves-valores.

Gerar um token no formato JWT com o tipo de autorização implícita

A operação GenerateJWTAccessTokenImplicitGrant gera uma chave de acesso JWT através do tipo de autorização implícita. Concede automaticamente ao token o tipo de concessão implícito; por conseguinte, o elemento <SupportedGrantTypes> não é necessário. Como é um JWT, o elemento <Algorithm> é obrigatório. O exemplo seguinte mostra a utilização do algoritmo RS256. Por esse motivo, o elemento <PrivateKey> é obrigatório. Veja também: Use o tipo de concessão implícito.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

As chaves privadas RSA são segredos. Para proteger segredos, é uma prática recomendada que o proxy de API os obtenha a partir de um mapa de valores-chave (KVM) com âmbito de ambiente. Consulte também o artigo Usar mapas de chaves-valores.

A validar

Use a VerifyJWTAccessToken operação para validar uma chave de acesso JWT com a política OAuthV2. Esta operação é semelhante à operação VerifyAccessToken ; a diferença é que VerifyJWTAccessToken aplica-se a tokens no formato JWT, enquanto VerifyAccessToken aplica-se a tokens opacos.

Validar um token de acesso JWT assinado com um algoritmo HMAC

O exemplo seguinte mostra como configurar a política OAuthV2 para validar um token JWT que foi assinado com o algoritmo HS512. Quando usar a operação VerifyJWTAccessToken com um algoritmo HMAC, a configuração da política tem de usar o elemento <SecretKey> para especificar a chave secreta que foi usada para assinar o JWT.

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

As chaves secretas são segredos. Para proteger segredos, é uma prática recomendada que o proxy de API os obtenha a partir de um mapa de valores-chave (KVM) com âmbito de ambiente. Consulte também o artigo Usar mapas de chaves-valores.

Validar um token de acesso JWT assinado com um algoritmo RSA

O exemplo seguinte mostra como configurar a política OAuthV2 para validar um token JWT que foi assinado com o algoritmo RS512. Quando usar a operação VerifyJWTAccessToken com um algoritmo RSA, a configuração da política tem de usar o elemento <PublicKey> para especificar a chave pública que corresponde à chave privada usada para assinar o JWT.

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

A chave pública não é um segredo. As boas opções para armazenar chaves públicas incluem um conjunto de propriedades com âmbito de ambiente ou um mapa de chaves-valores (KVM) com âmbito de ambiente. Consulte também Aceda aos valores definidos da propriedade e Use mapas de valores-chave.

A atualizar

Use a RefreshJWTAccessToken operação para atualizar uma chave de acesso JWT. Esta operação é semelhante à operação RefreshAccessToken tradicional da política. Consulte também o artigo Atualizar um token de acesso.

Atualizar um token de acesso assinado com HMAC

O exemplo de política seguinte ilustra como configurar a política OAuthV2 para atualizar um token JWT que foi assinado com um algoritmo HMAC. Neste caso, os elementos <SecretKey> e <Algorithm> são obrigatórios.

A resposta da operação de atualização é semelhante à resposta de um token gerado recentemente. A operação de atualização gera um novo token JWT com uma data/hora de validade atualizada, mantendo as outras reivindicações iguais.

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

Atualizar um token de acesso JWT assinado com RSA

O exemplo de política seguinte ilustra como configurar a política OAuthV2 para atualizar um token JWT que foi assinado com um algoritmo RSA. Consulte também o artigo Atualizar um token de acesso.

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

As chaves privadas RSA são segredos. Para proteger segredos, é uma prática recomendada que o proxy de API os obtenha a partir de um mapa de valores-chave (KVM) com âmbito de ambiente. Consulte também o artigo Usar mapas de chaves-valores.

Exemplo de resposta do token

Para as operações de geração e atualização, o corpo da resposta é semelhante ao exemplo seguinte. Tenha em atenção que o access_token é representado como um JWT serializado e o token de atualização é um token opaco tradicional.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "[e-mail]",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

Resumo dos elementos da política obrigatórios

A tabela seguinte descreve os elementos específicos de JWT usados nos exemplos anteriores:

Elemento	Tipo	Notas
Algoritmo	Valor estático	Especifica o algoritmo usado para assinar o token.
SecretKey	Valor referenciado	Fornece a chave secreta usada para validar ou assinar tokens com um algoritmo HMAC: HS (256/384/512).
PrivateKey	Valor referenciado	Fornece a chave privada usada para gerar o token. Use apenas quando o algoritmo for um algoritmo RSA: RS (256/384/512).
PublicKey	Valor referenciado	Fornece a chave pública usada para validar o token. Use apenas quando o algoritmo for um algoritmo RSA: RS (256/384/512).

Elementos de políticas não suportados

Os seguintes elementos da política OAuthV2 não são suportados com configurações de tokens JWT:

Elemento	Notas
ExternalAuthorization	Quando gera uma chave de acesso JWT, a política OAuthV2 valida o ID do cliente e o segredo.
ExternalAccessToken	Quando gera um token de acesso JWT, o token é assinado pelo Apigee e as reivindicações são fornecidas pelo Apigee por predefinição ou através da configuração de políticas. A política suporta ExternalRefreshToken, o que pode ajudar nos exemplos de utilização de migração.
RFCCompliantRequestResponse	A geração e a atualização de tokens de acesso JWT estão em conformidade com a RFC por predefinição.

Notas de utilização

• Os JWTs encriptados não são suportados.
• Além de um token de acesso JWT, a resposta da política também inclui um token de atualização opaco para tipos de concessão em que os tokens de atualização são suportados. Apenas os tipos de concessão de código de autorização e palavra-passe suportam tokens de atualização.
• Inclua o cabeçalho de autorização nos pedidos enviados para o proxy que contém a política OAuthV2.
• Não pode revogar um token de acesso JWT. O token JWT gerado permanece válido até expirar. Pode revogar uma chave de atualização associada a uma chave de acesso JWT.
• A geração, a validação e a atualização de chaves de acesso têm de ser processadas pelo Apigee. Embora uma aplicação ou um gateway externo que tenha acesso à chave pública ou secreta possa descodificar o conteúdo do JWT, a aplicação externa não tem informações sobre os produtos da API identificados pela reivindicação client_id e, por isso, não pode desempenhar um papel na autorização do proxy da API.