Como usar tokens OAuth do JWT

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

Confira a documentação da Apigee Edge.

Este recurso está disponível para a Apigee e a Apigee híbrida.

Este tópico explica como gerar, verificar e atualizar tokens de acesso JWT usando a política OAuthV2.

Introdução

As operações JWT permitem que a política OAuthV2 gere, verifique e atualize os tokens de acesso em conformidade com o IETF RFC 9068, um padrão que descreve como emitir tokens de acesso no formato JWT. Os JWTs são normalmente usados para compartilhar declarações ou declarações entre aplicativos conectados. 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 retorna um JWT codificado em Base64 que consiste em um cabeçalho, um payload e uma assinatura separada por pontos. Por exemplo:

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

O conteúdo codificado desses elementos depende de como a política OAuthV2 é configurada. Na política, você especifica parâmetros como o algoritmo de assinatura e os elementos de payload, como assunto e nome. Por exemplo, o cabeçalho pode ser decodificado como {"alg":"HS256","typ":"at+JWT"}, e o payload pode ser decodificado como: {"sub":"ABC1234567","iat":1516239022}.

Cabeçalho

O cabeçalho especifica uma declaração typ (sempre "at+JWT) e alg, indicando o algoritmo usado para assinar o JWT. A Apigee é compatível com algoritmos RSA e HMAC: RS(256.384.512) e HS(256.384.512).

Payload

O payload consiste em declarações sobre a entidade. Algumas declarações precisam ser fornecidas na configuração da política, enquanto outras são geradas automaticamente pelo ambiente de execução da Apigee. A política é compatível com as seguintes reivindicações:

Resgatar	Descrição	Fornecido por
iss	O emissor do token. Esse 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 do cliente ou o ID do proprietário do recurso (no caso de tipos de concessão de senha ou autorização). Se o parâmetro appEndUserId for fornecido na solicitação, esse valor será usado como o ID do proprietário do recurso. É possível controlar onde esse valor é definido usando o elemento <AppEndUser> da política OAuthV2.	Desenvolvedor de API
jti	Um ID exclusivo, representado como uma string aleatória apoiada por UUID para identificar exclusivamente o token.	Apigee
exp	O prazo de validade, em outras palavras, o período após o qual o token deve ser considerado inválido. O valor é expresso em tempo de época (em segundos).	Apigee
iat	A hora de emissão, a hora em que o token foi criado. O valor é expresso em tempo de época (em segundos).	Apigee
client_id	O identificador exclusivo do aplicativo cliente.	Desenvolvedor de API
scope	O escopo do OAuth atribuído ao token. Consulte também Como trabalhar com escopos do OAuth.	Desenvolvedor de API

Assinatura

A assinatura é gerada usando o cabeçalho codificado, o payload, a chave secreta/privada e o algoritmo. A assinatura é usada para garantir que o conteúdo do token não tenha sido adulterado.

Para mais informações sobre os tokens de acesso OAuth 2.0 no formato JWT, consulte IETF RFC 9068: perfil JSON Web Token (JWT) para tokens de acesso OAuth 2.0.

Pré-requisitos

Este documento presume que você entende como gerar e verificar tokens de acesso OAuthV2 usando a política OAuthV2. Não importa se você usa as operações JWT ou as operações tradicionais que criam tokens de string opacas, o uso básico da política OAuthV2 é o mesmo. É possível usar tokens de acesso JWT com todos os tipos de concessão do OAuthV2 compatíveis. Consulte também Introdução ao OAuth 2.0.

Gerando

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

Os exemplos a seguir mostram como usar essas operações na política do OAuthV2. Os exemplos usam o tipo de concessão client_credentials. No entanto, é possível usar qualquer um dos tipos de concessão compatíveis com essas operações.

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

Gerar um token no formato JWT assinado com um algoritmo HMAC

Especifique o elemento <Algorithm> com um dos algoritmos HMAC (HS256/HS384/HS512). Forneça também o <SecretKey>. O exemplo a seguir 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 secrets. Para proteger os secrets, é uma prática recomendada que o proxy da API os recupere de um mapa de chave-valor (KVM) com escopo no ambiente. Consulte também Como usar mapas de chave-valor.

Gerar um token no formato JWT assinado com um algoritmo RSA

Especifique um dos algoritmos RSA (um dos RS256/RS384/RS512) no elemento <Algorithm> e forneça a chave privada no elemento <PrivateKey>. O exemplo a seguir mostra uma política configurada para gerar um JWT assinado com uma chave privada RSA usando o 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 secrets. Para proteger os secrets, é uma prática recomendada que o proxy da API os recupere de um mapa de chave-valor (KVM) com escopo no ambiente. Consulte também Como usar mapas de chave-valor.

Como gerar um token no formato JWT com o tipo de concessão implícito

A operação GenerateJWTAccessTokenImplicitGrant gera um token de acesso JWT usando o tipo de concessão implícito. Ela fornece automaticamente o token para o tipo de concessão implícita. Portanto, o elemento <SupportedGrantTypes> não é necessário. Como é um JWT, o elemento <Algorithm> é obrigatório. O exemplo a seguir mostra o uso do algoritmo RS256. Por isso, o elemento <PrivateKey> é obrigatório. Consulte também Usar o tipo de concessão implícita.

<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 secrets. Para proteger os secrets, é uma prática recomendada que o proxy da API os recupere de um mapa de chave-valor (KVM) com escopo no ambiente. Consulte também Como usar mapas de chave-valor.

Verificando

Use a operação VerifyJWTAccessToken para verificar um token de acesso JWT com a política OAuthV2. Essa operação é semelhante à operação VerifyAccessToken. A diferença é que VerifyJWTAccessToken se aplica aos tokens no formato JWT, enquanto VerifyAccessToken se aplica aos tokens opacos.

Como verificar um token de acesso JWT assinado com um algoritmo HMAC

O exemplo a seguir mostra como configurar a política OAuthV2 para verificar um token JWT assinado com o algoritmo HS512. Ao usar a operação VerifyJWTAccessToken com um algoritmo HMAC, a configuração da política precisa 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 secrets. Para proteger os secrets, é uma prática recomendada que o proxy da API os recupere de um mapa de chave-valor (KVM) com escopo no ambiente. Consulte também Como usar mapas de chave-valor.

Como verificar um token de acesso JWT assinado com um algoritmo RSA

O exemplo a seguir mostra como configurar a política OAuthV2 para verificar um token JWT assinado com o algoritmo RS512. Ao usar a operação VerifyJWTAccessToken com um algoritmo RSA, a configuração da política precisa 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 secret. Uma boa opção para armazenar chaves públicas é incluir um conjunto de propriedades ou um mapa de chave-valor (KVM) com escopo de ambiente. Consulte também Acessar valores de conjuntos de propriedades e Usar mapas de chave-valor.

Atualizando

Use a operação RefreshJWTAccessToken para atualizar um token de acesso JWT. Essa operação é semelhante à operação RefreshAccessToken tradicional da política. Consulte também Como atualizar um token de acesso.

Como atualizar um token de acesso assinado por HMAC

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

A resposta da operação de atualização é semelhante à resposta de um token recém-gerado. Uma operação de atualização gera um novo token JWT com um prazo de validade atualizado, mantendo outras declaraçõ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>

Como atualizar um token de acesso JWT assinado por RSA

Confira no exemplo de política a seguir como configurar a política do OAuthV2 para atualizar um token JWT assinado com um algoritmo RSA. Consulte também Como 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 secrets. Para proteger os secrets, é uma prática recomendada que o proxy da API os recupere de um mapa de chave-valor (KVM) com escopo no ambiente. Consulte também Como usar mapas de chave-valor.

Exemplo de resposta do token

Para as operações de geração e atualização, o corpo da resposta é semelhante ao exemplo a seguir. Observe que 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 de política obrigatórios

A tabela a seguir descreve elementos específicos do JWT usados nos exemplos anteriores:

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

Elementos de política incompatíveis

Os seguintes elementos da política OAuthV2 não são compatíveis com as configurações de token JWT:

Elemento	Observações
ExternalAuthorization	Ao gerar um token de acesso do JWT, a política OAuthV2 validará o ID do cliente e o secret.
ExternalAccessToken	Ao gerar um token de acesso do JWT, ele será assinado pela Apigee, e as declarações serão fornecidas pela Apigee por padrão ou pela configuração da política. A política é compatível com ExternalRefreshToken, que pode ajudar em casos de uso de migração.
RFCCompliantRequestResponse	A geração e a atualização de tokens de acesso JWT estão em conformidade com RFC por padrão.

Observações sobre uso

• JWTs criptografados não são compatíveis.
• Além de um token de acesso JWT, a resposta da política também inclui um token de atualização opaco para os tipos de concessão em que os tokens de atualização são compatíveis. Somente os tipos de concessão de código de senha e autenticação são compatíveis com tokens de atualização.
• Inclua o cabeçalho "Authorization" em solicitações enviadas ao proxy que contém a política de OAuthV2.
• Não é possível revogar um token de acesso JWT. O token JWT gerado permanecerá válido até expirar. É possível revogar um token de atualização associado a um token de acesso JWT.
• A geração, a verificação e a atualização dos tokens de acesso precisam ser gerenciadas pela Apigee. Embora um aplicativo ou gateway externo que tenha acesso à chave pública ou secreta possa decodificar o conteúdo do JWT, esse aplicativo não tem informações sobre os produtos da API identificados pelo client_id e, portanto, não pode desempenhar um papel na autorização do proxy de API.