Saltar al contenido principal

Configurar la Autenticación OAuth de Outlook/Microsoft 365

Esta guía te llevará a través de la creación de una aplicación de Microsoft Azure para la autenticación OAuth con Outlook/Microsoft 365. OAuth proporciona una forma más segura de acceder a tu cuenta de Outlook en comparación con la autenticación tradicional por contraseña.

Requisitos Previos​

  • Una cuenta de Microsoft (personal o Microsoft 365/Office 365)
  • Acceso al Portal de Azure
  • La URL de instalación de tu Perfex CRM (para la configuración de URI de redirección)
info

Para organizaciones con Microsoft 365, puede ser necesaria la aprobación del administrador.

Configuración Paso a Paso​

Paso 1: Registrar una Aplicación en el Portal de Azure​

  1. Ve al Portal de Azure
  2. Inicia sesión con tu cuenta de Microsoft
  3. Navega a "Azure Active Directory" (o búscalo)
  4. Haz clic en "App registrations" en el menú izquierdo
  5. Haz clic en "+ New registration"
  6. Completa los detalles de la aplicación:
    • Name: Ingresa un nombre (por ejemplo, "Perfex CRM Mailbox")
    • Supported account types: Elige "Accounts in any organizational directory and personal Microsoft accounts" para máxima compatibilidad
    • Redirect URI:
      • Plataforma: Web
      • URI: https://tu-dominio.com/admin/mailbox/oauth/callback?provider=outlook
      • Reemplaza tu-dominio.com con tu dominio real de Perfex CRM
  7. Haz clic en "Register"

Paso 2: Configurar Permisos de API​

  1. En el registro de tu app, haz clic en "API permissions" en el menú izquierdo
  2. Haz clic en "+ Add a permission"
  3. Selecciona "Microsoft Graph"
  4. Selecciona "Delegated permissions"
  5. Agrega los siguientes permisos:
    • Mail.Read - Leer correo en todos los buzones
    • Mail.ReadWrite - Leer y escribir correo en todos los buzones
    • Mail.Send - Enviar correo como el usuario
    • offline_access - Mantener acceso a los datos a los que se ha otorgado acceso (para actualización de tokens)
  6. Haz clic en "Add permissions"
  7. IMPORTANTE: Haz clic en "Grant admin consent for [Tu Organización]" si ves este botón
aviso

Esto es obligatorio para cuentas de organización. Requiere privilegios de administrador.

Paso 3: Crear Client Secret​

  1. En el registro de tu app, haz clic en "Certificates & secrets" en el menú izquierdo
  2. Haz clic en "+ New client secret"
  3. Ingresa una descripción (por ejemplo, "Perfex Mailbox Secret")
  4. Elige un período de expiración: 24 meses (recomendado para producción)
  5. Haz clic en "Add"
  6. IMPORTANTE: Copia el Value inmediatamente (no podrás verlo de nuevo) - este es tu Client Secret

Paso 4: Obtener el ID de Aplicación (Client ID)​

  1. En el registro de tu app, ve a "Overview"
  2. Copia el Application (client) ID - este es tu Client ID

Paso 5: Configurar URI de Redirección (Verificar)​

  1. En el registro de tu app, haz clic en "Authentication" en el menú izquierdo
  2. En "Redirect URIs", verifica que tu URI de redirección esté listada:
https://tu-dominio.com/admin/mailbox/oauth/callback?provider=outlook
  1. Si no está presente, haz clic en "+ Add a platform" > "Web" y agrégala
  2. En "Implicit grant and hybrid flows", asegúrate de que "Access tokens" esté marcado (si está disponible)
  3. Haz clic en "Save"

Paso 6: Configurar en Perfex CRM​

  1. Ve al área de administración de tu Perfex CRM
  2. Navega a Mailbox > Configuration
  3. Selecciona "OAuth2" como tu método de autenticación
  4. Selecciona "Outlook" como tu proveedor
  5. Ingresa tu Client ID (Application ID de Azure)
  6. Ingresa tu Client Secret (el valor del secreto que copiaste)
  7. Para organizaciones Microsoft 365: Ingresa tu Tenant ID (se encuentra en Azure AD > Overview). Déjalo en blanco para cuentas personales de Microsoft.
  8. Haz clic en "Save Configuration"
  9. Haz clic en el botón "Connect Outlook"
  10. Autoriza la aplicación en la ventana emergente de Microsoft
  11. Deberías ver un mensaje de éxito confirmando la conexión

Limitaciones y Consideraciones Importantes​

Restricciones de Aplicaciones de Microsoft Azure​

Estas limitaciones son impuestas por Microsoft, no por nuestro software.

  1. Requisitos de Consentimiento de Administrador - Las cuentas de organización (Microsoft 365/Office 365) requieren consentimiento del administrador para ciertos permisos. El administrador debe aprobar la app antes de que los usuarios puedan usarla.

  2. Restricciones de Tipo de Cuenta:

    • "Accounts in this organizational directory only" - Solo usuarios en tu organización
    • "Accounts in any organizational directory" - Usuarios de cualquier organización Microsoft 365
    • "Accounts in any organizational directory and personal Microsoft accounts" - Máxima compatibilidad
    • "Personal Microsoft accounts only" - Solo cuentas personales @outlook.com, @hotmail.com

  3. Requisitos de Tenant ID - Las cuentas de organización requieren Tenant ID para autenticación adecuada. Las cuentas personales pueden dejarlo en blanco.

Verificación y Publicación de la App​

  • Las Apps No Verificadas pueden usarse inmediatamente para cuentas personales pero pueden mostrar mensajes de advertencia a los usuarios.
  • Las Apps Verificadas requieren envío a la Microsoft App Store (opcional) y proporcionan mejor experiencia de usuario (sin advertencias).
  • Flujo de Consentimiento de Administrador - Para cuentas de organización, el administrador debe otorgar consentimiento. El administrador ve qué permisos solicita la app.

Actualización de Tokens​

Nuestro módulo maneja automáticamente la actualización de tokens:

  • Tokens de actualización: Obtenidos automáticamente con el permiso offline_access
  • Expiración de tokens: Típicamente 1 hora para tokens de acceso, 90 días para tokens de actualización
  • Actualización automática: Nuestro módulo actualiza los tokens automáticamente antes de la expiración

Multi-Tenant vs Single-Tenant​

  • Multi-Tenant: La app puede ser usada por cualquier cuenta de Microsoft (requiere consentimiento de admin por organización)
  • Single-Tenant: La app solo puede ser usada dentro de tu organización

Notas​

  • La URI de redirección debe coincidir exactamente con lo que configuraste en el Portal de Azure
  • Mantén tu Client Secret seguro - nunca lo compartas públicamente
  • Si cambias tu dominio, actualiza la URI de redirección en el Portal de Azure
  • Para cuentas de organización, asegúrate de que se otorgue el consentimiento de admin
  • El Tenant ID solo es necesario para cuentas de Microsoft 365/Office 365
  • El flujo OAuth es manejado completamente por Microsoft - nuestro módulo solo inicia y recibe el callback

Solución de Problemas​

Error "AADSTS50011: Redirect URI mismatch":

  • Asegúrate de que la URI de redirección en el Portal de Azure coincida exactamente: https://tu-dominio.com/admin/mailbox/oauth/callback?provider=outlook
  • Verifica barras diagonales finales o discrepancias HTTP vs HTTPS
  • Verifica que la URI esté listada bajo el tipo de plataforma "Web"

Error "Admin consent required":

  • Esto es esperado para cuentas de organización (política de Microsoft)
  • Contacta a tu administrador de Microsoft 365 para otorgar consentimiento
  • El admin puede otorgar consentimiento en Portal de Azure > Enterprise applications

Error "Invalid client secret":

  • Los client secrets expiran - crea uno nuevo en el Portal de Azure
  • Asegúrate de haber copiado el "Value" (no el Secret ID)
  • Verifica que el secreto no haya expirado

Error "AADSTS700016: Application not found":

  • Verifica que el Client ID sea correcto
  • Asegúrate de estar usando el Application (client) ID, no el Object ID
  • Verifica que el registro de la app exista en el tenant de Azure AD correcto

Error "Token refresh failed":

  • Asegúrate de que el permiso offline_access esté otorgado
  • Verifica que se haya otorgado el consentimiento de admin (para cuentas de organización)
  • Verifica que el client secret no haya expirado

Recursos Adicionales​

info

Los requisitos de consentimiento de admin, restricciones de tipo de cuenta y políticas de tokens son políticas de seguridad de Microsoft para aplicaciones de Azure. Estas limitaciones no son impuestas por nuestro software.