Usando tokens JWT OAuth

Esta página se aplica ao Apigee e ao Apigee híbrido .

Veja a documentação do Apigee Edge .

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 tokens de acesso em conformidade com a IETF RFC 9068 , um padrão que descreve como emitir tokens de acesso no formato JWT. JWTs são comumente usados ​​para compartilhar declarações ou asserçõ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 separados por pontos. Por exemplo:

Figura 1 : Formato serializado JWT consistindo de cabeçalho, carga útil e assinatura separados por pontos.

O conteúdo codificado desses elementos depende de como você configura a política OAuthV2. Na política, você especifica parâmetros como o algoritmo de assinatura e 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} .

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

Carga útil

O payload consiste em declarações sobre a entidade. Algumas declarações devem ser fornecidas na configuração da política, enquanto outras são geradas automaticamente pelo tempo de execução da Apigee. A política oferece suporte às seguintes declarações:

Alegar Descrição Fornecido 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 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. Você pode controlar onde esse valor é definido usando o elemento <AppEndUser> da política OAuthV2. Desenvolvedor de API
jti Um ID exclusivo, representado como uma sequência aleatória apoiada por UUID para identificar exclusivamente o token. Apigee
exp O tempo de expiração, ou seja, o tempo após o qual o token deve ser considerado inválido. O valor é expresso em tempo de época (em segundos). Apigee
iat O momento da emissão, o momento 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 OAuth atribuído ao token. Consulte também Trabalhando com escopos OAuth . Desenvolvedor de API

Assinatura

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

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

Pré-requisitos

Este documento pressupõe que você entenda como gerar e verificar tokens de acesso OAuthV2 usando a política OAuthV2. Independentemente de você usar as operações JWT ou as operações tradicionais que criam tokens de string opaca, o uso básico da política OAuthV2 é o mesmo. Você pode usar tokens de acesso JWT com todos os tipos de concessão OAuthV2 suportados. 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 tradicionais GenerateAccessToken e GenerateAccessTokenImplicitGrant 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 Obter tokens OAuth 2.0 .

Os exemplos a seguir mostram como usar essas operações na política OAuthV2. Os exemplos usam o tipo de concessão client_credentials ; no entanto, você pode usar qualquer um dos tipos de concessão suportados com essas operações.

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

Gerando um token no formato JWT assinado com um algoritmo RSA

Especifique um dos algoritmos RSA (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>

Gerando um token no formato JWT com o tipo de concessão implícita

A operação GenerateJWTAccessTokenImplicitGrant gera um token de acesso JWT usando o tipo de concessão implícita. Ela atribui automaticamente ao token o tipo de concessão implícita; portanto, o elemento <SupportedGrantTypes> não é necessário. Por ser um JWT, o elemento <Algorithm> é necessário. O exemplo a seguir mostra o uso do algoritmo RS256. Por isso, o elemento <PrivateKey> é necessá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>

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 a tokens no formato JWT, enquanto VerifyAccessToken se aplica a tokens opacos.

Verificando 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 deve usar o elemento <SecretKey> para especificar a chave secreta usada para assinar o JWT.

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

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

Refrescante

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 Atualizando um token de acesso .

Atualizando um token de acesso assinado pelo HMAC

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

A resposta da operação de atualização é semelhante à resposta de um token recém-gerado. A operação de atualização gera um novo token JWT com um tempo de expiração atualizado, mantendo as demais declarações inalteradas.

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

Atualizando um token de acesso JWT assinado por RSA

O exemplo de política a seguir ilustra como configurar a política OAuthV2 para atualizar um token JWT assinado com um algoritmo RSA. Consulte também Atualizando 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>

Resposta de token de amostra

Para as operações de geração e atualização, o corpo da resposta é semelhante ao exemplo a seguir. Observe 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": "[email protected]",
  "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 necessários

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

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

Elementos de política não suportados

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

Elemento Notas
Autorização Externa Ao gerar um token de acesso JWT, a política OAuthV2 validará o ID do cliente e o segredo.
Token de acesso externo Ao gerar um token de acesso JWT, o token será assinado pela Apigee e as declarações serão fornecidas pela Apigee por padrão ou por meio da configuração de política. A política oferece suporte ExternalRefreshToken , o que pode auxiliar em casos de uso de migração.
Resposta de solicitação compatível com RFC A geração e atualização de tokens de acesso JWT são compatíveis com RFC por padrão.

Notas de uso

  • JWTs criptografados 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 tokens de atualização são suportados. Somente os tipos de concessão de senha e código de autenticação suportam tokens de atualização.
  • Inclua o cabeçalho de autorização nas solicitações enviadas ao proxy que contêm a política OAuthV2.
  • Não é possível revogar um token de acesso JWT. O token JWT gerado permanecerá válido até expirar. Você pode revogar um token de atualização associado a um token de acesso JWT.
  • A geração, a verificação e a atualização de tokens de acesso devem ser gerenciadas pela Apigee. Embora um aplicativo ou gateway externo com acesso à chave pública ou secreta possa decodificar o conteúdo do JWT, o aplicativo externo não possui informações sobre os produtos da API identificados pela declaração client_id e, portanto, não pode desempenhar um papel na autorização do proxy da API.