Exchange Online 管理員 API 的認證與授權

注意事項

本文所述的功能目前處於預覽階段，並非所有組織都能提供，且可能會有所變動。

本文將介紹使用Exchange Online 管理員 API 端點時的認證與授權要求。

Exchange Online 管理員 API 提供基於 REST 的方式來執行特定 PowerShell 指令，取代舊有的 Exchange Web Services (EWS) 情境。欲了解更多資訊，請參閱 Exchange Online 管理員 API 概述。

要存取管理員 API，您的應用程式必須建立身份、取得正確權限，並遵循安全令牌處理的最佳實務。大致而言，此過程包含以下幾個關鍵步驟：

Register an app in Microsoft Entra ID

建立應用程式註冊，建立應用程式的身份，並設定憑證 (用戶端秘密或憑證) 。此註冊可讓您的應用程式向 Microsoft Entra ID 請求令牌。
指派必要的 API 權限

在您的應用程式註冊中加入必要的 OAuth 範圍：
- 委派流量： Exchange.ManageV2。
- 僅應用程式的流程： Exchange.ManageAsAppV2。
步驟 3：指派 RBAC 權限

Exchange Online 使用基於角色的存取控制 (RBAC) 來判斷呼叫者可管理哪些端點、指令列（cmdlet）及物件。將適當的 RBAC 角色分配給使用者 (以進行委派存取) ，或將應用程式的服務主體 (分配給僅應用程式存取) 。
步驟四：取得存取權憑證

使用 OAuth 2.0 流程從 Microsoft Entra ID 取得令牌：
- 委託流程以供使用者存取。
- 僅用應用程式的流程進行服務對服務存取。
步驟五：使用存取權杖

步驟 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 (可選) ：委派流程所必需。
  - 平台：選擇網頁。
  - URI：例如，輸入存取權杖寄出 (的網址， 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 範圍讓你的應用程式取得 token，但 RBAC 決定呼叫者能管理哪些 cmdlet 和物件。若沒有適當的 RBAC 角色指派，即使是有效的標記也會因錯誤訊息失敗： 403 禁止。

根據你的應用程式性質，請依照以下小節中的步驟操作。

委派 (使用者) 流程的權限

對於委託情境，應用程式代表其取得令牌的使用者必須在 Exchange Online 中擁有必要的 RBAC 角色。常見角色範例：

信箱與資料夾操作的收件人管理。
組織管理，適用於組織層級的環境。
僅視組織管理，用於唯讀組織運作。

透過 Exchange 管理中心或 Exchange Online PowerShell 指派這些角色。關於教學，請參閱管理 Exchange Online 中的角色群組。

僅限應用程式流程的權限

對於僅應用程式的情況，代表你應用程式的服務主體必須擁有足夠的權限。您有下列選項：

為簡化而 (推薦Microsoft Entra角色分配) ：為企業應用程式賦予內建的Microsoft Entra角色。例如，Exchange 管理員可取得完整 Exchange Online 權限：
1. 在Microsoft Entra 系統管理中心中https://entra.microsoft.com，選擇管理員 & 角色。
2. 關於 角色與管理者 |在所有角色 頁面，請點擊該行中除第一欄旁勾選框以外的任何位置，選擇 Exchange 管理員 角色。
3. 關於 交易所管理員 | 開啟的分配頁面，選擇 新增分配，選擇你的應用程式，然後選擇確認。
將內建或自訂的 Exchange RBAC 角色群組分配 (權限最小) ：在 Exchange Online 中建立或使用現有的自訂角色群組，這些群組只包含應用程式所需的 cmdlet，並將服務主體加入這些群組。此方法避免廣泛權限，並與最低權限安全相符。欲了解更多資訊，請參閱 Exchange Online PowerShell 中的僅 App 認證。

下表列出每個端點所需的內建 RBAC 角色。

端點	必要交換角色群組
/組織配置 /AcceptedDomain	僅限檢視組織管理
/信箱 /MailboxFolderPermission /DistributionGroupMember /動態分配群組成員	收件者管理

若想更細緻地控制，建議使用自訂角色群組，只包含特定管理角色 (指令集，) 你的應用程式需求。此方法遵循最低權限安全，且相較於 Exchange 管理員或全球管理員等超出一般管理員 API 操作範圍的廣泛角色，降低風險。

步驟四：取得存取權憑證

要呼叫 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 身分識別平台中的範圍與權限。

使用者需要授權應用程式代表他們行事。該應用程式會將使用者重新導向到 Microsoft 身分識別平台中的端點/authorize。透過這個端點，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 GUID 或友善名稱。
client_id	必要	由註冊入口網站指派給應用程式的客戶 ID。也稱為 appId。
response_type	必要	必須包含 OAuth 2.0 授權碼流程的值 `code` 。
redirect_uri	建議	應用程式以 URL 編碼格式的重定向 URI，應用程式會傳送與接收認證回應。它必須符合你在應用程式註冊入口網站註冊的重定向 URI。
範圍	必要	一份空間分隔的 API 權限清單，列出你希望使用者同意的 Exchange Online 管理員 API。這些權限可以包括資源權限 (`https://outlook.office365.com/.default` ，在此情境中) 及 OIDC 範圍，例如 `offline_access`，表示應用程式需要一個刷新令牌以維持資源的長效存取。
response_mode	建議	指定將產生的權杖回傳給應用程式的方法。有效的值為 `query` 或 `form_post`。
州	建議	請求中包含的值也會在標記回應中回傳。它可以是任意內容的串。通常會使用隨機且唯一的值來防止跨站請求偽造攻擊。此屬性同時編碼使用者在驗證請求發生前應用程式的狀態資訊，例如他們所處的頁面或視圖。

使用者登入並同意。 Microsoft Entra ID 會重新導向到 your redirect_uri with ?code=<authorization_code>.
使用 offline_access 後續可啟用刷新令牌。欲了解更多資訊，請參閱 Microsoft 身分識別平台中的刷新令牌及 Microsoft 身分識別平台中的範圍與權限。

步驟二：兌換授權碼兌換代幣

應用程式會利用前一步的授權碼，透過向端點發送 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 GUID 或友善名稱。
client_id	必要	由註冊入口網站指派給應用程式的客戶 ID。也稱為 appId。
grant_type	必要	該值必須是 `authorization_code` 授權碼流程的。
範圍	必要	一份空間分隔的示波器清單。您的應用程式請求的範圍必須等同於步驟 1：送使用者登入並同意時所請求的範圍。
code	必要	你在第一步取得的授權碼：讓使用者登入並同意。
redirect_uri	必要	就是你在步驟 1：讓使用者登入並同意時用來取得授權碼的重定向 URI 值。
client_secret	網頁應用程式的必備功能	你在應用程式註冊入口網站建立的客戶端秘密。

成功的回應包括：

access_token：承載者。通常大約60分鐘。
refresh_token：出席，因為 offline_access 是被要求的。
id_token：隨意的。如果有人要求內視鏡 openid ，我會退回。欲了解更多資訊，請參閱 Microsoft 身分識別平台中的 Microsoft 身分識別平台應用程式類型、認證流程及刷新令牌。

提示

將 TenantID (tid 存) 代幣權利的值。你需要它來建立管理員 API 網址和未來的權杖請求。欲了解更多資訊，請參閱 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 GUID 或友善名稱。
client_id	必要	由註冊入口網站指派給應用程式的客戶 ID。也稱為 appId。
grant_type	必要	值必須為 `refresh_token`。
refresh_token	必要	你的應用程式在第 2 步的代幣請求中獲得的 refresh_token：兌換授權碼兌換代幣。
範圍	必要	一份空間分隔的示波器清單。你的應用程式請求的範圍必須等同於或其在步驟 2：兌換授權碼以代幣兌換時所請求範圍的子集。
client_secret	網頁應用程式的必備功能	你在應用程式註冊入口網站建立的客戶端秘密。

成功的回應包括以下結果：

還會退回新的access_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 GUID 或友善名稱。
client_id	必要	申請ID是由註冊入口網站分配給該應用程式的。
範圍	必要	應用程式 ID 的資源 `.default` URI 加上後綴。對於 Exchange Online 管理員 API，資源應用程式 ID 的 URI 是 `https://outlook.office365.com/`，因此作用域值為 `https://outlook.office365.com/.default`。此值通知 Microsoft 身分識別平台端點，將管理員同意的所有應用程式層級權限納入存取權杖中。
client_secret	必要	你在應用程式註冊入口網站產生的客戶端秘密。確認這個值是 URL 編碼的。
grant_type	必要	值必須為 `client_credentials`。

步驟五：使用存取權杖

在取得第 4 步所述的存取權杖後，請在每次後續 API 呼叫的授權標頭中包含該存取權杖：

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

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

使用 MSAL (Microsoft 認證函式庫)

本文包含了在手動建立原始 HTTP 請求以取得用戶端秘密權杖時所需的協定細節。在正式應用中，使用內建或支援的認證函式庫來取得安全權杖並呼叫受保護的網頁 API。例如， Microsoft 認證函式庫 (MSAL) 。

MSAL 及其他支援的認證函式庫透過處理細節簡化流程，讓你能專注於應用程式的功能。例如：

肯定。
餅乾處理。
代幣快取。
安全連結。

Microsoft 維護了大量程式碼範例，展示支援 Microsoft 身分識別平台的認證函式庫。要存取這些程式碼範例，請參閱 Microsoft 身分識別平台程式碼範例。

關於如何利用憑證取得憑證的範例，請參閱 Microsoft 身分識別平台及 OAuth 2.0 用戶端憑證流程。

Last updated on 2025-11-17

共用方式為

Exchange Online 管理員 API 的認證與授權

步驟 1：在 Microsoft Entra ID 註冊應用程式

步驟 2：指派必要的 API 權限

步驟 3：指派 RBAC 權限

委派 (使用者) 流程的權限

僅限應用程式流程的權限

步驟四：取得存取權憑證

授權碼流程 (以刷新令牌委派)

步驟 1：讓使用者登入並同意

步驟二：兌換授權碼兌換代幣

步驟 3：靜默刷新存取權杖 (無使用者提示)

用戶端憑證流程 (應用程式專用)

步驟五：使用存取權杖

使用 MSAL (Microsoft 認證函式庫)

其他資源