Usar tokens OAuth JWT

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

Consulta la documentación de Apigee Edge.

Esta función está disponible tanto para Apigee como para Apigee Hybrid.

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

Introducción

Las operaciones de JWT permiten que la política OAuthV2 genere, verifique y actualice tokens de acceso que cumplan el estándar IETF RFC 9068, que describe cómo emitir tokens de acceso en formato JWT. Los JWTs se suelen usar para compartir reclamaciones o aserciones entre aplicaciones conectadas. Emitir tokens de acceso OAuthV2 en formato JWT es una alternativa a emitir tokens de acceso opacos.

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

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

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

Header

El encabezado especifica una reclamación typ (siempre "at+JWT) y la reclamación alg, que indica el algoritmo usado para firmar el JWT. Apigee admite los algoritmos 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 otras las genera automáticamente el tiempo de ejecución de Apigee. La política admite las siguientes reclamaciones:

Reclamar	Descripción	Proporcionado por
iss	La entidad emisora del token. Este valor se define de la siguiente manera: (http|https)://{domain-name-for-proxy}/{proxy-basePath}. Por ejemplo: https://api.mycompany.com/auth/v2.	Apigee
sub	El ID de cliente o el ID del propietario del recurso (en el caso de los tipos de concesión de contraseña o autorización). Si se proporciona el parámetro appEndUserId en la solicitud, ese valor se utiliza como ID del propietario del recurso. Puede controlar dónde se define este valor mediante el elemento <AppEndUser> de la política OAuthV2.	Desarrollador de APIs
jti	Un ID único, representado como una cadena aleatoria respaldada por UUID para identificar de forma única el token.	Apigee
exp	El tiempo de vencimiento, es decir, el tiempo transcurrido el cual el token se considera no válido. El valor se expresa en tiempo de época (en segundos).	Apigee
iat	La hora de emisión, es decir, la hora en la que se creó el token. El valor se expresa en tiempo de época (en segundos).	Apigee
client_id	Identificador único de la aplicación cliente.	Desarrollador de APIs
scope	El permiso de OAuth asignado al token. Consulta también Usar permisos de OAuth.	Desarrollador de APIs

Firma

La firma se genera mediante el encabezado codificado, la carga útil, la clave secreta o privada y el algoritmo. La firma se usa para asegurarse de que el contenido del token no se ha manipulado.

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

Requisitos previos

En este documento se da por hecho que sabes cómo generar y verificar tokens de acceso OAuthV2 mediante la política OAuthV2. Tanto si usas las operaciones JWT como las tradicionales que crean tokens de cadena opacos, el uso básico de la política OAuthV2 es el mismo. Puedes usar tokens de acceso JWT con todos los tipos de concesión de OAuthV2 admitidos. Consulta también la introducción a OAuth 2.0.

Generando

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

En los siguientes ejemplos se muestra cómo usar estas operaciones en la política OAuthV2. En los ejemplos se usa el tipo de concesión client_credentials, pero puedes usar cualquiera de los tipos de concesión admitidos 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.

Generar un token en formato JWT firmado con un algoritmo HMAC

Especifica el elemento <Algorithm> con uno de los algoritmos HMAC (HS256, HS384 o HS512). También debe proporcionar el <SecretKey>. En el siguiente ejemplo se muestra una política configurada para generar un JWT firmado con el algoritmo HS512, usando 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 secretas. Para proteger los secretos, se recomienda que el proxy de API los recupere de un mapa de valores clave (KVM) con ámbito de entorno. Consulte también Usar mapas de clave-valor.

Generar un token en formato JWT firmado con un algoritmo RSA

Especifica uno de los algoritmos RSA (RS256, RS384 o 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 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 RSA son secretos. Para proteger los secretos, se recomienda que el proxy de API los recupere de un mapa de valores clave (KVM) con ámbito de entorno. Consulte también Usar mapas de clave-valor.

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

La operación GenerateJWTAccessTokenImplicitGrant genera un token de acceso JWT con el tipo de concesión implícito. Asigna automáticamente al token el tipo de concesión implícito, por lo que no es necesario el elemento <SupportedGrantTypes>. Como se trata de un JWT, el elemento <Algorithm> es obligatorio. En el siguiente ejemplo se muestra el uso del algoritmo RS256. Por eso, el elemento <PrivateKey> es obligatorio. Consulte también Usar el tipo de autorización 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 RSA son secretos. Para proteger los secretos, se recomienda que el proxy de API los recupere de un mapa de valores clave (KVM) con ámbito de entorno. Consulte también Usar mapas de clave-valor.

Verificando

Usa la VerifyJWTAccessToken operación para verificar un token de acceso JWT con la política 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.

Verificar un token de acceso JWT firmado con un algoritmo HMAC

En el siguiente ejemplo se muestra cómo configurar la política OAuthV2 para verificar un token JWT firmado 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ó para 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 secretas. Para proteger los secretos, se recomienda que el proxy de API los recupere de un mapa de valores clave (KVM) con ámbito de entorno. Consulte también Usar mapas de clave-valor.

Verificar un token de acceso JWT firmado con un algoritmo RSA

En el ejemplo siguiente se muestra cómo configurar la política OAuthV2 para verificar un token JWT firmado con el algoritmo RS512. Cuando se usa la operación VerifyJWTAccessToken con un algoritmo 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 secreta. Entre las opciones recomendables para almacenar claves públicas se incluyen un conjunto de propiedades de ámbito de entorno o un mapa de pares clave-valor (KVM) de ámbito de entorno. Consulte también Acceder a los valores de un conjunto de propiedades y Usar mapas de clave-valor.

Actualizando

Usa la RefreshJWTAccessToken operación 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 Actualizar un token de acceso.

Actualizar un token de acceso firmado con HMAC

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

La respuesta de la operación de actualización es similar a la respuesta de un token recién generado. La operación de actualización genera un nuevo token JWT con una hora de vencimiento actualizada, pero mantiene las demás reclamaciones.

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

Actualizar un token de acceso JWT firmado con RSA

En el siguiente ejemplo de política se muestra cómo configurar la política OAuthV2 para actualizar un token JWT firmado con un algoritmo RSA. Consulta también Actualizar 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 RSA son secretos. Para proteger los secretos, se recomienda que el proxy de API los recupere de un mapa de valores clave (KVM) con ámbito de entorno. Consulte también Usar mapas de clave-valor.

Respuesta de token de ejemplo

En el caso de las operaciones de generación y actualización, el cuerpo de la respuesta es similar al siguiente ejemplo. Ten en cuenta que el access_token se representa como un JWT serializado y que 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 de la política obligatorios

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 usado para firmar el token.
SecretKey	Valor de referencia	Proporciona la clave secreta que se usa para verificar o firmar tokens con un algoritmo HMAC: HS (256/384/512).
PrivateKey	Valor de referencia	Proporciona la clave privada usada para generar el token. Úsalo solo cuando el algoritmo sea un algoritmo RSA: RS (256/384/512).
PublicKey	Valor de referencia	Proporciona la clave pública que se usa para verificar el token. Úsalo solo cuando el algoritmo sea un algoritmo RSA: RS (256/384/512).

Elementos de política no admitidos

Los siguientes elementos de la política OAuthV2 no se admiten con las configuraciones de tokens JWT:

Elemento	Notas
ExternalAuthorization	Al generar un token de acceso JWT, la política OAuthV2 validará el ID de cliente y el secreto.
ExternalAccessToken	Al generar un token de acceso JWT, Apigee lo firmará y proporcionará las reclamaciones de forma predeterminada o mediante la configuración de la política. La política admite ExternalRefreshToken, lo que puede ayudar en los casos prácticos de migración.
RFCCompliantRequestResponse	La generación y la actualización de tokens de acceso JWT cumplen el RFC de forma predeterminada.

Notas de uso

• No se admiten JWTs cifrados.
• 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 concesión en los que se admiten tokens de actualización. Solo los tipos de concesión de contraseña y código de autorización admiten tokens de actualización.
• Incluye el encabezado Authorization en las solicitudes enviadas al proxy que contiene la política OAuthV2.
• No puedes revocar un token de acceso JWT. El token JWT generado seguirá siendo válido hasta que caduque. Puedes revocar un token de actualización asociado a un token de acceso JWT.
• Apigee debe encargarse de generar, verificar y actualizar los tokens de acceso. Aunque una aplicación o una pasarela externas que tengan acceso a la clave pública o secreta pueden descodificar el contenido del JWT, la aplicación externa no tiene información sobre los productos de API que se identifican mediante la reclamación client_id y, por lo tanto, no puede participar en la autorización del proxy de API.