plantillas-proyectos/docs/MICROSOFT_SSO_SETUP.md

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
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:

[
  {
    "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