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