DioCrafts
12 KiB
12 KiB
Arquitectura de Integración OIDC en OxiCloud
Este documento describe la arquitectura y el flujo de autenticación OpenID Connect (OIDC) en OxiCloud.
Diagrama de Arquitectura
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ PROVEEDOR DE IDENTIDAD │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ │ │ │ │ │ │
│ │ Authentik │ │ Authelia │ │ KeyCloak │ │
│ │ │ │ │ │ │ │
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
│ │ │ │ │
└────────────┼──────────────────────┼──────────────────────┼─────────────┘
│ │ │
│ │ │
│ │ │
│ OIDC │
│ │ │
│ │ │
┌────────────┼──────────────────────┼──────────────────────┼─────────────┐
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ OXICLOUD │ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ │ │ │ │ │
│ │ │ OidcService │◄────►│ AuthService │ │ │
│ │ │ │ │ │ │ │
│ │ └───────┬───────┘ └───────┬───────┘ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌───────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ AuthApplicationService │ │ │
│ │ │ │ │ │
│ │ └───────────────────┬───────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌───────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ Auth Handler │ │ │
│ │ │ │ │ │
│ │ └───────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
▲
│
│ HTTP/HTTPS
│
│
┌────────────────────────────────────────────────────────────────────────┐
│ │
│ NAVEGADOR WEB │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Interfaz de Usuario │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ │ │ │ │ │
│ │ │ Login.html │ │ oidcAuth.js │ │ │
│ │ │ │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────┘
Flujo de Autenticación OIDC
El flujo de autenticación OIDC en OxiCloud sigue el flujo de código de autorización (Authorization Code Flow):
-
Inicio de la Autenticación:
- El usuario hace clic en "Login con [Proveedor]" en la página de inicio de sesión.
- El frontend genera un estado aleatorio para protección CSRF.
- El frontend solicita a OxiCloud una URL de autorización.
-
Redirección al Proveedor de Identidad:
- OxiCloud genera una URL de autorización y la devuelve al frontend.
- El navegador redirige al usuario a la página de inicio de sesión del proveedor de identidad.
-
Autenticación en el Proveedor:
- El usuario se autentica en el proveedor de identidad (con contraseña, 2FA, etc.).
- El proveedor redirige al usuario de vuelta a OxiCloud con un código de autorización.
-
Intercambio del Código de Autorización:
- El frontend de OxiCloud recibe el código de autorización y lo envía al backend.
- OxiCloud intercambia el código por tokens de acceso e ID con el proveedor de identidad.
- OxiCloud verifica el token de ID y extrae la información del usuario.
-
Creación/Recuperación de Usuario:
- OxiCloud busca un usuario existente con el ID externo del proveedor.
- Si no existe y la creación automática está habilitada, se crea un nuevo usuario.
- Si no existe y la creación automática está deshabilitada, se devuelve un error.
-
Generación de Tokens de Sesión:
- OxiCloud genera sus propios tokens de acceso y actualización para el usuario.
- Estos tokens se utilizan para autenticar las solicitudes subsiguientes a la API de OxiCloud.
-
Respuesta al Cliente:
- OxiCloud devuelve los tokens y la información del usuario al frontend.
- El frontend almacena los tokens y redirige al usuario a la página principal.
Componentes Principales
1. OidcService
Este servicio gestiona la comunicación con los proveedores OIDC:
- Descubre los endpoints OIDC de los proveedores
- Genera URLs de autorización
- Intercambia códigos de autorización por tokens
- Verifica tokens y extrae información de usuario
2. AuthApplicationService
Coordina el proceso de autenticación:
- Proporciona una interfaz entre la capa de API y los servicios de dominio
- Gestiona el proceso de creación/recuperación de usuarios
- Coordina la generación de tokens de acceso para OxiCloud
3. Auth Handler
Expone endpoints HTTP para el flujo de autenticación OIDC:
/api/auth/oidc/providers- Lista los proveedores OIDC disponibles/api/auth/oidc/auth- Genera una URL de autorización para un proveedor/api/auth/oidc/callback- Procesa la respuesta del proveedor y completa la autenticación
4. Frontend (oidcAuth.js)
Gestiona la parte del cliente del flujo de autenticación:
- Muestra botones para los proveedores OIDC
- Inicia el flujo de autenticación
- Maneja la redirección de retorno del proveedor
- Procesa y almacena los tokens de sesión
Configuración Multi-Proveedor
OxiCloud permite configurar múltiples proveedores OIDC simultáneamente:
- Configuración Separada: Cada proveedor tiene su propia configuración independiente.
- Selección de Proveedor: Los usuarios pueden elegir con qué proveedor autenticarse.
- Mapeo de Identidades: OxiCloud mapea identidades de diferentes proveedores a usuarios internos.
Seguridad
La implementación OIDC en OxiCloud incluye varias medidas de seguridad:
- Protección CSRF: Utiliza un estado aleatorio para prevenir ataques CSRF.
- Validación de Tokens: Verifica firmas y vigencia de los tokens JWT.
- Código de Autorización: Utiliza el flujo de código de autorización, que es más seguro que el flujo implícito.
- HTTPS: Requiere conexiones HTTPS para todas las comunicaciones OIDC.
- Secretos del Cliente: Los secretos del cliente se almacenan de forma segura y nunca se exponen al frontend.