Preparación para realizar una solicitud autenticada a la API
Después de crear y configurar una cuenta de servicio, tu aplicación debe completar los siguientes pasos:
- Crear un JSON Web Token (JWT), que incluye el encabezado, el payload y la firma;
- Solicitar un token de acceso (
AccessToken) a la plataforma de autenticación OAuth2; - Gestionar la respuesta JSON que devolverá la plataforma de autenticación.
Si la respuesta incluye un token de acceso, puedes usarlo para realizar solicitudes a las APIs de productos de Unico para las que la cuenta de servicio tiene permisos de acceso. (Si la respuesta no incluye un token de acceso, tu JWT y la solicitud del token pueden ser incorrectos, o la cuenta de servicio puede no tener los permisos necesarios para acceder a los recursos solicitados).
El token de acceso generado en la solicitud mencionada anteriormente tiene una validez predeterminada de 3600 segundos, pero esto puede variar según la configuración de seguridad establecida para tu empresa. Cuando el token de acceso expira, tu aplicación debe generar un nuevo JWT, firmarlo y solicitar un nuevo token de acceso a la plataforma de autenticación.
1 — Creación del JWT
Un JWT consta de tres partes: un encabezado, un payload y una firma. El encabezado y el payload son objetos JSON. Estos objetos JSON se serializan en UTF-8 y luego se codifican utilizando la codificación Base64url¹. Esta codificación proporciona resiliencia frente a cambios de codificación en casos de operaciones de codificación repetidas. El encabezado, el payload y la firma se concatenan con un carácter de punto (.).
Un JWT se compone de la siguiente manera:
{Header en Base64url}.{Payload en Base64url}.{Signature en Base64url}
El texto base para la firma se compone de la siguiente manera:
{Header en Base64url}.{Payload en Base64url}
1.1 — Formación del encabezado del JWT
El encabezado consta de dos campos que especifican el algoritmo de firma y el formato del token. Ambos campos son obligatorios, y cada campo tiene un solo valor. Las cuentas de servicio se basan en el algoritmo RSA SHA-256 y el formato de token JWT. Como resultado, la representación JSON del encabezado es la siguiente:
{"alg":"RS256","typ":"JWT"}
La representación en Base64url es la siguiente:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
1.2 — Formación del payload del JWT
El payload del JWT contiene información sobre el JWT, incluidos los permisos solicitados (scopes), la cuenta que solicita acceso, el emisor, el momento en que se emitió el token y la vida útil del token. La mayoría de los campos son obligatorios. Al igual que el encabezado del JWT, el payload es un objeto JSON y se utiliza en la composición de la firma.
1.3 — Campos obligatorios
Los campos obligatorios en el JWT se muestran en la tabla siguiente. Pueden aparecer en cualquier orden dentro del payload.
| Nombre | Descripción |
|---|---|
iss | El identificador de la cuenta de servicio dentro de la empresa. |
scope | Una lista delimitada por espacios o por el signo más (+) de los permisos que la aplicación está solicitando. Si se requieren todos los permisos de la cuenta, usa el símbolo de asterisco (*) para esto. |
aud | La dirección de la plataforma de autenticación que emite los tokens de acceso. Este valor siempre debe ser exactamente https://identityhomolog.acesso.io. Problemas comunes que no funcionan: agregar una barra diagonal final (https://identityhomolog.acesso.io/), o usar HTTP en lugar de HTTPS. |
exp | La hora de expiración del token, especificada en segundos desde las 00:00:00 UTC del 1 de enero de 1970. Este valor tiene una duración máxima de 1 hora después del momento de emisión del JWT. Debe ser numérico — un valor entre comillas como "1524161193" es una cadena y no funcionará; 1524161193 es un número y funcionará. |
iat | El momento de emisión del JWT, especificado en segundos desde las 00:00:00 UTC del 1 de enero de 1970. Este valor debe ser numérico, la misma regla que exp. |
El campo iat debe representar la hora actual en el formato requerido, y el campo exp debe respetar el siguiente cálculo:
exp = iat + 3600
La representación de los campos JSON obligatorios en el payload del JWT es la siguiente:
{
"iss": "service_account_name@tenant_id.iam.acesso.io",
"aud": "https://identityhomolog.acesso.io",
"scope": "*",
"exp": 1626296976,
"iat": 1626293376
}
1.4 — Cálculo de la firma
La especificación **JSON Web Signature (JWS)**² es el mecanismo que guía el cálculo de la firma de un JWT. El contenido de entrada para el cálculo de la firma es el array de bytes del siguiente contenido:
{Header en Base64url}.{Payload en Base64url}
Se debe usar el mismo algoritmo especificado en el encabezado del JWT para calcular la firma. El único algoritmo de firma admitido por la plataforma de autenticación OAuth2 es RSA usando SHA-256, expresado como RS256 en el campo alg del encabezado del JWT.
Firma la representación UTF-8 del contenido de entrada usando SHA256withRSA (también conocido como RSASSA-PKCS1-V1_5-SIGN con el hash SHA-256) con la clave privada que fue creada y asociada a la cuenta de servicio (el archivo .key.pem generado a partir de la solicitud recibida por correo electrónico). El contenido de salida será un array de bytes.
La firma debe luego codificarse en Base64url. El encabezado, el payload y la firma deben concatenarse con un carácter de punto. El resultado es el JWT.
También es posible usar bibliotecas preestablecidas para crear el JWT. Como referencia, puedes encontrar una lista de bibliotecas en el sitio web de jwt.io.
2 — Solicitud de un token de acceso
Después de generar el JWT firmado, una aplicación puede usarlo para solicitar un token de acceso. La solicitud de token de acceso es una solicitud POST HTTPS, y el cuerpo debe estar codificado en URL. La URL se muestra a continuación:
https://identityhomolog.acesso.io/oauth2/token
Los siguientes parámetros son obligatorios en la solicitud POST HTTPS:
| Nombre | Descripción |
|---|---|
grant_type | Usa el siguiente texto, codificado en URL si es necesario: urn:ietf:params:oauth:grant-type:jwt-bearer |
assertion | El JWT, incluida la firma. |
POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<jwt>
3 — Gestión de la respuesta de la plataforma de autenticación
Si el JWT y la solicitud del token de acceso están correctamente formados, y la cuenta de servicio tiene los permisos necesarios, la plataforma de autenticación devolverá un objeto JSON que contiene un token de acceso:
{
"access_token": "<access_token>",
"token_type": "Bearer",
"expires_in": "3600"
}
El token de acceso devuelto en el campo access_token del objeto JSON también es un token JWT que debe usarse en las APIs de los Productos de Unico. Si ocurre un error en la solicitud, verifica el tipo de error en Errores de autenticación.
4 — Duración del token de acceso
La duración del token de acceso es variable. Su duración se especifica en el campo expires_in, que se devuelve junto con el token de acceso. El mismo token de acceso debe usarse durante toda su validez para todas las llamadas a la API de los productos.
No solicites un nuevo token de acceso hasta que la validez del token actual esté por terminar. Recomendamos un margen de 600 segundos (10 minutos):
new Date((token.exp - 600) * 1000)
Donde token.exp es la marca de tiempo de la expiración del token.
Por defecto, el token enviado a la empresa dura 1 hora, pero se puede cambiar. La recomendación es usar siempre expires_in como base y restarle 600s para solicitar un nuevo token.
Ejemplos:
Escenario estándar:
expires_in: 3600 (1h) - Token generado a las 14:42
Solicita un nuevo token solo a las 15:32, es decir, 14:42 + (3600 - 600)
Escenario con duración modificada:
expires_in: 7200 (2h) - Token generado a las 14:42
Solicita un nuevo token solo a las 16:32, es decir, 14:42 + (7200 - 600)
No uses un tiempo fijo para obtener un nuevo token, ya que la duración del token recibido puede ser más corta que el tiempo establecido, lo que podría causar fallos al usar los servicios.
¹ Según la RFC 4648 para la codificación BaseN, el formato Base64url es similar a Base64, excepto que se omite el carácter =, y los caracteres + y / se reemplazan por - y _, respectivamente.
² JSON Web Signature: https://tools.ietf.org/html/rfc7515.