chore: baseline plantilla-proyectos como base del CRM
This commit is contained in:
Aduanasoft
227
docs/KEYCLOAK_SETUP.md
Normal file
227
docs/KEYCLOAK_SETUP.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user