微软 OAuth2

跳转至主内容

此浏览器不再受支持。

请升级到 Microsoft Edge 以使用最新的功能、安全更新和技术支持。

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

• 项目
• 11/16/2022

本文内容

了解如何使用 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 概述。

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

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

注册应用程序

若要使用 OAuth，必须将应用程序注册到 Azure Active Directory。

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

获取访问令牌

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

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

1. OAuth2 授权代码流
2. OAuth2 设备授权流
3. OAuth2 客户端凭据授予流

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

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

对连接请求进行身份验证

可以使用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访问的 SASL XOAUTH2 格式为：

base64("user=^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 Oauth 2.0 客户端凭据流。

若要对 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]

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

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

将 POP 和 IMAP 权限添加到 AAD 应用程序

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

2. 选择“ 添加权限”。

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

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

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

   

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

现在，应将 POP 或 IMAP 应用程序权限添加到 AAD 应用程序的权限中。

获取租户管理员同意

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

如果应用程序是针对多个租户使用（例如合作伙伴/ISV 开发的集中注册应用程序）注册/配置的，如何授予同意

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

在 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

如果你为自己的租户注册了应用程序，如何授予同意

如果使用“仅限此组织目录中的帐户”在自己的租户中注册了应用程序，则只需在 Azure AD 管理中心内使用应用程序配置页来授予管理员同意，而无需使用授权请求 URL 应用。

在 Exchange 中注册服务主体

租户管理员同意 Azure AD 应用程序后，租户管理员必须通过 Exchange Online PowerShell 在 Exchange 中注册 AAD 应用程序的服务主体。 这由 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 中注册 Azure AD 应用程序的服务主体的示例：

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

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

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

Get-ServicePrincipal | fl

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

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

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

Add-MailboxPermission -Identity "" -User 
<SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

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

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

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

另请参阅

• 使用 powershell 脚本进行 IMAP OAuth 测试

• 在 Exchange 中的身份验证和 EWS

• IMAP、POP 连接设置

• Internet 消息访问协议

• 邮局协议

• 用于身份验证的 SMTP 服务扩展