Construir

Microsoft Graph OAuth: Autenticar buzones de correo de Outlook y Microsoft 365 (Guía 2026)

Microsoft Graph OAuth 2026

Microsoft Graph OAuthAutenticar buzones de Outlook y Microsoft 365

Una guía completa de OAuth de Microsoft Graph para 2026 para desarrolladores de SaaS. Cubre el registro de aplicaciones de Microsoft Entra, los puntos de conexión de autoridad, los ámbitos de Mail, los permisos delegados vs. de aplicación, el consentimiento del administrador, el código de autorización + PKCE, la rotación de tokens de actualización, los códigos de error AADSTS y cómo Unipile elimina 5 semanas de "plomería" de OAuth en 5 minutos.

Constrúyelo con Unipile Guía de MS Graph
enlazar_cuenta_outlook.py
import solicita # Paso 1: Generar un enlace de autenticación alojado response = requests.Correo electrónico:( "https://apiXXX.unipile.com:XXX /api/v1/hosted/cuentas/enlace", encabezados={"Clave API X": clave_api}, json={ "tipo": "crear", "proveedores": ["MICROSOFT"], "url_de_la_api": tu_dsn, "expiraEn": "31/12/2026 23:59:59" } ) # Paso 2: Redirige al usuario a la URL auth_url = respuesta.json()["url"] # Unipile gestiona todo el flujo de OAuth #, incluyendo Entra, osciloscopios, tokens y actualización
Microsoft OAuth manejado. Buzón listo.
Contexto 2026

Por qué OAuth de Microsoft Graph es innegociable en 2026

Si tu aplicación SaaS lee, envía o sincroniza correos electrónicos de Outlook o Microsoft 365, la autenticación OAuth de Microsoft Graph ya no es opcional. Tres importantes deprecaciones han hecho obsoletas la autenticación básica, los protocolos heredados y las contraseñas de aplicación. OAuth 2.0 a través de la API de Microsoft Graph es la única vía compatible.

Autenticación Básica - Completamente Obsoleta
Microsoft deshabilitó la autenticación básica para Exchange Online en octubre de 2022. Esto afecta a IMAP, POP3, SMTP, EWS, MAPI, OAB, Outlook Anywhere y RPC sobre HTTP. Sin excepciones, sin extensiones del período de gracia restantes.
Desactivado Oct 2022
EWS - Cronología del Atardecer
Exchange Web Services (EWS) está en modo de mantenimiento. Microsoft ha anunciado que no habrá nuevas funcionalidades y recomienda migrar a Microsoft Graph. Aunque aún no se ha cerrado completamente, crear nuevas integraciones en EWS en 2026 será una decisión de deuda técnica de la que se arrepentirá.
Modo de mantenimiento
OAuth 2.0 - El Estándar Necesario
La autenticación OAuth de Microsoft Graph a través de Microsoft Entra ID (anteriormente Azure AD) es el único método de autenticación admitido oficialmente para aplicaciones SaaS de producción que acceden a buzones de Outlook y Microsoft 365 en 2026. Esta guía cubre la implementación completa.
Estándar Requerido
OAuth de Microsoft Graph desbloquea
Leer, enviar y sincronizar buzones de Outlook en nombre de usuarios autenticados
Accede a buzones de correo de Microsoft 365 y Outlook.com personales con un único registro de aplicación.
Tokens de actualización de larga duración con rotación automática (sin reautenticación para usuarios activos)
Control granular de permisos: solicita solo los permisos que tu aplicación realmente necesita
Soporte multi-inquilino: un registro de aplicación sirve para todos los inquilinos del cliente
Cumplimiento de las directivas empresariales de Acceso condicional y MFA
Flujos de OAuth

Los 3 flujos de OAuth que Microsoft admite (y cuál necesita SaaS)

La plataforma de identidad de Microsoft admite varios tipos de concesión de OAuth 2.0. Elegir el incorrecto es una fuente común de tiempo de ingeniería desperdiciado. Aquí está el desglose para aplicaciones SaaS que acceden al correo electrónico en nombre de sus usuarios.

Recomendado para SaaS
Código de Autorización + PKCE
RFC 6749 Sección 4.1 + RFC 7636
El usuario es redirigido a la página de inicio de sesión de Microsoft, se autentica y otorga consentimiento. Tu aplicación intercambia el código de autorización devuelto por tokens de acceso y actualización. PKCE (Proof Key for Code Exchange) previene los ataques de interceptación de códigos y es obligatorio para clientes públicos y recomendado para todos los clientes en 2026.
Úselo para aplicaciones SaaS que acceden a los buzones de correo de los usuarios
Credenciales del cliente
Sección 4.4 (solo aplicaciones) de OAuth 2.0
No interacción del usuario. Tu aplicación se autentica como sí misma usando un ID de cliente y secreto (o certificado). Requiere permisos de aplicación (no delegados), lo que significa que un administrador del inquilino debe otorgar consentimiento para acceder a todos los buzones de la organización. Sin pantalla de consentimiento del usuario.
Solo para herramientas internas con acceso otorgado por el administrador
Flujo de código del dispositivo
Concesión de autorización de dispositivo OAuth 2.0
Diseñado para dispositivos sin navegador (CLIs, IoT, televisores inteligentes). El usuario visita una URL en otro dispositivo para autenticarse. No es relevante para aplicaciones web SaaS donde es posible una redirección.
No aplicable a aplicaciones web SaaS estándar
Comienza a construir tu flujo de OAuth de Microsoft
Unipile - Registro de aplicaciones de Microsoft Entra
Configuración paso a paso

Registro de Aplicación de Microsoft Entra: 7 Pasos

Antes de que tu aplicación pueda solicitar tokens OAuth, necesitas una aplicación registrada en Microsoft Entra ID (anteriormente Azure Active Directory). Aquí están los pasos exactos, incluyendo qué valores de campo son importantes y cuáles son cosméticos.

1
Crear un registro de aplicación en el Portal de Azure
Navegar a portal.azure.com, ir a Microsoft Entra ID (buscar en la barra superior), luego Registros de aplicaciones, luego haz clic + Nuevo registro. Ver el Documentación completa de Microsoft OAuth para contexto adicional.
Nombre
El nombre de tu aplicación. Este es el nombre que los usuarios ven en la pantalla de consentimiento de Microsoft. Usa el nombre de tu producto, no un identificador técnico.
Tipos de cuenta admitidos
Para un SaaS multi-inquilino que atiende tanto a usuarios empresariales como personales: seleccionar Cuentas en cualquier directorio organizacional (cualquier inquilino de Microsoft Entra ID - multiinquilino) y cuentas personales de Microsoft. Esto corresponde a la /común endpoint de autoridad.
Consejo: Si solo admite cuentas de Microsoft 365 para empresas (no Outlook.com personal), seleccione únicamente "Multitenant". Esto utiliza el /organizaciones autoridad y reduce tu superficie de consentimiento. Más sobre los puntos finales de autoridad en la sección 4.
2
Configurar URIs de redireccionamiento
Después del registro, ve a Autenticación en el panel izquierdo. Añadir una plataforma: seleccionar Web. Agrega tus URI de redireccionamiento, la URL a la que Microsoft redirigirá al usuario con el código de autorización.
Tipo de plataforma
Web para aplicaciones del lado del servidor. Usar Aplicación de página única (SPA) para flujos del lado del cliente (habilita automáticamente PKCE).
URI de redirección
Debe ser HTTPS en producción. Ejemplo: https://app.yourproduct.com/auth/microsoft/callback. Se requiere una coincidencia exacta, cualquier desviación genera AADSTS50011.
URL de cierre de sesión (opcional)
Microsoft llamará a esta URL cuando el usuario cierre sesión en cualquier aplicación de su inquilino. Opcional para integraciones solo de correo electrónico.
Error común: Se permiten las URI de localhost durante el desarrollo (http://localhost:3000/callback) pero las URIs de producción deben usar HTTPS. Registre ambos por separado.
3
Agregar permisos de la API de Microsoft Graph
Ir a Permisos de API. Hacer clic + Agregar un permiso, seleccionar Microsoft Graph, entonces Permisos delegados. Añade los ámbitos que tu aplicación necesita.
Mínimo para leer
Mail.Read, acceso_sin_conexión, openid, perfil
Para leer + enviar
Mail.ReadWrite, Mail.Enviar, acceso_sin_conexión, openid, perfil
acceso_sin_conexión
Crítico. Sin este ámbito, Microsoft no emite un token de actualización. Tus usuarios necesitarán volver a autenticarse cada 60-90 minutos.
Nota: Agregar permisos aquí no los otorga, declara tu intención. El usuario consiente cuando completa el flujo de OAuth. Se requiere el consentimiento del administrador para algunos ámbitos de mayor privilegio (ver sección 7).
4
Generar un secreto de cliente
Ir a Certificados y secretos. Hacer clic + Nuevo secreto de cliente. Establecer una descripción y una fecha de caducidad.
Recomendación de caducidad
730 días (24 meses) es el máximo. Establezca un recordatorio de calendario 60 días antes de que expire, la rotación de un secreto expirado causa fallas de autenticación inmediatas en todos los usuarios.
Copia el valor inmediatamente
El valor secreto solo se muestra una vez. Guárdalo en tu gestor de secretos (por ejemplo, AWS Secrets Manager, HashiCorp Vault, Azure Key Vault). Nunca se volverá a mostrar después de que abandones esta página.
Alternativa recomendada: Para producción, usa un certificado en lugar de un secreto de cliente. Los certificados son más seguros (clave asimétrica), nunca caducan por accidente y son preferidos por Microsoft para aplicaciones de nivel empresarial.
5
Copia tu ID de cliente e ID de inquilino
Desde el Visión general página de registro de tu aplicación, copia dos valores que necesitarás en cada solicitud OAuth:
ID de cliente de aplicación
Un UUID que identifica de forma única el registro de su aplicación. Se utiliza como el client_id parámetro en todas las solicitudes de autenticación.
ID del directorio (inquilino)
El ID de inquilino de su organización. Se usa en las URL de autoridad de inquilino único. Para aplicaciones de inquilino múltiple, usted usa /común en su lugar, pero mantenga este valor para las URL de consentimiento del administrador.
6
Habilitar tokens de ID (opcional pero recomendado)
De vuelta en Autenticación, bajo Flujos implícito e híbrido, puedes habilitar Tokens de ID. Esto te permite recibir un JWT con declaraciones de identidad del usuario (nombre, correo electrónico, ID de inquilino) junto con el token de acceso, útil para flujos de incorporación donde deseas pre-llenar los datos del perfil del usuario.
Orientación 2026: Para flujos auth-code puros + PKCE, los tokens de identificación se devuelven a través del punto final del token, no de la concesión implícita. No es necesario habilitar la concesión implícita. Habilítela solo si tiene una SPA heredada que no pueda usar PKCE.
7
Opcional: Verifica tu dominio de editor
En Marca y propiedades, establezca el dominio de su editor en el dominio de su producto. Esto reemplaza la etiqueta "sin verificar" en la pantalla de consentimiento con el nombre de su dominio. Para aplicaciones multiinquilinas dirigidas a clientes empresariales, completar la verificación de Microsoft Partner Network y convertirse en un "editor verificado" elimina la advertencia prominente "Esta aplicación no se usa comúnmente".
Dominio del editor
Un dominio que posees y has verificado mediante un registro TXT o mediante el flujo de validación de dominios de App Service.
Editor verificado
Requiere una ID de Microsoft Partner Network (MPN) vinculada a una identidad comercial verificada. Tarda de 1 a 5 días hábiles. Mejora significativamente la conversión de clientes empresariales en las pantallas de consentimiento.
Omite la configuración: construye con Unipile en su lugar
Puntos de conexión de autoridad

Elegir el punto de conexión de autoridad de Microsoft adecuado

La URL de autoridad que utilizas en tus solicitudes OAuth determina qué tipos de cuentas de Microsoft pueden autenticarse y qué tokens recibes. Si la configuras incorrectamente, se producirán errores silenciosos que impedirán que algunos usuarios se autentiquen por completo.

URL de autoridad Acepta Caso práctico Advertencias
/comúnLa mayoría de SaaS Tanto las cuentas de Microsoft Entra (trabajo/escuela) como las cuentas personales de Microsoft (Outlook.com, Hotmail, Live) SaaS multi-inquilino que da servicio a todos los usuarios de Microsoft. Un único punto de conexión controla a toda su base de usuarios. Los tokens son emitidos por el tenant principal de cada usuario, no por el tuyo. La validación de tokens debe usar un emisor específico del tenant o aceptar múltiples emisores. No se pueden aplicar directivas de Acceso Condicional.
/organizaciones Cuentas de Microsoft Entra ID solamente (trabajo/escuela). No se admiten cuentas personales de Microsoft. SaaS B2B dirigido solo a clientes empresariales, nunca a usuarios de consumidor de Outlook.com. Los usuarios con cuentas personales de Microsoft recibirán un error. Validación de tokens más simple (patrón de emisor único aceptable).
consumidores Solo cuentas personales de Microsoft (Outlook.com, Hotmail, Live). Aplicaciones de consumo dirigidas a bandejas de entrada personales. Raro en SaaS B2B. Las cuentas de Microsoft 365 para empresas son rechazadas. No es útil para SaaS que atiende a usuarios de negocios.
/{id-de-inquilino} Cuentas en un inquilino específico de Microsoft Entra solamente. Herramientas internas de un solo inquilino (la aplicación de tu propia empresa). Flujos de consentimiento de administrador dirigidos a un inquilino específico. También se usa en el patrón de URL de redirección de consentimiento de administrador. Los usuarios de inquilinos alternativos son rechazados. Solo apropiado para aplicaciones internas o cuando se bloquea deliberadamente a un inquilino de un cliente.
/común La mayoría de SaaS
Acepta Tanto las cuentas de Microsoft Entra (trabajo/escuela) como las cuentas personales de Microsoft (Outlook.com, Hotmail, Live)
Caso de uso SaaS multi-inquilino que da servicio a todos los usuarios de Microsoft. Un único punto de conexión controla a toda su base de usuarios.
Advertencias Los tokens son emitidos por el tenant principal de cada usuario, no por el tuyo. La validación de tokens debe usar un emisor específico del tenant o aceptar múltiples emisores. No se pueden aplicar directivas de Acceso Condicional.
/organizaciones
Acepta Cuentas de Microsoft Entra ID solamente (trabajo/escuela). No se admiten cuentas personales de Microsoft.
Caso de uso SaaS B2B dirigido solo a clientes empresariales, nunca a usuarios de consumidor de Outlook.com.
Advertencias Los usuarios con cuentas personales de Microsoft recibirán un error. Validación de tokens más simple (patrón de emisor único aceptable).
consumidores
Acepta Solo cuentas personales de Microsoft (Outlook.com, Hotmail, Live).
Caso de uso Aplicaciones de consumo dirigidas a bandejas de entrada personales. Raro en SaaS B2B.
Advertencias Las cuentas de Microsoft 365 para empresas son rechazadas. No es útil para SaaS que atiende a usuarios de negocios.
/{id-de-inquilino}
Acepta Cuentas en un inquilino específico de Microsoft Entra solamente.
Caso de uso Herramientas internas de un solo inquilino (la aplicación de tu propia empresa). Flujos de consentimiento de administrador dirigidos a un inquilino específico. También se usa en el patrón de URL de redirección de consentimiento de administrador.
Advertencias Los usuarios de inquilinos alternativos son rechazados. Solo apropiado para aplicaciones internas o cuando se bloquea deliberadamente a un inquilino de un cliente.
Nota de validación de token para /common: Cuando usas el /común endpoint, el iss (emisor) la reclamación en el JWT será https://login.microsoftonline.com/{tenantId}/v2.0 dónde {tenantId} varía por usuario. Configura tu biblioteca de validación JWT para aceptar cualquier emisor que coincida con https://login.microsoftonline.com/{tenantId}/v2.0 en lugar de una cadena de emisor fija.
Alcances de correo

Ámbitos de correo de Microsoft Graph: Desglose granular

Microsoft Graph utiliza ámbitos de permisos para controlar lo que tu aplicación puede hacer. Solicitar demasiados ámbitos aumenta la fricción en la pantalla de consentimiento y reduce la conversión. Solicitar muy pocos provoca errores en tiempo de ejecución. Aquí tienes todos los ámbitos de correo que necesitas conocer.

Alcance Tipo Qué permite ¿Consentimiento de administrador?
Mail.Read Delegado Leer todos los mensajes en el buzón del usuario autenticado. Incluye encabezados, cuerpo, archivos adjuntos. Solo lectura, no se puede modificar ni enviar. Usuario
Mail.ReadBasic Delegado Leer propiedades limitadas del mensaje: asunto, remitente, destinatarios, fecha. No se puede leer el cuerpo del mensaje ni los archivos adjuntos. Útil para listar la bandeja de entrada de forma ligera sin acceso completo al contenido. Usuario
Mail.ReadWrite Delegado Leer y modificar todos los mensajes. Incluye crear, actualizar, eliminar mensajes y carpetas. Superconjunto de Mail.Read - no solicites ambos. Usuario
Mail.Enviar Delegado Envía correos electrónicos como el usuario autenticado. Requerido incluso si también tienes Mail.ReadWrite: el envío es un permiso separado en Microsoft Graph. Usuario
Correo.Leer.Compartido Delegado Leer correo en buzones compartidos o en los buzones de otros usuarios a los que el usuario autenticado ha tenido acceso. No para leer el buzón del propio usuario. Usuario
Mail.ReadWrite.Shared Delegado Leer y modificar correos electrónicos en buzones compartidos a los que el usuario tiene acceso. Usuario
Mail.Enviar.Compartido Delegado Enviar correo electrónico desde buzones compartidos o "enviar en nombre de" otro usuario (si dicho usuario ha concedido acceso). Usuario
acceso_sin_conexión Delegado Instruye a Microsoft a emitir un token de actualización. Sin él, solo recibes un token de acceso de corta duración sin forma de renovarlo. Siempre requerido para aplicaciones SaaS. Usuario
openid Delegado Devuelve un token de identificación con la identidad básica del usuario. Requerido si quieres saber quién se autenticó sin hacer una llamada separada a la API /me. Usuario
perfil Delegado Agrega las reclamaciones `name` y `preferred_username` al token de ID. Normalmente se incluye con `openid`. Usuario
Mail.Read (Aplicación) Aplicación Leer todo el correo de todos los buzones del tenant sin interacción del usuario. Usado por servicios de daemon. Requiere el consentimiento del administrador del tenant. Se necesita administrador
Mail.ReadWrite (Aplicación) Aplicación Leer y escribir todo el correo en todos los buzones de inquilinos. Permiso muy amplio. Solo para herramientas internas confiables con la aprobación explícita del administrador del inquilino. Se necesita administrador
Mail.Read Delegado
Leer todos los mensajes en el buzón del usuario autenticado. Incluye encabezados, cuerpo, archivos adjuntos. Solo lectura, no se puede modificar ni enviar.
Consentimiento del usuario
Mail.ReadBasic Delegado
Leer propiedades limitadas del mensaje: asunto, remitente, destinatarios, fecha. No se puede leer el cuerpo del mensaje ni los archivos adjuntos. Útil para listar la bandeja de entrada de forma ligera sin acceso completo al contenido.
Consentimiento del usuario
Mail.ReadWrite Delegado
Leer y modificar todos los mensajes. Incluye crear, actualizar, eliminar mensajes y carpetas. Superconjunto de Mail.Read - no solicites ambos.
Consentimiento del usuario
Mail.Enviar Delegado
Envía correos electrónicos como el usuario autenticado. Requerido incluso si también tienes Mail.ReadWrite: el envío es un permiso separado en Microsoft Graph.
Consentimiento del usuario
Correo.Leer.Compartido Delegado
Leer correo en buzones compartidos o en los buzones de otros usuarios a los que el usuario autenticado ha tenido acceso. No para leer el buzón del propio usuario.
Consentimiento del usuario
Mail.ReadWrite.Shared Delegado
Leer y modificar correos electrónicos en buzones compartidos a los que el usuario tiene acceso.
Consentimiento del usuario
Mail.Enviar.Compartido Delegado
Enviar correo electrónico desde buzones compartidos o "enviar en nombre de" otro usuario (si dicho usuario ha concedido acceso).
Consentimiento del usuario
acceso_sin_conexión Delegado
Instruye a Microsoft a emitir un token de actualización. Sin él, solo recibes un token de acceso de corta duración sin forma de renovarlo. Siempre requerido para aplicaciones SaaS.
Consentimiento del usuario
openid Delegado
Devuelve un token de identificación con la identidad básica del usuario. Requerido si quieres saber quién se autenticó sin hacer una llamada separada a la API /me.
Consentimiento del usuario
perfil Delegado
Agrega las reclamaciones `name` y `preferred_username` al token de ID. Normalmente se incluye con `openid`.
Consentimiento del usuario
Mail.Read (Aplicación) Aplicación
Leer todo el correo de todos los buzones del tenant sin interacción del usuario. Usado por servicios de daemon. Requiere el consentimiento del administrador del tenant.
Se necesita administrador
Mail.ReadWrite (Aplicación) Aplicación
Leer y escribir todo el correo en todos los buzones de inquilinos. Permiso muy amplio. Solo para herramientas internas confiables con la aprobación explícita del administrador del inquilino.
Se necesita administrador
Alcance mínimo establecido: lector de bandeja de entrada
scope=Mail.Readoffline_accessopenidprofile
Leer mensajes, renovar tokens, identidad de usuario. Sin capacidad de escribir ni enviar.
Alcance estándar establecido: integración completa de correo electrónico
scope=Mail.ReadWriteMail.Sendoffline_accessopenidprofile
Leer, escribir, enviar. El conjunto más común para integraciones de herramientas de CRM y ventas.
Ver la guía completa de la API de correo electrónico
Modelo de permisos

Permisos delegados vs. permisos de aplicación: cuándo aplicar cada uno

Microsoft Graph utiliza dos modelos de permisos fundamentalmente diferentes. La mayoría de los desarrolladores de SaaS eligen por defecto el incorrecto, lo que da lugar a requisitos innecesarios de consentimiento del administrador y a una experiencia de usuario deficiente. Aquí se explica exactamente cuándo usar cada uno.

Permisos delegados
Actuar en nombre del usuario que ha iniciado sesión
La aplicación accede a Microsoft Graph utilizando la identidad del usuario autenticado. La aplicación solo puede hacer lo que el propio usuario podría hacer. Si el usuario no puede leer una carpeta, tu aplicación tampoco podrá.
El usuario consiente durante el flujo de OAuth; no se requiere administrador para ámbitos estándar
El acceso se limita al buzón de cada usuario individual
Los usuarios pueden revocar el acceso en cualquier momento desde la configuración de su cuenta de Microsoft
Respeta los permisos a nivel de usuario, las asignaciones de roles y las políticas de acceso al buzón
Úselo para aplicaciones SaaS donde cada usuario se autentica individualmente
Permisos de la aplicación
Actuar como la aplicación misma
La aplicación accede a Microsoft Graph sin que ningún usuario esté presente. Se utiliza para servicios en segundo plano, demonios y flujos de trabajo automatizados. La aplicación se autentica utilizando sus propias credenciales (flujo de credenciales de cliente).
Requiere consentimiento del administrador del inquilino: una barrera importante para los usuarios externos
El acceso es a nivel de inquilino; se pueden leer TODOS los buzones una vez que el administrador da su consentimiento.
No se requiere inicio de sesión interactivo del usuario - funciona para automatización "headless"
Adecuado para herramientas internas de TI donde el administrador de su organización controla la implementación
Solo para herramientas internas donde el administrador de su organización otorga acceso completo al inquilino
La Regla de Decisión de SaaS
Si estás construyendo un producto utilizado por clientes externos quienes inician sesión individualmente, usen Permisos delegados. Cada cliente se autentica con su propia cuenta de Microsoft, da su consentimiento a los ámbitos de tu aplicación y tu aplicación opera en nombre de ese usuario autenticado. Los permisos de aplicación requieren que un administrador del tenant pre-apruebe tu aplicación para toda su organización, un paso que mata las conversiones en un embudo de SaaS de autoservicio. La única excepción es si estás creando una herramienta empresarial interna implementada por tu propio equipo de TI en tu propio tenant.
Guía completa

Código de autorización + PKCE: Ejemplos de Curl paso a paso

Aquí está el flujo completo de código de autorización OAuth 2.0 de Microsoft Graph con PKCE, desde la generación del verificador de código hasta el intercambio de tokens. Estos son ejemplos de calidad de producción que puedes adaptar directamente a tu pila.

Paso 1 de 4 - Generar parámetros PKCE
generar code_verifier y code_challenge
PKCE funciona generando un secreto aleatorio (code_verifier), luego un hash SHA-256 de este (code_challenge). Envías el challenge en el paso 2 y el verifier en el paso 4. Microsoft verifica que coincidan, evitando la interceptación de código.
pkce_generate.py
import os, base64, hashlib # 1. Generar code_verifier (43-128 caracteres, codificación Base64 compatible con URL) verificador_de_código = base64.urlsafe_b64encode( os.urandom(32) ).descifrar('utf-8').eliminar espacios en blanco al final('=') # 2. Generar code_challenge = BASE64URL(SHA256(code_verifier)) desafío_de_código = base64.urlsafe_b64encode( hashlib.sha256verificador_de_código.codificar('utf-8')).digestivo() ).descifrar('utf-8').eliminar espacios en blanco al final('=') # Guarda el código de verificación en la sesión; lo necesitarás en el paso 4 # Enviar el código de desafío en la URL de autorización
Paso 2 de 4 - Solicitud de autorización
Construye la URL de /authorize y redirige al usuario
Redirige el navegador del usuario al endpoint de autorización de Microsoft. El usuario ve la página de inicio de sesión de Microsoft, se autentica y consiente los ámbitos de tu aplicación. Microsoft luego redirige de vuelta a tu `redirect_uri` con un código de autorización.
client_id
ID de tu aplicación (cliente) del registro de aplicaciones de Entra
tipo_de_respuesta
código - solicita un código de autorización
uri_redireccionamiento
Debe coincidir exactamente con un URI registrado en su aplicación de Entra. Codificado en URL.
alcance
Lista separada por espacios. Incluir siempre acceso_sin_conexión para tokens de actualización.
estado
Valor opaco que generas. Se devuelve sin cambios en la devolución de llamada. Úsalo para prevenir CSRF y restaurar el estado de la interfaz de usuario.
desafío_de_código
El valor BASE64URL(SHA256(code_verifier)) del paso 1.
método_desafío_de_código
S256 - usa siempre SHA-256, nunca en texto plano
authorize_url.sh
# Generar la URL de autorización (formato para facilitar la lectura) AUTH_URL="https://login.microsoftonline.com/common/oauth2/v2.0/authorize ?client_id=TU_CLIENT_ID &tipo_de_respuesta=código &redirect;_uri=https://3aapp.com/3aauth/3ams/3acb &scope;=Mail.ReadWriteMail.Sendoffline_access &estado=VALOR_ALEATORIO_DEL_ESTADO &code_challenge=TU_CODE_CHALLENGE &code_challenge_method=S256" # Redirigir al usuario a $AUTH_URL #: Microsoft se encarga del inicio de sesión, la autenticación multifactorial y la pantalla de consentimiento # En caso de éxito: redirect_uri?code=AUTH_CODE&state;=...
Paso 3 de 4 - Manejar la devolución de llamada
Recibe el código de autorización en tu redirect_uri
Microsoft redirige a tu redirect_uri con un código parámetro de consulta. Valide el estado El parámetro coincide con lo que enviaste. El código caduca en 10 minutos - cámbialo inmediatamente en el paso 4.
Paso 4 de 4 - Intercambio de tokens
Canjea el código de autorización por tokens de acceso + actualización
POSTEA al punto final del token con el código y tu code_verifier. Microsoft devuelve un token de acceso (válido por ~60-90 minutos) y un token de actualización (de larga duración). Almacena ambos de forma segura.
token_exchange.sh
Código de autorización de # Exchange para tokens curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=TU_CLIENT_ID" \ -d "client_secret=TU_CLIENT_SECRET" \ -d "tipo_concesión=código_autorización" \ -d "código=AUTH_CODE_FROM_CALLBACK" \ -d "redirect_uri=https://app.com/auth/ms/cb" \ -d "code_verifier=TU_VERIFICADOR_DE_CÓDIGO" \ -d "scope=Mail.ReadWrite Mail.Send offline_access"
Devoluciones: access_token, refresh_token, expires_in, scope
token_respuesta.json
{ "tipo_token": "Portador", "alcance": "Mail.ReadWrite Mail.Send offline_access", "expira_en": 3600, "token_de_acceso": "eyJ0eXAiOiJKV1Qi...", "token de actualización": "0.ARoAi7W...", "id_token": "eyJ0eXAi..." }
Ciclo de vida del token

Manejo de Tokens de Actualización: Rotación, Expiración y Acceso Condicional

Los tokens de actualización de Microsoft Graph son de larga duración pero no permanentes. Varias condiciones pueden invalidarlos de forma silenciosa. Comprender estos casos extremos es lo que diferencia una integración de Microsoft OAuth de calidad de producción de una que falla aleatoriamente para los usuarios empresariales.

expiración por inactividad de 90 días
Los tokens de actualización de Microsoft caducan después de 90 días de inactividad. Si un usuario no utiliza tu aplicación durante 90 días, su token de actualización se vuelve inválido y debe volver a autenticarse. No hay forma de extender esto sin la interacción del usuario. Soportar siempre concesión_inválida manejar errores con gracia y solicitar reautenticación.
Cambios en la política de acceso condicional
Los inquilinos de empresa utilizan directivas de acceso condicional (requisitos de MFA, cumplimiento del dispositivo, restricciones de ubicación). Si una directiva cambia después de que un usuario se autenticó, su token de actualización puede invalidarse en el próximo uso. Esta es una decisión del lado del cliente; no puedes controlarla ni predecirla. Propaga siempre los errores de autenticación a los usuarios con una indicación clara para volver a autenticarse.
Rotación de tokens de actualización
Cuando usas un token de actualización para obtener un nuevo token de acceso, Microsoft puede emitir un nuevo token de actualización. Guarda siempre el nuevo token de actualización de la respuesta, reemplazando al anterior. Si sigues usando el token de actualización anterior después de que se haya rotado, eventualmente encontrarás un concesión_inválida error.
Revocación del administrador
Un administrador de inquilinos puede revocar todos los tokens de actualización para un usuario o para toda la organización en cualquier momento (por ejemplo, cuando un empleado se va o durante un incidente de seguridad). Tu aplicación recibe concesión_inválida. Este es el comportamiento esperado; manéjelo marcando la cuenta vinculada como que necesita reautorización.
refresh_token.sh
# Actualizar el token de acceso utilizando el token de actualización almacenado curl -X POST "https://login.microsoftonline.com/common/oauth2/v2.0/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=TU_CLIENT_ID" \ -d "client_secret=TU_CLIENT_SECRET" \ -d "grant_type=refresh_token" \ -d "refrescar_token=TOKEN_DE_ACTUALIZACIÓN_ALMACENADO" \ -d "scope=Mail.ReadWrite Mail.Send offline_access" #: comprueba SIEMPRE si hay un nuevo refresh_token en la respuesta. # Si está presente, sustitúyalo inmediatamente. # Si aparece el error «invalid_grant», solicita al usuario que vuelva a autenticarse.
Solución de problemas

Errores comunes de AADSTS decodificados

Los errores de OAuth de Microsoft Graph siguen un patrón de código de error AADSTS consistente. Estos son los más comunes que encontrará durante el desarrollo y la producción, con causas exactas y soluciones.

Código de error Qué significa Causa raíz y solución
AADSTS65001 No se ha concedido el consentimiento para uno o más de los ámbitos solicitados El usuario no ha consentido los ámbitos de tu aplicación o un administrador de inquilino ha bloqueado el consentimiento del usuario para tu aplicación. Solución: Incluir consentimiento en tu URL de autorización para forzar una pantalla de consentimiento, o envía la URL de consentimiento del administrador al administrador del inquilino.
Agregar solicitud=consentimiento o solicitar consentimiento del administrador
AADSTS50011 Conflicto de URI de redirección En uri_redireccionamiento En tu solicitud, la URI de redirección no coincide exactamente con ninguna URI de redirección registrada en el registro de aplicaciones de Entra. Incluso una diferencia en la barra final causa esto. Solución: Copia la URI exacta del registro de aplicaciones de Entra y úsala textualmente.
Corregir: coincidencia exacta de URI en el registro de la aplicación Entra
AADSTS700016 Aplicación no encontrada en el inquilino En client_id no existe en el inquilino contra el que se está autenticando. Común cuando se usa una autoridad específica del inquilino/{id-de-inquilino}) para una aplicación multitenant. Corrección: Usar /común o /organizaciones autoridad para aplicaciones multiinquilino.
Corregir: cambiar a la autoridad /common u /organizations
AADSTS90099 La aplicación no ha sido autorizada en este tenant (consent_required) La aplicación existe pero no ha sido consentida en el tenant del usuario. Difiere de AADSTS65001 en que toda la aplicación está bloqueada, no solo ámbitos específicos. Solución: Envíe la URL de consentimiento del administrador al administrador de TI del cliente.
Corregir: URL de consentimiento del administrador al administrador del tenant del cliente
AADSTS70011 La subvención proporcionada es inválida o ha caducado El token de actualización o el código de autorización ha expirado o ha sido revocado. Los códigos de autorización expiran en 10 minutos. Los tokens de actualización expiran después de 90 días de inactividad o revocación por parte del administrador. Solución: Pida al usuario que se reautentique desde el principio del flujo OAuth.
Corregir: solicitar reautenticación completa
AADSTS50076 Se requiere MFA por la política de acceso condicional El inquilino del usuario requiere autenticación multifactor para tu aplicación. Esta es una decisión del lado del cliente que aplica el administrador del inquilino. Tu aplicación no puede omitirla. El usuario necesita completar la MFA. Si se usa el flujo de código de autenticación, Microsoft mostrará automáticamente el aviso de MFA en el navegador. Los problemas surgen en flujos automatizados (credenciales de cliente) que no pueden completar la MFA.
Esperado: el usuario debe completar la MFA
AADSTS50020 La cuenta de usuario del proveedor de identidad externo no existe en el inquilino El usuario está intentando autenticarse con una cuenta personal de Microsoft en un tenant que solo permite cuentas organizacionales, o viceversa. Corrección: Verifique su punto final de autoridad; si está utilizando /organizaciones, las cuentas personales no pueden autenticarse. Cambiar a /común si necesitas ambos.
Arreglo: cambiar autoridad a /common
AADSTS53003 Acceso bloqueado por la directiva de acceso condicional La directiva de Acceso Condicional del inquilino ha bloqueado completamente este intento de autenticación (por ejemplo, país bloqueado, dispositivo no administrado, aplicación bloqueada). Esta es una decisión del lado del cliente. No puede anularla. Muestre el error al usuario y aconséjele que se ponga en contacto con su administrador de TI.
Lado del cliente: aconseje al usuario que se ponga en contacto con el administrador de TI
Deja que Unipile se encargue de todo esto por ti
La Alternativa Unipile

Olvida 5 semanas de configuración manual de OAuth con Unipile

Todo en esta guía —registro de aplicaciones Entra, puntos de conexión de autoridad, selección de ámbitos, PKCE, rotación de tokens, manejo de errores AADSTS— es tiempo de ingeniería que no hace avanzar tu producto. Unipile se encarga de toda la pila de OAuth de Microsoft Graph como un servicio administrado, por lo que tu equipo escribe una llamada a la API en lugar de 500 líneas de código de conexión de OAuth.

Construyéndolo tú mismo
Registro y configuración de la aplicación Enter
Implementación de PKCE y generación de código de desafío
Almacenamiento, rotación y gestión de caducidad de tokens de actualización
Flujo de consentimiento del administrador para clientes empresariales
Manejo de errores AADSTS y solicitudes de reautenticación
Rotación del secreto del cliente antes de su vencimiento
Manejo de advertencias de Acceso condicional por inquilino
Separar las pilas OAuth para los proveedores de Gmail e IMAP
Usando Unipile
Un POST para generar un enlace de autenticación alojado
Unipile gestiona PKCE, tokens y refresco automáticamente
Tokens nunca se almacenan en tu base de datos - Unipile se encarga de ello
Misma API para cuentas de Microsoft, Gmail e IMAP
Notificaciones de webhook cuando las cuentas necesitan reautenticación
Pantalla de consentimiento con marca con sus propias credenciales de aplicación de Entra
Envía la integración de tu email en horas, no en semanas
Cómo funciona Microsoft OAuth alojado por Unipile
Tu backend llama a un endpoint para generar un enlace de autenticación alojado. Tu usuario hace clic en él, se autentica con Microsoft y Unipile gestiona todo el flujo de OAuth: redirección de Entra, manejo de ámbitos, intercambio de tokens y renovación. La cuenta enlazada estará entonces disponible a través de la API de correo unificada de Unipile.
unipile_microsoft_oauth.py
import solicita UNIPILE_API_URL = "https://apiXXX.unipile.com:XXX" UNIPILE_API_KEY = "tu-api-llave" # Paso 1: Generar un enlace de autenticación alojado para Microsoft response = requests.Correo electrónico:( "{UNIPILE_API_URL}/api/v1/hosted/accounts/link", encabezados={ "Clave API X": Clave_API_UNIPILE, "Tipo-Contenido": "application/json" }, json={ "tipo": "crear", "proveedores": ["MICROSOFT"], "url_de_la_api": UNIPILE_API_URL, "expiraEn": "31/12/2026 23:59:59", # Opcional: vincula este enlace a un usuario concreto "nombre": "usuario_id_123", # Opcional: recibir una notificación cuando se vincule la cuenta "url_de_notificación": "https://app.yourproduct.com/webhooks/account-linked" } ) # Paso 2: Redirige al usuario a esta URL url_autenticacion_alojada = respuesta.json()["url"] Ejemplo de #: https://account.unipile.com/[encoded-token] # Unipile gestiona: redireccionamiento de Entra, pantalla de consentimiento, PKCE, Intercambio de tokens #, actualización del almacenamiento de tokens, gestión del ámbito # Paso 3: Tras la autenticación, utiliza la API de correo electrónico de Unipile para leer y enviar mensajes correos_electrónicos = requests.consiga( f"{UNIPILE_API_URL}/api/v1/correos", encabezados={"Clave API X": {UNIPILE_API_KEY}, params={"account_id": "id-cuenta-vinculada"} )
Microsoft OAuth completado. Buzón disponible a través de la API unificada.
Flujo de autenticación alojado
Unipile aloja la pantalla de consentimiento de OAuth. Tus usuarios ven un flujo limpio y personalizado. Sin mantenimiento de URI de redireccionamiento, sin problemas de CORS, sin malabarismos con URL de localhost frente a producción.
Gestión de tokens
Unipile almacena y rota tokens OAuth de Microsoft en tu nombre. La rotación de tokens de actualización, la monitorización de inactividad de 90 días y las notificaciones de reautenticación se gestionan automáticamente.
API de correo electrónico unificada
Después de vincularse, los buzones de correo de Microsoft, Gmail e IMAP responden a los mismos puntos finales de correo electrónico de Unipile. Una integración sirve a los tres proveedores.
Tus propias credenciales de Entra
Configura tus propias credenciales de aplicación de Microsoft Entra en el panel de Unipile. Tus usuarios verán el nombre de tu aplicación en la pantalla de consentimiento de Microsoft, no el de Unipile.
Notificaciones de webhook
Recibe un webhook cuando una cuenta vinculada necesita una reautenticación (token de actualización caducado, revocación de administrador, cambio de Acceso Condicional). Muestra el aviso de reautenticación inmediatamente en tu producto.
Leer, enviar y sincronizar
Después de OAuth de Microsoft a través de Unipile, puede leer correos electrónicos, enviar correos electrónicos, sincronizar hilos, administrar carpetas y manejar archivos adjuntos, todo a través de la API unificada de correo electrónico de Unipile. No se necesita un cliente de Microsoft Graph por separado.
Cómo funciona Unipile
Unipile es un intermediario técnico independiente que actúa en nombre de cada usuario autenticado a través de tokens OAuth emitidos por Microsoft. Cuando un usuario vincula su buzón de Outlook o Microsoft 365, Unipile opera exclusivamente utilizando los permisos delegados de ese usuario. Unipile no está afiliado, respaldado ni patrocinado por Microsoft. Utilizamos la API pública de Microsoft Graph en nombre de los usuarios finales autenticados. Cada cuenta opera dentro de la identidad de Microsoft Entra del propio usuario y las políticas de Acceso Condicional de su organización.
Comienza a construir tu flujo de OAuth de Microsoft Guía de correo electrónico de MS Graph
PREGUNTAS FRECUENTES

Preguntas frecuentes

Las preguntas más comunes sobre OAuth de Microsoft Graph para la integración de correo electrónico, desde la selección de alcances hasta el ciclo de vida de los tokens y los flujos de consentimiento empresarial.

01
¿Microsoft Graph OAuth funciona tanto para cuentas de Outlook.com como de Microsoft 365?
Sí. Usando el /común endpoint de autoridad, un único registro de aplicación de Microsoft Entra maneja la autenticación tanto para cuentas personales de Outlook.com como para cuentas de trabajo/escuela de Microsoft 365. La clave es seleccionar "Cuentas en cualquier directorio organizacional y cuentas personales de Microsoft" al registrar tu aplicación en el portal de Azure.
02
Los tokens de OAuth que se emiten para un usuario de Microsoft 365 cuando abandona su empresa quedan invalidados.
Cuando un administrador de TI deshabilita o elimina una cuenta de usuario en Microsoft Entra ID, todos los tokens de actualización de ese usuario son revocados inmediatamente. Tu próximo intento de actualización de token devuelve un concesión_inválida error. Maneja esto con gracia: marca la cuenta enlazada como que requiere reautenticación y muestra una indicación clara de reautenticación en tu producto. Este es un comportamiento esperado, una decisión del lado del cliente fuera de tu control.
03
¿Se requiere el consentimiento del administrador para leer correos electrónicos de Outlook a través de OAuth de Microsoft Graph?
No, para permisos delegados estándar. Mail.Read, Mail.ReadWritey Mail.Enviar los ámbitos de consentimiento del usuario, que los usuarios individuales pueden aprobar durante el flujo de OAuth. El consentimiento del administrador solo es necesario para los permisos de la aplicación o los ámbitos de alta privilegios, como Usuario.Leer.Todos. Algunos inquilinos empresariales configuran políticas que bloquean el consentimiento de todas las aplicaciones de terceros; esa es una decisión del cliente.
04
¿Cuánto tiempo duran los tokens de actualización de Microsoft Graph?
Los tokens de actualización caducan después de 90 días de inactividad. Siempre que tu aplicación utilice el token de actualización de forma regular (lo que ocurre automáticamente al actualizar los tokens de acceso antes de que caduquen cada 60-90 minutos), el token de actualización se mantiene activo. Los cambios en las directivas de acceso condicional, los restablecimientos de contraseña o la revocación por parte de un administrador pueden invalidarlos antes. Maneja siempre concesión_inválida errores y reemplazar los tokens de actualización antiguos por el nuevo devuelto en cada respuesta de token.
05
¿Cuál es la diferencia entre AADSTS65001 y AADSTS90099?
AADSTS65001El usuario aún no ha consentido uno o más ámbitos específicos. Solución: añadir consentimiento a su URL de autorización para forzar una pantalla de consentimiento nueva. AADSTS90099Toda la aplicación no ha sido autorizada en ese tenant; el administrador del tenant necesita pre-aprobar tu aplicación. Envía la URL de consentimiento del administrador al administrador de TI del cliente. Ambos errores son comunes en escenarios empresariales donde los tenants restringen el consentimiento del usuario.
06
¿Puedo usar el mismo registro de aplicación de Entra para leer y enviar correos electrónicos?
Sí. Solicitar ambos Mail.ReadWrite y Mail.Enviar en el mismo ámbito de cadena. Nota que Mail.ReadWrite y Mail.Enviar son ámbitos separados: tener acceso de lectura/escritura no otorga automáticamente permiso para enviar. Siempre incluye acceso_sin_conexión para asegurarte de que recibes un token de actualización. Consulta Página de la API de correo electrónico para detalles de implementación.
07
¿Unipile almacena los tokens de OAuth de Microsoft en mi base de datos?
No. Cuando utilizas el flujo de autenticación de Microsoft alojado por Unipile, Unipile gestiona todos los tokens OAuth en tu nombre. Tu aplicación nunca maneja directamente los tokens de acceso o de actualización de Microsoft. Interactúas con las cuentas enlazadas exclusivamente a través de la API unificada de correo de Unipile utilizando tu clave API de Unipile. Esto elimina los requisitos de almacenamiento de tokens, rotación y seguridad de tu propia infraestructura.
08
¿Está Unipile afiliada a Microsoft?
No. Unipile no está afiliado, respaldado ni patrocinado por Microsoft. Unipile es un intermediario técnico independiente que utiliza la API pública de Microsoft Graph en nombre de los usuarios finales autenticados. Cada integración opera a través de tokens OAuth emitidos por Microsoft bajo la identidad del propio usuario y las políticas de Acceso Condicional de su organización. Microsoft Graph y Microsoft Entra son marcas comerciales de Microsoft Corporation.
¿Aún tiene preguntas? Nuestro equipo puede guiarte a través del proceso de OAuth de Microsoft Graph para tu caso de uso específico.
es_ESES
en_USEN fr_FRFR de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR es_ESES