Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da 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 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. Exemplo:
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}
.
Header
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 foi 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.
Prerequisites
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 do 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.
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>
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>
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>
Verificando
Use a operação VerifyJWTAccessToken
para verificar um token de acesso JWT com a
política OAuthV2. Esta 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>
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>
Atualizar
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
Veja 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>
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": "developer@example.org", "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:
Element | 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:
Element | 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.