Usa tokens de OAuth de JWT

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Esta función está disponible para Apigee y Apigee Hybrid.

En este tema, se explica cómo generar, verificar y actualizar los tokens de acceso JWT con la política de OAuthV2.

Introducción

Las operaciones de JWT permiten que la política OAuthV2 genere, verifique y actualice tokens de acceso que cumplan con IETF RFC 9068, un estándar que describe cómo emitir tokens de acceso en formato JWT. Por lo general, los JWT se usan para compartir reclamaciones o confirmaciones entre aplicaciones conectadas. Emitir tokens de acceso de OAuthV2 en formato JWT es una alternativa a emitir tokens de acceso opacos.

Cuando se configura para JWT, la política de OAuthV2 genera y muestra un JWT codificado en Base64 que consta de un encabezado, una carga útil y una firma separada por puntos. Por ejemplo:

Figura 1: formato serializado de JWT que consta de encabezado, carga útil y firma separada por puntos.

El contenido codificado de estos elementos depende de cómo configures la política de OAuthV2. En la política, especifica esos parámetros, como el algoritmo de firma y los elementos de carga útil, como el asunto y el nombre. Por ejemplo, el encabezado puede decodificarse como {"alg":"HS256","typ":"at+JWT"} y la carga útil puede decodificarse como: {"sub":"ABC1234567","iat":1516239022}.

Header

El encabezado especifica una reclamación typ (siempre "at+JWT) y la reclamación alg, lo que indica el algoritmo usado para firmar el JWT. Apigee admite algoritmos de RSA y HMAC: RS(256,384,512) y HS(256,384,512).

Carga útil

La carga útil consta de reclamaciones sobre la entidad. Algunas reclamaciones deben proporcionarse en la configuración de la política, mientras que el entorno de ejecución de Apigee genera automáticamente otras. La política admite las siguientes reclamaciones:

Canjear	Descripción	Proporcionado por
iss	El emisor del token. Este valor se establece de la siguiente manera: (http|https)://{domain-name-for-proxy}/{proxy-basePath}. Por ejemplo: https://api.mycompany.com/auth/v2.	Apigee
sub	El ID del cliente o el ID del propietario del recurso (en el caso de los tipos de otorgamiento de contraseña o autorización). Si se proporciona el parámetro appEndUserId en la solicitud, ese valor se usa como el ID del propietario del recurso. Puedes controlar dónde se configura este valor con el elemento <AppEndUser> de la política de OAuthV2.	Desarrollador de API
jti	Un ID único, representado como una string aleatoria respaldada por UUID para identificar de forma única el token.	Apigee
exp	La hora de vencimiento, en otras palabras, la hora después de la cual el token debe considerarse no válido. El valor se expresa en tiempo de época (en segundos).	Apigee
iat	La hora de emisión, la hora a la que se creó el token. El valor se expresa en tiempo de época (en segundos).	Apigee
client_id	El identificador único de la aplicación cliente.	Desarrollador de API
scope	El alcance de OAuth asignado al token. Consulta también Trabaja con alcances de OAuth.	Desarrollador de API

Firma

La firma se genera con el encabezado codificado, la carga útil, la clave secreta/privada y el algoritmo. La firma se usa para garantizar que el contenido del token no se haya alterado.

Para obtener más información sobre los tokens de acceso de OAuth 2.0 en formato JWT, consulta IETF RFC 9068: Perfil de token web JSON (JWT) para tokens de acceso de OAuth 2.0.

Prerequisites

En este documento, se supone que comprendes cómo generar y verificar tokens de acceso de OAuthV2 con la política de OAuthV2. Ya sea que uses las operaciones JWT o las operaciones tradicionales que crean tokens de string opacos, el uso básico de la política de OAuthV2 es el mismo. Puedes usar tokens de acceso JWT con todos los tipos de otorgamiento de OAuthV2 compatibles. Consulta también Introducción a OAuth 2.0.

Generando

Usa las operaciones GenerateJWTAccessToken y GenerateJWTAccessTokenImplicitGrant para generar un token de acceso JWT con la política de OAuthV2. Estas operaciones son similares a las operaciones tradicionales GenerateAccessToken y GenerateAccessTokenImplicitGrant de la política. La diferencia principal es que la operación JWT muestra un token de acceso con formato JWT en lugar de un token de string opaco. Consulta también Obtén tokens de OAuth 2.0.

En los siguientes ejemplos, se muestra cómo usar estas operaciones en la política de OAuthV2. En los ejemplos, se usa el tipo de otorgamiento client_credentials. Sin embargo, puedes usar cualquiera de los tipos de otorgamiento compatibles con estas operaciones.

Nota: Además de un token de acceso JWT, la respuesta de la política también incluye un token de actualización opaco.

Genera un token de formato JWT firmado con un algoritmo HMAC

Especifica el elemento <Algorithm> con uno de los algoritmos HMAC (HS256/HS384/HS512). También proporciona la <SecretKey>. En el siguiente ejemplo, se muestra una política configurada para generar un JWT firmado con el algoritmo HS512 mediante la clave 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>

Las claves secretas son secretos. Para proteger secretos, se recomienda que el proxy de API los recupere de un mapa de clave-valor (KVM) con alcance de entorno. Consulta también Usa mapas de clave-valor

Genera un token de formato JWT firmado con un algoritmo de RSA

Especifica uno de los algoritmos de RSA (uno de RS256/RS384/RS512) en el elemento <Algorithm> y proporciona la clave privada en el elemento <PrivateKey>. En el siguiente ejemplo, se muestra una política configurada para generar un JWT firmado con una clave privada de RSA mediante el 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>

Las claves privadas de RSA son secretos. Para proteger secretos, se recomienda que el proxy de API los recupere de un mapa de clave-valor (KVM) con alcance de entorno. Consulta también Usa mapas de clave-valor

Genera un token de formato JWT con el tipo de concesión implícito

La operación GenerateJWTAccessTokenImplicitGrant genera un token de acceso JWT con el tipo de otorgamiento implícito. Le da automáticamente al token el tipo de otorgamiento implícito; por lo tanto, el elemento <SupportedGrantTypes> no es obligatorio. Debido a que es un JWT, el elemento <Algorithm> es obligatorio. El siguiente ejemplo muestra el uso del algoritmo RS256. Debido a eso, se requiere el elemento <PrivateKey>. Consulta también Usa el tipo de otorgamiento 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>

Las claves privadas de RSA son secretos. Para proteger secretos, se recomienda que el proxy de API los recupere de un mapa de clave-valor (KVM) con alcance de entorno. Consulta también Usa mapas de clave-valor

Verificando

Usa la operación VerifyJWTAccessToken para verificar un token de acceso JWT con la política de OAuthV2. Esta operación es similar a la operación VerifyAccessToken. La diferencia es que VerifyJWTAccessToken se aplica a los tokens en formato JWT, mientras que VerifyAccessToken se aplica a los tokens opacos.

Verifica un token de acceso JWT firmado con un algoritmo HMAC

En el siguiente ejemplo, se muestra cómo configurar la política de OAuthV2 para verificar un token JWT que se firmó con el algoritmo HS512. Cuando se usa la operación VerifyJWTAccessToken con un algoritmo HMAC, la configuración de la política debe usar el elemento <SecretKey> para especificar la clave secreta que se usó a fin de firmar el JWT.

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

Las claves secretas son secretos. Para proteger secretos, se recomienda que el proxy de API los recupere de un mapa de clave-valor (KVM) con alcance de entorno. Consulta también Usa mapas de clave-valor

Verifica un token de acceso JWT firmado con un algoritmo de RSA

En el siguiente ejemplo, se muestra cómo configurar la política de OAuthV2 para verificar un token JWT que se haya firmado con el algoritmo RS512. Cuando se usa la operación VerifyJWTAccessToken con un algoritmo de RSA, la configuración de la política debe usar el elemento <PublicKey> para especificar la clave pública que corresponde a la clave privada que se usó para firmar el JWT.

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

La clave pública no es un secreto. Las buenas opciones para almacenar claves públicas incluyen un conjunto de propiedades con alcance de entorno o un mapa de clave-valor (KVM) con alcance de entorno. Consulta también Accede a los valores de conjuntos de propiedades y Usa mapas clave-valor.

Actualizando

Usa la operación RefreshJWTAccessToken para actualizar un token de acceso JWT. Esta operación es similar a la operación tradicional RefreshAccessToken de la política. Consulta también Actualiza un token de acceso.

Actualiza un token de acceso firmado de HMAC

En el siguiente ejemplo de política, se ilustra cómo configurar la política de OAuthV2 para actualizar un token JWT que se firmó con un algoritmo HMAC. En este caso, se requieren los elementos <SecretKey> y <Algorithm>.

La respuesta de la operación de actualización es similar a la de un token recién generado. La operación de actualización genera un token JWT nuevo con una hora de vencimiento actualizada y mantiene las otras reclamaciones sin cambios.

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

Actualiza un token de acceso JWT firmado con RSA

En el siguiente ejemplo de política, se ilustra cómo configurar la política de OAuthV2 para actualizar un token JWT que se firmó con un algoritmo de RSA. Consulta también Actualiza un token de acceso.

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

Las claves privadas de RSA son secretos. Para proteger secretos, se recomienda que el proxy de API los recupere de un mapa de clave-valor (KVM) con alcance de entorno. Consulta también Usa mapas de clave-valor

Respuesta de token de muestra

Para las operaciones de generación y actualización, el cuerpo de la respuesta es similar al siguiente ejemplo. Ten en cuenta que access_token se representa como un JWT serializado y el token de actualización es un 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" ]
}

Resumen de los elementos obligatorios de la política

En la siguiente tabla, se describen los elementos específicos de JWT que se usan en los ejemplos anteriores:

Elemento	Tipo	Notas
Algoritmo	Valor estático	Especifica el algoritmo que se usa para firmar el token.
SecretKey	Valor al que se hace referencia	Proporciona la clave secreta usada para verificar o firmar tokens con un algoritmo HMAC: HS (256/384/512).
PrivateKey	Valor al que se hace referencia	Proporciona la clave privada usada para generar el token. Úsalo solo cuando el algoritmo sea de RSA: RS (256/384/512).
PublicKey	Valor al que se hace referencia	Proporciona la clave pública que se usa para verificar el token. Úsalo solo cuando el algoritmo sea de RSA: RS (256/384/512).

Elementos de la política no compatibles

Los siguientes elementos de la política de OAuthV2 no son compatibles con las configuraciones de token JWT:

Elemento	Notas
ExternalAuthorization	Cuando se genera un token de acceso JWT, la política de OAuthV2 validará el ID de cliente y el Secret.
ExternalAccessToken	Cuando se genera un token de acceso JWT, Apigee firmará el token y proporcionará los reclamos de forma predeterminada o a través de la configuración de la política. La política es compatible con ExternalRefreshToken, que puede ayudar en los casos de uso de migración.
RFCCompliantRequestResponse	La generación y actualización de los tokens de acceso JWT cumplen con RFC de forma predeterminada.

Notas de uso

• No se admiten los JWT encriptados.
• Además de un token de acceso JWT, la respuesta de la política también incluye un token de actualización opaco para los tipos de otorgamiento que admiten tokens de actualización. Solo los tipos de otorgamiento de contraseña y código de autenticación admiten tokens de actualización.
• Incluye el encabezado de autorización en las solicitudes enviadas al proxy que contiene la política de OAuthV2.
• No puedes revocar un token de acceso JWT. El token JWT generado seguirá siendo válido hasta que venza. Puedes revocar un token de actualización asociado a un token de acceso JWT.
• Apigee debe controlar la generación, la verificación y la actualización de los tokens de acceso. Aunque una aplicación o puerta de enlace externa que tiene acceso a la clave pública o secreta puede decodificar el contenido del JWT, la aplicación externa no tiene información sobre los productos de API que la reclamación client_id identifica y, por lo tanto, no puede desempeñar una función en la autorización del proxy de API.