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.

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.