Autenticación de una conexión IMAP, POP o SMTP mediante OAuth

  • Artículo

Obtenga información sobre cómo usar la autenticación de OAuth para conectarse con protocolos IMAP, POP o SMTP y para acceder a los datos de correo electrónico de Office 365 usuarios.

La compatibilidad de OAuth2 con los protocolos IMAP, POP y SMTP, como se describe a continuación, está disponible tanto para los usuarios de Microsoft 365 (que incluye Office en la Web) como para los usuarios de Outlook.com.

Importante

En esta documentación se usa el ámbito de la API REST de Outlook en desuso. En su lugar, las nuevas aplicaciones deben usar el punto de conexión de la API REST de Graph .

Si no está familiarizado con el protocolo OAuth 2.0, consulte Protocolo de OAuth 2.0 en Plataforma de identidad de Microsoft información general. Para obtener más información sobre las bibliotecas de autenticación de Microsoft (MSAL), que implementan el protocolo OAuth 2.0 para autenticar usuarios y acceder a las API seguras, consulte Información general de MSAL.

Puede usar el servicio de autenticación de OAuth proporcionado por Microsoft Entra (Microsoft Entra) para permitir que la aplicación se conecte con protocolos IMAP, POP o SMTP para acceder a Exchange Online en Office 365. Para usar OAuth con la aplicación, debe:

  1. Registre la aplicación con Microsoft Entra.
  2. Obtenga un token de acceso de un servidor de tokens.
  3. Autentique las solicitudes de conexión con un token de acceso.

Registrar su aplicación

Para usar OAuth, una aplicación debe registrarse con Microsoft Entra.

Siga las instrucciones que aparecen en Registro de una aplicación con el Plataforma de identidad de Microsoft para crear una nueva aplicación.

Obtener un token de acceso

Puede usar una de nuestras bibliotecas cliente de MSAL para capturar un token de acceso de la aplicación cliente.

Como alternativa, puede seleccionar un flujo adecuado en la lista siguiente y seguir los pasos correspondientes para llamar a las API REST de la plataforma de identidad subyacente y recuperar un token de acceso.

  1. Flujo de código de autorización de OAuth2
  2. Flujo de concesión de autorización de dispositivos OAuth2
  3. Flujo de concesión de credenciales de cliente de OAuth2

Asegúrese de especificar los ámbitos completos, incluidas las direcciones URL de recursos de Outlook, al autorizar la aplicación y solicitar un token de acceso.

Protocolo Cadena de ámbito de permiso
IMAP https://outlook.office.com/IMAP.AccessAsUser.All
POP https://outlook.office.com/POP.AccessAsUser.All
AUTENTICACIÓN SMTP https://outlook.office.com/SMTP.SendAsApp

Además, puede solicitar offline_access ámbito. Cuando un usuario aprueba el ámbito de offline_access, la aplicación puede recibir tokens de actualización del punto de conexión de token de Plataforma de identidad de Microsoft. Los tokens de actualización son de larga duración. La aplicación puede obtener nuevos tokens de acceso a medida que expiren los más antiguos.

Autenticación de solicitudes de conexión

Puede iniciar una conexión a Office 365 servidores de correo mediante la configuración de correo electrónico IMAP y POP para Office 365.

SASL XOAUTH2

La integración de OAuth requiere que la aplicación use el formato de XOAUTH2 SASL para codificar y transmitir el token de acceso. SASL XOAUTH2 codifica el nombre de usuario y el token de acceso juntos en el formato siguiente:

base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")

^A representa un control + A (%x01).

Por ejemplo, el formato de XOAUTH2 SASL para acceder test@contoso.onmicrosoft.com con el token de EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA acceso es:

base64("user=test@contoso.onmicrosoft.com^Aauth=Bearer EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA^A^A")

Después de la codificación base64, este formato se traduce en la siguiente cadena. Los saltos de línea se insertan para mejorar la legibilidad.

dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVy
IEV3QkFBbDNCQUFVRkZwVUFvN0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==

Autenticación de sasl XOAUTH2 para buzones compartidos en Office 365

En el caso del acceso al buzón compartido mediante OAuth, una aplicación debe obtener el token de acceso en nombre de un usuario, pero reemplazar el campo userName en la cadena codificada sasl XOAUTH2 por la dirección de correo electrónico del buzón compartido.

Intercambio de protocolo IMAP

Para autenticar una conexión de servidor IMAP, el cliente debe responder con un AUTHENTICATE comando en el formato siguiente:

AUTHENTICATE XOAUTH2 <base64 string in XOAUTH2 format>

Intercambio de mensajes cliente-servidor de ejemplo que da como resultado una autenticación correcta:

[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 OK AUTHENTICATE completed.

Intercambio de mensajes cliente-servidor de ejemplo que produce un error de autenticación:

[connection begins]
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 NO AUTHENTICATE failed.

Intercambio de protocolo POP

Para autenticar una conexión de servidor POP, el cliente tendrá que responder con un AUTH comando dividido en dos líneas en el formato siguiente:

AUTH XOAUTH2 
<base64 string in XOAUTH2 format>

Intercambio de mensajes cliente-servidor de ejemplo que da como resultado una autenticación correcta:

[connection begins] 
C: AUTH XOAUTH2  
S: + 
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX 
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0 
Q2cBAQ== 
S: +OK User successfully authenticated. 
[connection continues...]

Intercambio de mensajes cliente-servidor de ejemplo que produce un error de autenticación:

[connection begins] 
C: AUTH XOAUTH2  
S: + 
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY 
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj 
l0Q2cBAQ= 
S: -ERR Authentication failure: unknown user name or bad password.

Intercambio de protocolo SMTP

Para autenticar una conexión de servidor SMTP, el cliente debe responder con un AUTH comando en el formato siguiente:

AUTH XOAUTH2 <base64 string in XOAUTH2 format>

Intercambio de mensajes cliente-servidor de ejemplo que da como resultado una autenticación correcta:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Authentication successful
[connection continues...]

Intercambio de mensajes cliente-servidor de ejemplo que produce un error de autenticación:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 535 5.7.3 Authentication unsuccessful [SN2PR00CA0018.namprd00.prod.outlook.com]

Uso del flujo de concesión de credenciales de cliente para autenticar conexiones SMTP, IMAP y POP

Las entidades de servicio de Exchange se usan para permitir que las aplicaciones accedan a los buzones de Exchange a través del flujo de credenciales de cliente con los protocolos SMTP, POP e IMAP.

Agregue los permisos POP, IMAP o SMTP a la aplicación Entra AD.

  1. En el Azure Portal, elija la hoja Permisos de API en la vista de administración de la aplicación de Microsoft Entra.

  2. Seleccione Agregar permiso.

  3. Seleccione la pestaña API que usa mi organización y busque "Office 365 Exchange Online".

  4. Haga clic en Permisos de aplicación.

  5. En Acceso POP, elija pop . Permiso AccessAsApp . Para el acceso IMAP, elija imap . Permiso AccessAsApp . Para el acceso SMTP, elija SMTP. Permiso SendAsApp .

    pop-imap-permission

  6. Una vez que haya elegido el tipo de permiso, seleccione Agregar permisos.

Ahora debe tener los permisos de aplicación SMTP, POP o IMAP agregados a los permisos de la aplicación Entra AD.

Para acceder a los buzones de Exchange a través de POP o IMAP, la aplicación Entra AD debe obtener el consentimiento del administrador de inquilinos para cada inquilino. Para obtener más información, consulte proceso de consentimiento del administrador de inquilinos.

Si el ISV o asociado registró la aplicación Microsoft Entra con la opción "Cuentas en cualquier directorio organizativo", debe agregar esta aplicación y dar su consentimiento mediante los pasos siguientes aprovechando la dirección URL de la solicitud de autorización.

Guía POP e IMAP

En la solicitud de autorización de inquilino de OAuth 2.0, el parámetro de scope consulta debe ser https://ps.outlook.com/.default para los ámbitos de aplicación POP e IMAP. La dirección URL de la solicitud de autorización de OAuth 2.0 se muestra en el ejemplo siguiente:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://ps.outlook.com/.default
Guía de SMTP

En la solicitud de autorización de inquilino de OAuth 2.0, el parámetro de scope consulta debe ser https://outlook.office365.com/.default solo para SMTP. La dirección URL de la solicitud de autorización de OAuth 2.0 se muestra en el ejemplo siguiente:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://outlook.office365.com/.default

Si registró la aplicación en su propio inquilino mediante "Solo cuentas en este directorio organizativo", puede seguir adelante y usar la página de configuración de la aplicación dentro de la Centro de administración Microsoft Entra para conceder el consentimiento del administrador y no tiene que usar el enfoque de dirección URL de solicitud de autorización.

granting-consent-for-tenant

Registro de entidades de servicio en Exchange

Una vez que un administrador de inquilinos da su consentimiento a la aplicación Microsoft Entra, debe registrar la entidad de servicio de la aplicación Entra AD en Exchange a través de Exchange Online PowerShell. El cmdlet habilita New-ServicePrincipaleste registro.

Para usar el cmdlet New-ServicePrincipal , instale ExchangeOnlineManagement y conéctese al inquilino como se muestra en el siguiente fragmento de código:

Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement 
Connect-ExchangeOnline -Organization <tenantId>

Si sigue teniendo un error al ejecutar el cmdlet New-ServicePrincipal después de realizar estos pasos, es probable que el usuario no tenga suficientes permisos en Exchange Online para realizar la operación.

En el ejemplo siguiente se muestra el registro de la entidad de servicio de una aplicación de Microsoft Entra en Exchange:

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]

El administrador de inquilinos puede encontrar los identificadores de entidad de servicio a los que se hace referencia anteriormente en la instancia de aplicación empresarial de la aplicación Entra AD en el inquilino. Puede encontrar la lista de las instancias de aplicación empresarial en el inquilino en la hoja Aplicaciones empresariales de la vista Microsoft Entra de Azure Portal.

Puede obtener el identificador de la entidad de servicio registrada mediante el Get-ServicePrincipal cmdlet .

Get-ServicePrincipal | fl

El OBJECT_ID es el identificador de objeto de la página Información general del nodo Aplicación empresarial (Azure Portal) para el registro de la aplicación. No es el identificador de objeto de la página Información general del nodo Registros de aplicaciones. El uso del identificador de objeto incorrecto provocará un error de autenticación.

El administrador de inquilinos ahora puede agregar los buzones específicos en el inquilino a los que la aplicación podrá acceder. Esta configuración se realiza con el Add-MailboxPermission cmdlet .

En el ejemplo siguiente se muestra cómo conceder a la entidad de servicio de la aplicación acceso a un buzón:

Add-MailboxPermission -Identity "john.smith@contoso.com" -User 
<SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

Se usan diferentes identificadores durante la creación de la entidad de servicio de Exchange y también posteriores al conceder permisos de buzón. El ejemplo siguiente puede ayudarle a usar el identificador correcto para las distintas fases. En este ejemplo se usan cmdlets de Microsoft Entra; por lo tanto, deberá instalar el módulo de PowerShell Microsoft Entra, si aún no lo ha hecho. Para obtener más información, vea Instalar Microsoft Entra PowerShell para Graph.

$AADServicePrincipalDetails = Get-AzureADServicePrincipal -SearchString YourAppName

New-ServicePrincipal -AppId $AADServicePrincipalDetails.AppId -ObjectId $AADServicePrincipalDetails.ObjectId -DisplayName "EXO Serviceprincipal for EntraAD App $($AADServicePrincipalDetails.Displayname)"

$EXOServicePrincipal = Get-ServicePrincipal -Identity "EXO Serviceprincipal for EntraAD App YourAppName"

Add-MailboxPermission -Identity "john.smith@contoso.com" -User $EXOServicePrincipal.Identity -AccessRights FullAccess

La aplicación Microsoft Entra ahora puede acceder a los buzones permitidos a través de los protocolos SMTP, POP o IMAP mediante el flujo de concesión de credenciales de cliente de OAuth 2.0. Para obtener más información, consulte las instrucciones de Permisos y consentimiento en el Plataforma de identidad de Microsoft.

Debe usar https://outlook.office365.com/.default en la scope propiedad de la carga del cuerpo para la solicitud de token de acceso.

Los tokens de acceso generados se pueden usar como tokens para autenticar conexiones SMTP, POP e IMAP a través del formato de XOAUTH2 SASL, tal como se describió anteriormente.

Consulte también