---
title: 為 OpenConnector 建立 Microsoft OAuth app
description: 為 Outlook、OneDrive、Excel 等 OOMOL OpenConnector Microsoft Graph
  provider 註冊 Microsoft Entra application。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/openconnector-microsoft-oauth-app/
markdown_url: https://oomol.com/zh-tw/docs/openconnector-microsoft-oauth-app.md
---

# 為 OpenConnector 建立 Microsoft OAuth app

當 OpenConnector 需要連接 Outlook、OneDrive 或 Excel 等 Microsoft Graph provider 時，使用 Microsoft Entra app registration。

## OpenConnector services

| Service ID | Provider | Extra client field |
| --- | --- | --- |
| `outlook` | Outlook | `tenant` |
| `one_drive` | OneDrive | `tenant` |
| `excel` | Excel | `tenant` |

`tenant` 是 authorization 和 token URL 中使用的 Microsoft identity platform tenant segment。常見值包括 `common`、`organizations`、`consumers` 或具體 tenant ID。

## 前置條件

- 一個正在運行的 OpenConnector runtime。
- 可以存取 Microsoft Entra admin center 或 Azure app registrations。
- 有權限註冊 app 和建立 client secret。
- 使用者在瀏覽器中開啟的 OpenConnector origin，例如 `http://localhost:3000` 或 `https://connect.example.com`。

## 第 1 步：確定 OpenConnector callback URL

在 OpenConnector origin 後拼接 `/oauth/callback`，得到 callback URL。本地測試使用 `http://localhost:3000/oauth/callback`。公開部署時，請先設定 `OOMOL_CONNECT_ORIGIN`，重新啟動 OpenConnector 後使用公開 callback URL，例如 `https://connect.example.com/oauth/callback`。

## 第 2 步：註冊 Microsoft app

在 [Microsoft Entra admin center](https://entra.microsoft.com/) 中：

1. 開啟 **App registrations**。
2. 建立新的 registration。
3. 選擇適合目標使用者的 supported account type。
4. 新增一個 **Web** redirect URI，值為 OpenConnector 的準確 callback URL。
5. 註冊 app。
6. 開啟 **Certificates & secrets**，建立 client secret。
7. 開啟 **API permissions**，新增 OpenConnector service 需要的 delegated Microsoft Graph permissions。

Microsoft 官方文件見 [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2)。Microsoft 授權碼流程要求 auth request 裡的 redirect URI 符合已註冊 redirect URI。

## 第 3 步：複製 client values

| Microsoft 欄位 | OpenConnector 欄位 |
| --- | --- |
| Application client ID | `clientId` |
| Client secret value | `clientSecret` |
| Tenant segment | `extra.tenant` |

建立 client secret 後立刻複製 secret value。Microsoft 後續不會再次顯示完整 secret value。

## 第 4 步：在 OpenConnector 中儲存 client

OpenConnector 的 Microsoft providers 需要額外的 `tenant` 值。請使用能在 OAuth client 表單中顯示 `tenant` 欄位的 OpenConnector 主控台版本，再按本文繼續設定。

1. 開啟 OpenConnector Web 主控台，例如 `http://localhost:3000`。
2. 開啟 **Providers**，選擇 **Outlook**、**OneDrive** 或 **Excel**。
3. 點擊 **Configure OAuth Client** 或 **Edit OAuth Client**。
4. 貼上 Microsoft application client ID 和 client secret value。
5. 在 **Tenant** 中填寫 `common`、`organizations`、`consumers` 或你的 tenant ID。
6. 點擊 **Save OAuth Client**。

設定 `one_drive` 或 `excel` 時，在對應 provider 頁面重複這些步驟。

## 第 5 步：連接並測試

儲存 OAuth client config 後，在 Microsoft provider 頁面點擊 **Connect**。登入 Microsoft 帳號，批准 consent，回到 OpenConnector，並確認 provider 頁面顯示帳號已連接。

執行 Microsoft Graph action 前，先查看主控台裡的 action 詳情。如果你的 catalog 版本沒有 `outlook.list_messages`，請選擇該 provider 目前顯示的其他讀取 action。

## 排查建議

| 現象 | 檢查項 |
| --- | --- |
| Microsoft 提示 redirect URI 無效 | 在 app registration 中新增準確的 `<openconnector-origin>/oauth/callback` URL，平台類型選擇 Web。 |
| 目標使用者無法登入 | 檢查 app 的 supported account type，以及 OpenConnector 儲存的 `tenant` 值。 |
| 需要 admin consent | 某些 Microsoft Graph permissions 或 tenant policy 要求管理員同意，請讓 tenant admin 審核 app。 |
| Token request 失敗 | 確認儲存了目前 client secret value；secret ID 只用於識別這條 secret 記錄。 |
| Action 提示權限不足 | 新增所需 delegated API permissions，完成 consent，然後重新連接 Microsoft 帳號。 |