08. Keycloak¶
Keycloak es el sistema centralizado de gestión de identidades y acceso que maneja la autenticación y autorización en todos los componentes de AClimate v3. En lugar de que cada aplicación administre su propia base de datos de usuarios, Keycloak proporciona un punto único donde los usuarios se autentican y reciben tokens que los autorizan a acceder a los diferentes servicios de la plataforma.
Cómo usa AClimate Keycloak¶
La WebAPI es la consumidora principal de la autenticación de Keycloak. Cuando un usuario inicia sesión a través del frontend o del portal admin, proporciona sus credenciales a Keycloak, que devuelve un token de acceso JWT. Este token se incluye en cada solicitud a la WebAPI, y la API valida el token contra las claves públicas de Keycloak antes de procesar cualquier solicitud. La API utiliza un endpoint de validación de tokens que obtiene los certificados de Keycloak y decodifica el JWT para verificar su autenticidad y extraer los roles y permisos del usuario.
El portal admin se integra con Keycloak a través de OAuth, permitiendo a los administradores iniciar sesión con sus credenciales existentes de Keycloak. El portal también proporciona interfaces de gestión de usuarios y roles que se sincronizan con Keycloak, por lo que los administradores pueden crear usuarios, asignar roles y gestionar permisos directamente desde la interfaz admin sin necesidad de acceder a la consola de administración de Keycloak por separado.
El frontend usa la librería keycloak-js en el contexto AuthProvider, que envuelve toda la aplicación en el layout raíz. Cuando los usuarios visitan el frontend, el AuthProvider verifica si tienen una sesión válida de Keycloak. Si no la tienen, son redirigidos a la página de inicio de sesión de Keycloak. Una vez autenticados, el frontend recibe un token que envía con cada solicitud a la API. La configuración del frontend especifica la URL de Keycloak, el nombre del realm y el ID del cliente que identifican la aplicación AClimate ante el servidor Keycloak.
Conceptos clave¶
Al configurar Keycloak para AClimate, se crea un realm que sirve como dominio de seguridad para la plataforma. Dentro de este realm, cada aplicación que necesita autenticación se registra como un cliente. Hay típicamente dos clientes: uno para el frontend y otro para el portal admin. Los roles se definen dentro de cada cliente o a nivel de realm para controlar qué acciones pueden realizar los usuarios. El portal admin usa roles como "admin" y "editor" para restringir el acceso a secciones de configuración específicas.
Configuración¶
Los componentes de la plataforma se configuran con las siguientes variables de entorno que definen cómo se conectan a Keycloak:
- KEYCLOAK_URL: la URL base del servidor Keycloak
- KEYCLOAK_REALM: el nombre del realm para AClimate
- KEYCLOAK_CLIENT_ID: el identificador de cliente utilizado por cada aplicación
- KEYCLOAK_CLIENT_SECRET: el secreto de cliente utilizado por los componentes del lado del servidor
Estas variables tienen valores predeterminados establecidos en los archivos de configuración de la aplicación para el desarrollo local, pero se configuran con los detalles reales del servidor Keycloak en entornos de producción.
Flujo de autenticación¶
Cuando un usuario accede al frontend o al portal admin por primera vez, es redirigido a la página de inicio de sesión de Keycloak donde ingresa sus credenciales. Keycloak valida las credenciales contra su base de datos de usuarios y emite un token de acceso JWT junto con un token de actualización. El token de acceso tiene una vida corta y se incluye en cada solicitud posterior a la API en el encabezado Authorization. Cuando el token de acceso expira, el frontend o el portal admin utilizan el token de actualización para obtener uno nuevo sin requerir que el usuario inicie sesión nuevamente. La WebAPI valida cada solicitud entrante verificando la firma y la expiración del token JWT contra las claves públicas de Keycloak.
Base de Datos de Keycloak¶
Keycloak almacena toda su configuración y datos de usuarios en una base de datos relacional dedicada. Esta base de datos contiene tablas para realms, usuarios con credenciales cifradas, mapeos de roles que asocian usuarios con sus permisos, aplicaciones cliente registradas, registros de eventos de autenticación para auditoría e información de sesiones activas.