Exchange Online 管理员 API 的身份验证和授权

注意

本文中所述的功能目前为预览版，并非在所有组织中都可用，并且可能会发生更改。

本文介绍使用 Exchange Online 管理员 API 终结点的身份验证和授权要求。

Exchange Online 管理员 API 提供了一种基于 REST 的方式来运行特定的 PowerShell cmdlet，取代了旧版 Exchange Web Services (EWS) 方案。有关详细信息，请参阅 Exchange Online 管理员 API 概述。

若要访问管理员 API，应用必须建立其标识、获取正确的权限，并遵循安全令牌处理的最佳做法。概括而言，此过程涉及以下关键步骤：

在 Microsoft Entra ID 中注册应用

创建应用注册以为应用建立标识，并 (客户端机密或证书) 配置凭据。此注册使应用能够从Microsoft Entra ID请求令牌。
分配所需的 API 权限

将必要的 OAuth 范围添加到应用注册：
- 委托流： Exchange.ManageV2。
- 仅限应用的流： Exchange.ManageAsAppV2。
步骤 3：分配 RBAC 权限

Exchange Online使用基于角色的访问控制 (RBAC) 来确定调用方可以管理哪些终结点、cmdlet 和对象。将适当的 RBAC 角色分配给用户 (以用于委派访问) ，或分配给应用的服务主体 (，以便仅应用访问) 。
步骤 4：获取访问令牌

使用 OAuth 2.0 流从Microsoft Entra ID获取令牌：
- 基于用户的访问的委托流。
- 用于服务到服务访问的仅限应用的流。
步骤 5：使用访问令牌

步骤 1：在 Microsoft Entra ID 中注册应用

若要调用 Exchange Online 管理员 API，必须先在 Microsoft Entra ID 中注册应用。应用类似于类对象。服务主体类似于类的实例。有关详细信息，请参阅 Microsoft Entra ID 中的应用程序和服务主体对象。有关在 Microsoft Entra ID 中创建应用程序的详细视觉流，请参阅 https://aka.ms/azuread-app。

在处打开Microsoft Entra 管理中心https://entra.microsoft.com。
在页面顶部的搜索框中，输入应用注册并从结果中选择它。
在“应用注册”页面，选择“新增注册”。
在 “注册应用程序 ”页上，配置应用程序设置：
- 名称：输入描述性名称 (，例如 Exchange 管理员 API 客户端) 。
- 支持的帐户类型：选择以下值之一：
  - 单组织应用：仅选择 此组织目录中的帐户。
  - 多租户委托方案：选择 任何组织目录中的帐户。
- 重定向 URI (可选) ：委托流是必需的。
  - 平台：选择“ Web”。
  - URI：输入发送访问令牌的 URL (例如， https://localhost 用于测试) 。
完成“ 注册应用程序 ”页后，选择“ 注册”。

你将被带到已注册应用的 “概述 ”页。留在页面上进行下一步。

注意

无法为本机应用程序创建凭据，因为它们不能用于自动服务到服务调用。

步骤 2：分配所需的 API 权限

在上一步中创建的应用的“概述”页上，从“管理”部分选择“API 权限”。
在应用的 “API 权限 ”页上，选择“ 添加权限”。
在打开的“请求 API 权限”浮出控件中，选择“我的组织使用的 API”选项卡，在搜索框中输入Office 365 Exchange Online，然后从结果中选择它。
在 “应用程序需要哪些类型的权限？” 浮出控件上，选择以下选项之一：
- 仅限应用的流：选择“ 应用程序权限”，展开“ Exchange”，选择“ Exchange.ManageAsAppV2”，然后选择“ 添加权限”。
- 委托流：选择“ 委派权限”，展开“ Exchange”，选择“ Exchange.ManageV2”，然后选择“ 添加权限”。
返回 “API 权限 ”页，验证是否列出了上一步中的选择：
- > Office 365 Exchange Online Exchange.ManageAsApp：
  - 类型：应用程序
  - 需要管理员同意：是
- > Office 365 Exchange Online Exchange.ManageV2：
  - 类型：委派
  - 需要管理员同意：是
选择“ 授予管理员同意”，查看确认对话框，然后选择“ 是”。

步骤 3：分配 RBAC 权限

注册应用并授予 API 权限后，必须配置 Exchange RBAC 角色。 OAuth 范围允许应用获取令牌，但 RBAC 确定调用方可以管理哪些 cmdlet 和对象。如果没有适当的 RBAC 角色分配，即使有效令牌也会失败并出现错误： 403 禁止访问。

根据应用的性质，使用以下子部分中的步骤之一。

委派 (用户) 流的权限

对于委托方案，应用代表其获取令牌的用户必须在 Exchange Online 中分配必要的 RBAC 角色。常见角色示例：

邮箱和文件夹作的收件人管理。
组织级别设置的组织管理。
只读组织作的“仅查看组织管理”。

通过 Exchange 管理中心或 Exchange Online PowerShell 分配这些角色。有关说明，请参阅在 Exchange Online 中管理角色组。

仅限应用流的权限

对于仅应用方案，表示应用的服务主体必须具有足够的权限。可以选择下列选项：

为简单起见) (建议分配Microsoft Entra角色：向企业应用程序授予内置Microsoft Entra角色。例如，完全Exchange Online权限的 Exchange 管理员：
1. 在 Microsoft Entra 管理中心中https://entra.microsoft.com，选择“& 管理员的角色”。
2. 在“角色和管理员”上 |“所有角色”页，单击第一列旁边的“检查”框以外的任何位置，选择 Exchange 管理员角色。
3. 在 Exchange 管理员中 |打开的“分配 ”页，选择“ 添加分配”，选择你的应用，然后选择“ 确认”。
将内置或自定义 Exchange RBAC 角色组分配 (最低特权) ：在仅包含应用所需的 cmdlet 的Exchange Online中创建或使用现有自定义角色组，并将服务主体添加到这些组。此方法可避免广泛的特权，并与最低特权安全性保持一致。有关详细信息，请参阅 Exchange Online PowerShell 中的仅限应用的身份验证。

下表列出了每个终结点所需的内置 RBAC 角色。

端点	所需的 Exchange 角色组
/OrganizationConfig /AcceptedDomain	仅查看组织管理
/邮箱 /MailboxFolderPermission /DistributionGroupMember /DynamicDistributionGroupMember	收件人管理

若要进行更精细的控制，请考虑使用仅包含特定管理角色的自定义角色组 (cmdlet 集) 应用程序需求。与 Exchange 管理员或全局管理员等广泛角色相比，此方法遵循最低特权安全性并降低风险，这些角色超出了典型管理员 API作所需的范围。

步骤 4：获取访问令牌

若要调用 Exchange Online 管理员 API，应用必须从 Microsoft Entra ID 获取 OAuth 2.0 访问令牌。如前所述，管理员 API 支持以：

授权代码流 (具有刷新令牌的委托) ：应用代表已登录用户执行作，如果请求包含范围，还可以获取用于无提示续订的 offline_access 刷新令牌。
客户端凭据流 (仅限应用的) ：你的应用充当自身， (没有用户) 。用于服务/后台方案。刷新令牌不会在此流中颁发。

/.default请求令牌时使用资源的范围 (例如 https://outlook.office365.com/.default) 。此方法告知Microsoft Entra ID颁发一个令牌，其中包含) 以前为该资源授予的应用程序权限 (角色。

授权代码流 (具有刷新令牌的委托)

如果需要用户上下文，请使用此流。若要获取刷新令牌，必须在授权和令牌请求 offline_access 中请求。有关详细信息，请参阅刷新Microsoft 标识平台中的令牌和Microsoft 标识平台中的作用域和权限。

用户需要授权应用代表他们进行作。应用将用户重定向到/authorizeMicrosoft 标识平台中的终结点。通过此终结点，Microsoft Entra ID用户登录并请求其同意应用请求的权限。同意后，Microsoft Entra ID向应用返回授权代码。然后，应用可以在Microsoft 标识平台终结点兑换此代码/token以获取访问令牌。

以下示例显示了对 /authorize 终结点的请求。在请求 URL 中，调用终结点， /authorize 并将所需属性和建议属性指定为查询参数。例如：

GET https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/authorize
    ?client_id=<ClientID>
    &response_type=code
    &redirect_uri=<RedirectURI> # must exactly match the app registration
    &response_mode=query
    &scope=https://outlook.office365.com/.default offline_access
    &state=12345

下表介绍了这些参数：

参数	必需	说明
TenantID	必需	请求权限的组织。该值可以是 TenantID GUID 或友好名称。
client_id	必需	注册门户分配给应用的客户端 ID。也称为 appId。
response_type	必需	必须包含 OAuth 2.0 授权代码流的值 `code` 。
redirect_uri	建议	应用的重定向 URI，采用 URL 编码格式，其中身份验证响应由应用发送和接收。它必须与在应用注册门户中注册的重定向 URI 之一匹配。
范围	必需	希望用户同意的Exchange Online 管理员 API 权限的空格分隔列表。这些权限可以包括在此方案中 (`https://outlook.office365.com/.default` 资源权限) 和 OIDC 范围，例如 `offline_access`，这表示应用需要刷新令牌才能长期访问资源。
response_mode	建议	指定将生成的令牌发送回应用的方法。有效值为 `query` 或 `form_post`。
state	建议	请求中包含的一个值，该值也会在令牌响应中返回。它可以是任何内容的字符串。通常使用随机的唯一值来防止跨站点请求伪造攻击。此属性还会在身份验证请求发生前对应用中有关用户状态的信息进行编码，例如用户所访问的页面或视图。

用户登录并同意。 Microsoft Entra ID使用重定向到。redirect_uri?code=<authorization_code>
使用 offline_access 可在以后颁发刷新令牌。有关详细信息，请参阅刷新Microsoft 标识平台中的令牌和Microsoft 标识平台中的作用域和权限。

步骤 2：兑换令牌的授权代码

应用使用上一步中的授权代码通过向终结点发送 POST 请求来请求 /token 访问令牌。

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                  # confidential clients only
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<RedirectURI>
&scope=https://outlook.office365.com/.default offline_access

下表介绍了这些参数：

参数	必需	说明
TenantID	必需	请求权限的组织。该值可以是 TenantID GUID 或友好名称。
client_id	必需	注册门户分配给应用的客户端 ID。也称为 appId。
grant_type	必需	对于授权代码流，该值必须为 `authorization_code` 。
范围	必需	以空格分隔的范围列表。应用请求的范围必须等效或步骤 1：向用户发送登录和同意中请求的范围的子集。
code	必需	在步骤 1：向用户发送登录和同意中获取的授权代码。
redirect_uri	必需	在步骤 1：向用户发送登录和同意中用于获取授权代码的相同重定向 URI 值。
client_secret	Web 应用需要	在应用注册门户中为应用创建的客户端密码。

成功的响应包括：

access_token：承载。通常大约 60 分钟。
refresh_token：存在，因为 offline_access 已请求。
id_token：自选。如果请求范围 openid ，则返回。有关详细信息，请参阅 Microsoft 标识平台中的Microsoft 标识平台应用类型和身份验证流和刷新令牌。

提示

存储来自令牌声明的 TenantID (tid) 值。需要它来形成管理员 API URL 和将来的令牌请求。有关详细信息，请参阅Microsoft 标识平台应用类型和身份验证流。

步骤 3：无提示 (无用户提示) 以静默方式刷新访问令牌

访问令牌生存期较短，应用必须在过期后刷新这些令牌才能继续访问资源。应用通过向终结点提交另一个 POST 请求来 /token 刷新访问令牌：

refresh_token在请求正文中提供而不是 code 。
指定 refresh_token 而不是 authorization_code 作为grant_type。

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>
&grant_type=refresh_token
&refresh_token=<refresh_token>
&scope=https://outlook.office365.com/.default offline_access

下表介绍了这些参数：

参数	必需	说明
TenantID	必需	请求权限的组织。该值可以是 TenantID GUID 或友好名称。
client_id	必需	注册门户分配给应用的客户端 ID。也称为 appId。
grant_type	必需	该值必须为 `refresh_token`。
refresh_token	必需	在步骤 2：兑换令牌的授权代码中，应用在令牌请求期间获得refresh_token。
范围	必需	以空格分隔的范围列表。应用请求的范围必须等效，或者它请求的范围子集（步骤 2：兑换令牌的授权代码）。
client_secret	Web 应用需要	在应用注册门户中为应用创建的客户端密码。

成功的响应包括以下结果：

返回一个新access_token，通常返回一个新refresh_token来替换旧refresh_token。
刷新令牌的持续时间长于访问令牌。机密客户端的默认值约为 90 天，SPA 重定向 URI 的默认值为 24 小时。可以随时吊销令牌，因此请在需要时处理重新身份验证。有关详细信息，请参阅刷新Microsoft 标识平台中的令牌。

客户端凭据流 (仅限应用的)

将此流用于没有用户的服务到服务调用。例如，在管理员同意应用程序权限 (之后， Exchange.ManageAsAppV2) 并分配所需的 RBAC 角色，请使用应用自己的凭据请求令牌。不颁发刷新令牌。根据需要请求新的访问令牌。

若要获取访问令牌，请将 POST 请求发送到 /token 标识平台终结点。在此请求中，客户端使用客户端密码。

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                   # or client assertion (certificate)
&grant_type=client_credentials
&scope=https://outlook.office365.com/.default

下表介绍了这些参数：

参数	条件	说明
TenantID	必需	请求权限的组织。该值可以是 TenantID GUID 或友好名称。
client_id	必需	注册门户分配给应用的应用程序 ID。
范围	必需	具有 `.default` 后缀的资源的应用 ID URI。对于Exchange Online 管理员 API，资源应用 ID URI 为 `https://outlook.office365.com/`，因此范围值为 `https://outlook.office365.com/.default`。此值通知Microsoft 标识平台终结点在访问令牌中包含管理员同意的所有应用级权限。
client_secret	必需	在应用注册门户中为应用生成的客户端密码。验证值是否编码了 URL。
grant_type	必需	该值必须为 `client_credentials`。

步骤 5：使用访问令牌

按照步骤 4：获取访问令牌中所述获取访问令牌后，在授权标头中为每个后续 API 调用添加访问令牌：

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json

 { "CmdletInput": { "CmdletName": "Get-OrganizationConfig" } }

使用 Microsoft 身份验证库 (MSAL)

本文包含手动创建问题原始 HTTP 请求以获取客户端密码令牌时所需的协议详细信息。在生产应用中，使用内置或支持的身份验证库获取安全令牌并调用受保护的 Web API。例如， Microsoft身份验证库 (MSAL) 。

MSAL 和其他支持的身份验证库通过处理详细信息来简化此过程，以便你可以专注于应用的功能。例如：

验证。
Cookie 处理。
令牌缓存。
安全连接。

Microsoft维护大量代码示例，这些代码示例使用Microsoft 标识平台演示支持的身份验证库。若要访问这些代码示例，请参阅Microsoft 标识平台代码示例。

有关如何使用证书获取令牌的示例，请参阅 Microsoft 标识平台和 OAuth 2.0 客户端凭据流。

Last updated on 2025-11-17

通过

Exchange Online 管理员 API 的身份验证和授权

步骤 1：在 Microsoft Entra ID 中注册应用

步骤 2：分配所需的 API 权限

步骤 3：分配 RBAC 权限

委派 (用户) 流的权限

仅限应用流的权限

步骤 4：获取访问令牌

授权代码流 (具有刷新令牌的委托)

步骤 1：向用户发送登录和同意

步骤 2：兑换令牌的授权代码

步骤 3：无提示 (无用户提示) 以静默方式刷新访问令牌

客户端凭据流 (仅限应用的)

步骤 5：使用访问令牌

使用 Microsoft 身份验证库 (MSAL)

其他资源