chore: baseline plantilla-proyectos como base del CRM
This commit is contained in:
Aduanasoft
214
docs/MICROSOFT_SSO_SETUP.md
Normal file
214
docs/MICROSOFT_SSO_SETUP.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Configuración de Login con Microsoft (Azure AD)
|
||||
|
||||
Esta guía te ayudará a configurar el login con Microsoft junto con el login tradicional.
|
||||
|
||||
## Parte 1: Configurar Aplicación en Azure AD
|
||||
|
||||
### 1.1 Crear App Registration en Azure Portal
|
||||
|
||||
1. Ve a [Azure Portal](https://portal.azure.com)
|
||||
2. Busca "Azure Active Directory" o "Microsoft Entra ID"
|
||||
3. En el menú lateral, selecciona **App registrations**
|
||||
4. Clic en **New registration**
|
||||
5. Configura:
|
||||
- **Name**: `Anexo76`
|
||||
- **Supported account types**:
|
||||
- "Accounts in any organizational directory (Any Azure AD directory - Multitenant)"
|
||||
- O "Accounts in any organizational directory and personal Microsoft accounts" si quieres permitir cuentas @outlook.com, @hotmail.com
|
||||
- **Redirect URI**:
|
||||
- Platform: `Web`
|
||||
- URI: `http://localhost:8080/realms/master/broker/microsoft/endpoint`
|
||||
- Clic en **Register**
|
||||
|
||||
### 1.2 Obtener Client ID y crear Client Secret
|
||||
|
||||
1. En la página de tu aplicación, copia el **Application (client) ID**
|
||||
2. Ve a **Certificates & secrets** en el menú lateral
|
||||
3. Clic en **New client secret**
|
||||
4. Descripción: `keycloak-integration`
|
||||
5. Expires: Selecciona el tiempo que prefieras (ej: 24 months)
|
||||
6. Clic en **Add**
|
||||
7. **IMPORTANTE**: Copia el **Value** del secret inmediatamente (solo se muestra una vez)
|
||||
|
||||
### 1.3 Configurar API Permissions (Opcional pero recomendado)
|
||||
|
||||
1. Ve a **API permissions**
|
||||
2. Deberías ver `Microsoft Graph` > `User.Read` (Delegated) - esto es suficiente
|
||||
3. Si quieres más información del usuario, agrega:
|
||||
- `email`
|
||||
- `profile`
|
||||
- `openid`
|
||||
|
||||
## Parte 2: Configurar Identity Provider en Keycloak
|
||||
|
||||
### 2.1 Agregar Microsoft como Identity Provider
|
||||
|
||||
1. Abre Keycloak Admin Console: http://localhost:8080
|
||||
2. Login como admin
|
||||
3. Asegúrate de estar en el realm correcto (probablemente `master`)
|
||||
4. En el menú lateral, ve a **Identity providers**
|
||||
5. En el dropdown "Add provider", selecciona **Microsoft**
|
||||
6. Configura:
|
||||
- **Alias**: `microsoft` (o cualquier nombre que prefieras)
|
||||
- **Display name**: `Microsoft` (esto es lo que verá el usuario)
|
||||
- **Enabled**: ON
|
||||
- **Store tokens**: ON (opcional, para poder usar tokens de Microsoft después)
|
||||
- **Stored tokens readable**: OFF
|
||||
- **Trust email**: ON
|
||||
- **First login flow**: `first broker login`
|
||||
- **Client ID**: Pega el Application (client) ID de Azure
|
||||
- **Client Secret**: Pega el client secret que copiaste
|
||||
- Clic en **Save**
|
||||
|
||||
### 2.2 Configurar Mappers (Mapeo de atributos)
|
||||
|
||||
Después de guardar, configura los mappers para traer información del usuario de Microsoft:
|
||||
|
||||
1. En la misma página del Identity Provider, ve a la pestaña **Mappers**
|
||||
2. Clic en **Add mapper**
|
||||
|
||||
**Mapper 1: Email**
|
||||
- Name: `email`
|
||||
- Sync mode override: `inherit`
|
||||
- Mapper type: `Attribute Importer`
|
||||
- Social profile JSON field path: `email`
|
||||
- User attribute name: `email`
|
||||
- Clic en **Save**
|
||||
|
||||
**Mapper 2: First Name**
|
||||
- Name: `firstName`
|
||||
- Mapper type: `Attribute Importer`
|
||||
- Social profile JSON field path: `given_name`
|
||||
- User attribute name: `firstName`
|
||||
- Clic en **Save**
|
||||
|
||||
**Mapper 3: Last Name**
|
||||
- Name: `lastName`
|
||||
- Mapper type: `Attribute Importer`
|
||||
- Social profile JSON field path: `family_name`
|
||||
- User attribute name: `lastName`
|
||||
- Clic en **Save**
|
||||
|
||||
**Mapper 4: Username**
|
||||
- Name: `username`
|
||||
- Mapper type: `Username Template Importer`
|
||||
- Template: `${CLAIM.email}`
|
||||
- Target: `BROKER_USERNAME`
|
||||
- Clic en **Save**
|
||||
|
||||
### 2.3 Configurar Redirect URI en Azure (si es necesario)
|
||||
|
||||
Si usas un realm diferente a `master`, actualiza la Redirect URI en Azure:
|
||||
|
||||
- Formato: `http://localhost:8080/realms/{REALM_NAME}/broker/microsoft/endpoint`
|
||||
- Para producción: `https://tu-dominio.com/realms/{REALM_NAME}/broker/microsoft/endpoint`
|
||||
|
||||
## Parte 3: Actualizar Frontend
|
||||
|
||||
El frontend necesita detectar y mostrar el botón de Microsoft. Keycloak proporciona esta información automáticamente.
|
||||
|
||||
### 3.1 Obtener Identity Providers disponibles
|
||||
|
||||
Tu frontend puede consultar los Identity Providers disponibles:
|
||||
|
||||
**Endpoint de Keycloak:**
|
||||
```
|
||||
GET http://localhost:8080/realms/master/broker-login/identity-providers
|
||||
```
|
||||
|
||||
Esto retorna algo como:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"alias": "microsoft",
|
||||
"displayName": "Microsoft",
|
||||
"providerId": "microsoft",
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 3.2 URL para iniciar flujo de Microsoft
|
||||
|
||||
Para iniciar el login con Microsoft, redirige al usuario a:
|
||||
```
|
||||
http://localhost:8080/realms/master/broker/microsoft/login?client_id=anexo76-frontend&redirect_uri=http://localhost:5173/auth/callback
|
||||
```
|
||||
|
||||
Parámetros:
|
||||
- `client_id`: Tu client ID de frontend en Keycloak (`anexo76-frontend`)
|
||||
- `redirect_uri`: URL a la que Keycloak redirigirá después del login exitoso
|
||||
- `response_type`: `code` (para authorization code flow)
|
||||
- `scope`: `openid profile email`
|
||||
|
||||
### 3.3 Manejar el Callback
|
||||
|
||||
Después del login con Microsoft, Keycloak redirige a tu `redirect_uri` con un `code`:
|
||||
```
|
||||
http://localhost:5173/auth/callback?code=abc123...&session_state=xyz...
|
||||
```
|
||||
|
||||
Tu frontend debe:
|
||||
1. Extraer el `code` del query string
|
||||
2. Intercambiar el `code` por tokens llamando a tu backend
|
||||
3. Tu backend llama a Keycloak para obtener los tokens
|
||||
|
||||
## Parte 4: Testing
|
||||
|
||||
### 4.1 Verificar que Microsoft aparece en la página de login
|
||||
|
||||
Ve a:
|
||||
```
|
||||
http://localhost:8080/realms/master/protocol/openid-connect/auth?client_id=anexo76-frontend&redirect_uri=http://localhost:5173&response_type=code
|
||||
```
|
||||
|
||||
Deberías ver:
|
||||
- Formulario de login tradicional (usuario/contraseña)
|
||||
- Botón o link de "Microsoft" para login social
|
||||
|
||||
### 4.2 Probar el flujo completo
|
||||
|
||||
1. Haz clic en el botón de Microsoft
|
||||
2. Serás redirigido a Microsoft login
|
||||
3. Ingresa credenciales de Microsoft
|
||||
4. Microsoft redirige a Keycloak
|
||||
5. Keycloak crea/actualiza el usuario y redirige a tu app
|
||||
6. Tu app obtiene el token y autentica al usuario
|
||||
|
||||
## Notas Importantes
|
||||
|
||||
### Multi-tenant con Microsoft
|
||||
|
||||
Si tu app es multi-tenant y quieres que cada tenant use su propio Azure AD:
|
||||
1. Crea múltiples Identity Providers en Keycloak (uno por tenant)
|
||||
2. Usa aliases diferentes: `microsoft-tenant1`, `microsoft-tenant2`
|
||||
3. En el frontend, muestra el botón correcto según el tenant
|
||||
|
||||
### Asignación automática de tenant
|
||||
|
||||
Cuando un usuario se loguea por primera vez con Microsoft, puedes:
|
||||
1. Usar un mapper para asignar atributos basados en el dominio del email
|
||||
2. Configurar "Default Tenant" en tu backend si el email es de un dominio conocido
|
||||
3. Solicitar al usuario que seleccione su tenant en el primer login
|
||||
|
||||
### Producción
|
||||
|
||||
Para producción, recuerda:
|
||||
1. Actualizar las Redirect URIs en Azure con tu dominio real
|
||||
2. Usar HTTPS
|
||||
3. Configurar correctamente los Web Origins en Keycloak
|
||||
4. Usar variables de entorno para las configuraciones
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: redirect_uri_mismatch
|
||||
- Verifica que la URI en Azure coincida exactamente con la de Keycloak
|
||||
- Formato: `https://tu-dominio.com/realms/{realm}/broker/{alias}/endpoint`
|
||||
|
||||
### Usuario se crea pero no tiene tenant_id
|
||||
- Configura un mapper en Keycloak para asignar tenant_id automáticamente
|
||||
- O maneja esto en tu backend en el primer login
|
||||
|
||||
### No aparece el botón de Microsoft
|
||||
- Verifica que el Identity Provider esté habilitado en Keycloak
|
||||
- Revisa que el Display Name esté configurado
|
||||
Reference in New Issue
Block a user