通过

使用 OAuth 对 IMAP、POP 或 SMTP 连接进行身份验证

  • 项目

了解如何使用 OAuth 身份验证来连接 IMAP、POP 或 SMTP 协议，以及访问Office 365用户的电子邮件数据。

Microsoft 365 (包括Office web 版) 和 Outlook.com 用户，对 IMAP、POP 和 SMTP 协议的 OAuth2 支持如下。

如果不熟悉 OAuth 2.0 协议，请参阅Microsoft 标识平台概述上的 OAuth 2.0 协议。 有关Microsoft身份验证库 (MSAL) 的详细信息，这些库实现 OAuth 2.0 协议对用户进行身份验证并访问安全 API，请参阅 MSAL 概述。

可以使用 Microsoft Entra (Microsoft Entra) 提供的 OAuth 身份验证服务，使应用程序能够使用 IMAP、POP 或 SMTP 协议进行连接，以访问 Office 365 中的Exchange Online。 若要将 OAuth 与应用程序配合使用，需要：

  1. 向 Microsoft Entra 注册应用程序。
  2. 从令牌服务器获取访问令牌。
  3. 使用访问令牌对连接请求进行身份验证。

注册应用程序

若要使用 OAuth，必须使用 Microsoft Entra 注册应用程序。

按照使用 Microsoft 标识平台注册应用程序中列出的说明创建新的应用程序。

获取访问令牌

可以使用我们的 MSAL 客户端库 之一从客户端应用程序中提取访问令牌。

或者，可以从以下列表中选择适当的流，并按照相应的步骤调用基础标识平台 REST API 并检索访问令牌。

  1. OAuth2 授权代码流
  2. OAuth2 设备授权流

在授权应用程序并请求访问令牌时，请确保指定完整范围，包括 Outlook 资源 URL。

协议 权限范围字符串
IMAP https://outlook.office.com/IMAP.AccessAsUser.All
流行 https://outlook.office.com/POP.AccessAsUser.All
SMTP 身份验证 https://outlook.office.com/SMTP.Send

此外，还可以请求 offline_access 范围。 当用户批准offline_access范围时，应用可以从Microsoft 标识平台令牌终结点接收刷新令牌。 刷新令牌的生存期很长。 旧版访问令牌过期后，应用可以获取新的访问令牌。

或者，可以使用 OAuth2 客户端凭据授予流 来提取访问令牌，而不是 OAuth2 授权代码流或 OAuth2 设备授权流。

对连接请求进行身份验证

可以使用Office 365的 IMAP 和 POP 电子邮件设置启动与Office 365邮件服务器的连接。

SASL XOAUTH2

OAuth 集成要求应用程序使用 SASL XOAUTH2 格式对访问令牌进行编码和传输。 SASL XOAUTH2按以下格式将用户名和访问令牌编码在一起：

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

^A 表示 控件 + A (%x01) 。

例如，使用访问令牌EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA访问test@contoso.onmicrosoft.com的 SASL XOAUTH2格式为：

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

base64 编码后，此格式将转换为以下字符串。 插入换行符是为了提高可读性。

dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVy
IEV3QkFBbDNCQUFVRkZwVUFvN0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==

Office 365中共享邮箱的 SASL XOAUTH2身份验证

在使用 OAuth 进行共享邮箱访问的情况下，应用程序需要代表用户获取访问令牌，但将 SASL XOAUTH2编码字符串中的 userName 字段替换为共享邮箱的电子邮件地址。

IMAP 协议交换

若要对 IMAP 服务器连接进行身份验证，客户端必须使用以下格式的命令进行响应 AUTHENTICATE ：

AUTHENTICATE XOAUTH2 <base64 string in XOAUTH2 format>

导致身份验证成功的示例客户端-服务器消息交换：

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

导致身份验证失败的示例客户端-服务器消息交换：

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

POP 协议交换

若要对 POP 服务器连接进行身份验证，客户端必须采用以下格式，使用 AUTH 拆分为两行的命令进行响应：

AUTH XOAUTH2 
<base64 string in XOAUTH2 format>

导致身份验证成功的示例客户端-服务器消息交换：

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

导致身份验证失败的示例客户端-服务器消息交换：

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

SMTP 协议交换

若要对 SMTP 服务器连接进行身份验证，客户端必须使用以下格式的命令进行响应 AUTH ：

AUTH XOAUTH2 <base64 string in XOAUTH2 format>

导致身份验证成功的示例客户端-服务器消息交换：

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

导致身份验证失败的示例客户端-服务器消息交换：

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

使用客户端凭据授予流对 SMTP、IMAP 和 POP 连接进行身份验证

Exchange 中的服务主体用于允许应用程序使用 SMTP、POP 和 IMAP 协议通过客户端凭据流访问 Exchange 邮箱。

将 POP、IMAP 或 SMTP 权限添加到 Entra AD 应用程序

  1. 在Azure 门户，在Microsoft Entra应用程序的管理视图中选择“API 权限”边栏选项卡。

  2. 选择“ 添加权限”。

  3. 选择“我的组织使用的 API”选项卡，然后搜索“Office 365 Exchange Online”。

  4. 单击“ 应用程序权限”。

  5. 对于 POP 访问，请选择 POP。AccessAsApp 权限。 对于 IMAP 访问，请选择 IMAP。AccessAsApp 权限。 对于 SMTP 访问，请选择 SMTP。SendAsApp 权限。

    pop-imap-permission

  6. 选择权限类型后，选择“ 添加权限”。

现在，应将 SMTP、POP 或 IMAP 应用程序权限添加到 Entra AD 应用程序的权限中。

若要通过 POP 或 IMAP 访问 Exchange 邮箱，Entra AD 应用程序必须获得每个租户的租户管理员同意。 有关详细信息，请参阅 租户管理员同意流程。

如果 ISV/合作伙伴使用“任何组织目录中的帐户”选项注册了Microsoft Entra应用程序，则需要通过利用授权请求 URL，通过以下步骤添加此应用程序并许可该应用程序。

POP 和 IMAP 指南

在 OAuth 2.0 租户授权请求中 scope ，查询参数应 https://ps.outlook.com/.default 同时适用于 POP 和 IMAP 应用程序范围。 以下示例中显示了 OAuth 2.0 授权请求 URL：

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

在 OAuth 2.0 租户授权请求中 scope ，查询参数应 https://outlook.office365.com/.default 仅用于 SMTP。 以下示例中显示了 OAuth 2.0 授权请求 URL：

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

如果使用“仅限此组织目录中的帐户”在自己的租户中注册了应用程序，则可以继续使用Microsoft Entra 管理中心中的应用程序配置页授予管理员同意，并且无需使用授权请求 URL 方法。

granting-consent-for-tenant

在 Exchange 中注册服务主体

租户管理员同意Microsoft Entra应用程序后，他们必须通过 Exchange Online PowerShell 在 Exchange 中注册 Entra AD 应用程序的服务主体。 此注册由 New-ServicePrincipal cmdlet 启用。

若要使用 New-ServicePrincipal cmdlet，请安装 ExchangeOnlineManagement 并连接到租户，如以下代码片段所示：

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

如果在执行这些步骤后运行 New-ServicePrincipal cmdlet 时仍遇到错误，则可能是因为用户在 Exchange online 中没有足够的权限来执行该操作。

以下示例显示了在 Exchange 中注册Microsoft Entra应用程序的服务主体：

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

租户管理员可以在租户上的 Entra AD 应用程序的企业应用程序实例中找到上面引用的服务主体标识符。 可以在 Azure 门户的“Microsoft Entra”视图中的“企业应用程序”边栏选项卡中找到租户上的企业应用程序实例列表。

可以使用 cmdlet 获取已注册服务主体的标识符Get-ServicePrincipal。

Get-ServicePrincipal | fl

OBJECT_ID是企业应用程序节点的“概述”页中的对象 ID， (Azure 门户) 应用程序注册。 它 不是 “应用注册”节点的“概述”页中的“对象 ID”。 使用不正确的对象 ID 将导致身份验证失败。

租户管理员现在可以在租户中添加应用程序允许访问的特定邮箱。 此配置是使用 Add-MailboxPermission cmdlet 完成的。

以下示例演示如何向应用程序的服务主体授予对一个邮箱的访问权限：

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

在创建 Exchange 服务主体期间以及以后授予邮箱权限时，会使用不同的 ID。 以下示例可帮助你对不同阶段使用正确的 ID。 此示例使用 Microsoft Entra cmdlet;因此，如果尚未安装，则需要安装 Microsoft Entra PowerShell 模块。 有关详细信息，请参阅安装 Microsoft Entra PowerShell for 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

Microsoft Entra应用程序现在可以使用 OAuth 2.0 客户端凭据授予流通过 SMTP、POP 或 IMAP 协议访问允许的邮箱。 有关详细信息，请参阅Microsoft 标识平台的权限和同意中的说明。

必须在 访问令牌请求的正文有效负载的 属性中使用 https://outlook.office365.com/.defaultscope 。

生成的访问令牌可用作令牌，通过 SASL XOAUTH2格式对 SMTP、POP 和 IMAP 连接进行身份验证，如前所述。

注意

如果尝试将客户端凭据授予流与 SendAs 一起使用，则需要向发件人授予 SendAs 权限： Add-RecipientPermission (ExchangePowerShell) 。

另请参阅