228 lines
6.2 KiB
Markdown
228 lines
6.2 KiB
Markdown
# Guía de Configuración de Keycloak para Anexo76
|
|
|
|
Esta guía te ayudará a configurar Keycloak para usar con Anexo76.
|
|
|
|
# Script auto initialize
|
|
|
|
Te genera toda la configruracion inicial de keycloack que se ve en este documento,
|
|
aparte de esto te genera un primer usuario configurado con su tenant y una company
|
|
|
|
```
|
|
scripts/init_first_time.sh
|
|
```
|
|
|
|
## 1. Acceder a Keycloak Admin Console
|
|
|
|
1. Abrir http://localhost:8080
|
|
2. Hacer clic en "Administration Console"
|
|
3. Login con: `admin` / `admin`
|
|
|
|
## 2. Configurar Cliente Backend
|
|
|
|
### Crear Cliente Backend
|
|
|
|
1. En el menú izquierdo, ir a **Clients**
|
|
2. Clic en **Create client**
|
|
3. Configurar:
|
|
- **Client ID**: `anexo76-backend`
|
|
- **Client Protocol**: `openid-connect`
|
|
- Clic en **Next**
|
|
4. En la siguiente pantalla:
|
|
- **Client authentication**: ON (Confidential)
|
|
- **Authorization**: OFF
|
|
- **Authentication flow**: Marcar solo "Standard flow" y "Direct access grants"
|
|
- Clic en **Next**
|
|
5. En "Login settings":
|
|
- **Root URL**: `http://localhost:8000`
|
|
- **Valid redirect URIs**: `http://localhost:8000/*`
|
|
- **Web origins**: `http://localhost:8000`
|
|
- Clic en **Save**
|
|
|
|
### Obtener Client Secret
|
|
|
|
1. Ir a la pestaña **Credentials**
|
|
2. Copiar el **Client secret**
|
|
3. Agregar al archivo `backend/.env`:
|
|
```
|
|
KEYCLOAK_CLIENT_SECRET=tu-client-secret-aqui
|
|
```
|
|
|
|
## 3. Configurar Cliente Frontend
|
|
|
|
### Crear Cliente Frontend
|
|
|
|
1. En **Clients**, clic en **Create client**
|
|
2. Configurar:
|
|
- **Client ID**: `anexo76-frontend`
|
|
- **Client Protocol**: `openid-connect`
|
|
- Clic en **Next**
|
|
3. En la siguiente pantalla:
|
|
- **Client authentication**: OFF (Public)
|
|
- **Authorization**: OFF
|
|
- **Authentication flow**: Marcar "Standard flow"
|
|
- Clic en **Next**
|
|
4. En "Login settings":
|
|
- **Root URL**: `http://localhost:5173`
|
|
- **Valid redirect URIs**:
|
|
- `http://localhost:5173/*`
|
|
- `http://localhost:3000/*`
|
|
- **Valid post logout redirect URIs**:
|
|
- `http://localhost:5173/*`
|
|
- `http://localhost:3000/*`
|
|
- **Web origins**:
|
|
- `http://localhost:5173`
|
|
- `http://localhost:3000`
|
|
- Clic en **Save**
|
|
|
|
## 4. Crear Usuario de Prueba
|
|
|
|
### Crear Usuario
|
|
|
|
1. En el menú izquierdo, ir a **Users**
|
|
2. Clic en **Add user**
|
|
3. Configurar:
|
|
- **Username**: `demo`
|
|
- **Email**: `demo@empresa-demo.com`
|
|
- **First name**: `Usuario`
|
|
- **Last name**: `Demo`
|
|
- **Email verified**: ON
|
|
- Clic en **Create**
|
|
|
|
### Establecer Contraseña
|
|
|
|
1. Ir a la pestaña **Credentials**
|
|
2. Clic en **Set password**
|
|
3. Configurar:
|
|
- **Password**: `demo123`
|
|
- **Password confirmation**: `demo123`
|
|
- **Temporary**: OFF (para no tener que cambiar la contraseña)
|
|
4. Clic en **Save**
|
|
|
|
### Agregar Atributo tenant_id
|
|
|
|
1. En el mismo usuario, ir a la pestaña **Attributes**
|
|
2. Clic en **Add an attribute**
|
|
3. Configurar:
|
|
- **Key**: `tenant_id`
|
|
- **Value**: `1`
|
|
4. Clic en **Save**
|
|
|
|
### Asignar Roles
|
|
|
|
1. Ir a la pestaña **Role mappings**
|
|
2. En "Available roles", buscar y asignar:
|
|
- `admin` (si existe)
|
|
- `user` (si existe)
|
|
3. Si no existen estos roles, crearlos primero:
|
|
- Ir a **Realm roles** en el menú izquierdo
|
|
- Crear roles: `admin`, `user`, `auditor`, `system`
|
|
- Regresar al usuario y asignar roles
|
|
|
|
## 5. Configurar Mapper para tenant_id (Opcional pero recomendado)
|
|
|
|
Para que el `tenant_id` se incluya automáticamente en el token:
|
|
|
|
1. Ir a **Clients** → `anexo76-backend`
|
|
2. Ir a la pestaña **Client scopes**
|
|
3. Clic en `anexo76-backend-dedicated`
|
|
4. Ir a la pestaña **Mappers**
|
|
5. Clic en **Add mapper** → **By configuration** → **User Attribute**
|
|
6. Configurar:
|
|
- **Name**: `tenant-id-mapper`
|
|
- **User Attribute**: `tenant_id`
|
|
- **Token Claim Name**: `tenant_id`
|
|
- **Claim JSON Type**: `String`
|
|
- **Add to ID token**: ON
|
|
- **Add to access token**: ON
|
|
- **Add to userinfo**: ON
|
|
7. Clic en **Save**
|
|
|
|
Repetir para el cliente `anexo76-frontend` si es necesario.
|
|
|
|
## 6. Verificar Configuración
|
|
|
|
### Probar desde el Frontend
|
|
|
|
1. Abrir http://localhost:5173
|
|
2. Hacer clic en "Iniciar Sesión"
|
|
3. Ingresar credenciales:
|
|
- Usuario: `demo`
|
|
- Contraseña: `demo123`
|
|
4. Deberías ver el dashboard con información del usuario y licencia
|
|
|
|
### Probar desde el API
|
|
|
|
```bash
|
|
# Obtener token
|
|
curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
|
|
-H "Content-Type: application/x-www-form-urlencoded" \
|
|
-d "client_id=anexo76-backend" \
|
|
-d "client_secret=TU_CLIENT_SECRET" \
|
|
-d "username=demo" \
|
|
-d "password=demo123" \
|
|
-d "grant_type=password"
|
|
|
|
# Usar el token para llamar al API
|
|
curl -X GET http://localhost:8000/v1/auth/me \
|
|
-H "Authorization: Bearer TU_ACCESS_TOKEN"
|
|
```
|
|
|
|
## 7. Configuración Adicional (Opcional)
|
|
|
|
### Personalizar Tema de Login
|
|
|
|
1. Ir a **Realm settings** → **Themes**
|
|
2. Seleccionar tema de login deseado
|
|
3. Guardar cambios
|
|
|
|
### Configurar Timeout de Sesión
|
|
|
|
1. Ir a **Realm settings** → **Sessions**
|
|
2. Ajustar:
|
|
- **SSO Session Idle**: Tiempo de inactividad antes de expirar (ej: 30 minutos)
|
|
- **SSO Session Max**: Tiempo máximo de sesión (ej: 10 horas)
|
|
3. Guardar cambios
|
|
|
|
### Habilitar Registro de Usuarios (Opcional)
|
|
|
|
1. Ir a **Realm settings** → **Login**
|
|
2. Activar **User registration**
|
|
3. Guardar cambios
|
|
|
|
## Troubleshooting
|
|
|
|
### Error: "Invalid redirect URI"
|
|
|
|
- Verificar que las URIs en el cliente coincidan exactamente
|
|
- Incluir el protocolo (http:// o https://)
|
|
- Incluir el puerto si es necesario
|
|
|
|
### Error: "Client not found"
|
|
|
|
- Verificar que el Client ID sea exacto
|
|
- Verificar que el realm sea correcto
|
|
|
|
### Token no incluye tenant_id
|
|
|
|
- Verificar que el usuario tenga el atributo configurado
|
|
- Verificar que el mapper esté configurado correctamente
|
|
- Probar obteniendo un nuevo token
|
|
|
|
### Usuario no puede hacer login
|
|
|
|
- Verificar que el usuario esté habilitado (User enabled: ON)
|
|
- Verificar que el email esté verificado (Email verified: ON)
|
|
- Verificar que la contraseña no sea temporal
|
|
|
|
## Próximos Pasos
|
|
|
|
1. Para producción, cambiar el realm de `master` a uno dedicado
|
|
2. Configurar HTTPS/TLS en Keycloak
|
|
3. Configurar backup de la base de datos de Keycloak
|
|
4. Implementar políticas de contraseña más estrictas
|
|
5. Configurar MFA (Multi-Factor Authentication)
|
|
|
|
---
|
|
|
|
**¡Listo!** Tu configuración de Keycloak está completa para desarrollo.
|