plantillas-proyectos/docs/KEYCLOAK_SETUP.md

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

# 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.