Flujo de autenticación

El sistema de autenticación de DataInt utiliza un flujo basado en JWT (JSON Web Tokens) que involucra tres componentes principales: el cliente, el API Gateway y el servicio de autenticación. Este documento describe el proceso completo de autenticación, autorización y renovación de tokens.

Actores del sistema

Cliente

Aplicación o servicio que consume la API de DataInt. Debe proporcionar credenciales válidas para obtener acceso a los recursos.

API Gateway

Punto de entrada único que actúa como intermediario entre el cliente y los servicios internos. Se encarga de:

Recibir las solicitudes de autenticación
Validar tokens JWT en cada request
Enrutar solicitudes a los servicios correspondientes

Servicio de autenticación

Servicio especializado en la gestión de autenticación que:

Valida las credenciales del cliente
Genera y gestiona tokens JWT
Mantiene un registro de sesiones activas

Base de datos en memoria

Sistema de almacenamiento temporal que registra los tokens JWT activos y controla las sesiones para garantizar la seguridad.

Flujo de autenticación inicial

1. Solicitud de token

El cliente inicia el proceso enviando una solicitud POST al endpoint /v1/auth/token con sus credenciales como query parameters:

POST /v1/auth/token?client-id=tu_client_id&client-secret=tu_client_secret
Content-Type: application/json

2. Validación de credenciales

El API Gateway reenvía la solicitud al Auth Service, que:

Verifica la validez del client_id y client_secret
Confirma que el cliente tiene permisos para acceder a la API

3. Generación del JWT

Una vez validadas las credenciales, el Auth Service:

Genera un token JWT con información del cliente y tiempo de expiración (15 minutos)
Registra el token en la base de datos en memoria para control de sesiones
Retorna el token al cliente a través del API Gateway

4. Respuesta al cliente

El cliente recibe una respuesta completa que incluye información del usuario, organización, permisos y el JWT:

{
  "name": "Juan",
  "last_name": "Pérez",
  "email": "[email protected]",
  "phone": "+52 555 123 4567",
  "organization": {
    "name": "Empresa Demo",
    "domain_name": "empresa-demo.com",
    "services": [
      {
        "service": "crime-incidence",
        ...
      }
    ],
    "metadata": {
        ...
    }
  },
  "scopes": [...],
  "access_token_expire": "2025-07-30T19:00:00.000Z",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Autorización en llamadas a la API

Inclusión del token

Para cada solicitud a la API, el cliente debe incluir el JWT en el header de autorización:

GET /v1/crime-incidence/state
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Proceso de validación

Interceptación: El API Gateway intercepta la solicitud y extrae el token JWT
Validación: Envía el token al Auth Service para verificación
Verificación en BD: El Auth Service consulta la base de datos en memoria para confirmar que el token sigue siendo válido
Autorización: Si el token es válido, el API Gateway reenvía la solicitud al servicio de destino
Respuesta: El servicio procesa la solicitud y retorna la respuesta al cliente

Renovación de tokens

Cuándo renovar

Los tokens JWT tienen un tiempo de vida de 15 minutos. Es importante renovar el token antes de que expire para mantener el acceso continuo a la API. Se recomienda renovar cuando queden 2-3 minutos del tiempo de vida del token.

Proceso de renovación

Solicitud de renovación: El cliente envía una solicitud GET al endpoint /v1/auth/token con las credenciales como query parameters
Procesamiento: El Auth Service genera un nuevo JWT y actualiza el registro en la base de datos
Nuevo token: El cliente recibe el token renovado y debe usarlo para futuras solicitudes

GET /v1/auth/token?client_id=tu_client_id&client_secret=tu_client_secret

Diagrama del flujo completo

sequenceDiagram
    participant Client as Cliente
    participant "API Gateway" as "API Gateway"
    participant "Auth Service" as "Auth Service"
    participant "In-Memory DB" as "BD en Memoria"
    participant "Target Service" as "Servicio Destino"

    Client -> "API Gateway": POST /v1/auth/token\n(client-id, client-secret como query params)
    "API Gateway" -> "Auth Service": Validar credenciales\n(client-id, client-secret)
    "Auth Service" -> "Auth Service": Generar JWT (15 min)
    "Auth Service" -> "In-Memory DB": Registrar JWT\n(control de sesión)
    "Auth Service" -> "API Gateway": Retornar respuesta completa\n(usuario, org, scopes, JWT)
    "API Gateway" -> Client: Respuesta con JWT y metadatos
    Client -> "API Gateway": Solicitud API\n(ej: GET /v1/crime-incidence/state)
    "API Gateway" -> "Auth Service": Validar JWT
    "Auth Service" -> "In-Memory DB": Verificar validez del token
    "In-Memory DB" -> "Auth Service": Estado del token
    "Auth Service" -> "API Gateway": Resultado de validación
    "API Gateway" -> "Target Service": Reenviar solicitud
    "Target Service" -> "API Gateway": Respuesta
    "API Gateway" -> Client: Respuesta de la API
    Client -> "API Gateway": GET /v1/auth/token\n(client-id, client-secret como query params)
    "API Gateway" -> "Auth Service": Solicitud de renovación
    "Auth Service" -> "In-Memory DB": Actualizar registro de tokens
    "Auth Service" -> "API Gateway": Nuevo JWT
    "API Gateway" -> Client: JWT renovado

Consideraciones de seguridad

Almacenamiento seguro: Los tokens JWT deben almacenarse de forma segura en el cliente
HTTPS obligatorio: Todas las comunicaciones deben realizarse a través de HTTPS
Expiración: Los tokens tienen un tiempo de vida de 15 minutos para minimizar riesgos de seguridad
Rotación: Se recomienda implementar rotación regular de client_secret
Monitoreo: El sistema registra todas las actividades de autenticación para auditoría

Códigos de error comunes

401 Unauthorized: Credenciales inválidas o token expirado
403 Forbidden: Token válido pero sin permisos para el recurso solicitado
429 Too Many Requests: Límite de solicitudes de autenticación excedido