---
title: OpenConnector OAuth app 設定指南
description: 建立 provider OAuth app，設定回呼位址，並連線到自部署的 OOMOL OpenConnector runtime。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/openconnector-oauth-apps/
markdown_url: https://oomol.com/zh-tw/docs/openconnector-oauth-apps.md
---

# OpenConnector OAuth app 設定指南

當 OAuth2 provider 需要使用者授權時，OOMOL OpenConnector 會使用你自己在 provider 後台建立的 OAuth app。你需要在 provider 的 developer console 中建立 app，把 OpenConnector runtime 提供的準確 callback URL 填到 provider app 裡，再把 app 的 client 設定儲存到 OpenConnector。

這篇指南適用於 Gmail、Google Drive、Google Calendar、Slack、HubSpot、GitHub、Microsoft Outlook、Notion、Zoom、Zendesk、Jira、Dropbox，以及 OpenConnector provider catalog 中展示的其他 OAuth2 provider。

本文只涵蓋 OAuth app 設定。使用其他驗證方式的 provider，請依 OpenConnector provider 頁面顯示的 credential 欄位設定。

## 你需要準備什麼

- 一個正在運行的 OOMOL OpenConnector runtime。
- 可以存取 OpenConnector Web 主控台。
- 如果設定了 `OOMOL_CONNECT_ADMIN_TOKEN`，需要準備 admin token。
- 擁有在目標 provider developer 或 admin console 中建立 OAuth app 的權限。
- 一個用於測試連線的 provider 帳號、workspace、tenant、organization 或 portal。

如果 runtime 透過公開網域、tunnel 或 Cloudflare Worker URL 存取，請先設定 `OOMOL_CONNECT_ORIGIN`，再建立 provider OAuth app。Redirect URI 會基於這個 origin 產生。

```bash
OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build
```

## 第 1 步：確定 OpenConnector callback URL

用使用者在瀏覽器中開啟的 OpenConnector origin 拼出 callback URL：

```text
<openconnector-origin>/oauth/callback
```

預設本機 runtime 下，多數 OAuth provider 使用：

```text
http://localhost:3000/oauth/callback
```

設定 `OOMOL_CONNECT_ORIGIN` 後，callback URL 會使用對應的公開 origin：

```text
https://connect.example.com/oauth/callback
```

把這個準確的 callback URL 填入 provider OAuth app。除非你的 OpenConnector origin 本身帶結尾斜線，否則不要額外加上結尾斜線。

## 第 2 步：建立 provider OAuth app

開啟 provider 的 developer console，建立 OAuth app、integration、connected app、public app 或 application registration。不同 provider 的命名不同，但通常需要填寫同一類欄位。

| Provider app 欄位 | 填寫內容 |
| --- | --- |
| App name | 你能識別的名稱，例如 `OpenConnector Local` 或內部工具名稱。 |
| Homepage 或 website URL | 你的產品、內部工具、程式碼倉庫或 runtime URL。使用使用者和管理員能識別的值。 |
| Redirect URI、callback URL 或 reply URL | OpenConnector 的準確 callback URL，例如 `https://connect.example.com/oauth/callback`。 |
| Scopes 或 permissions | OpenConnector provider 需要的 scopes。可從 provider 頁面或 action guide 中複製。 |
| Distribution、install 或 visibility | 如果 provider 允許，而且你只連接自己的帳號，可保持 private、test-only、internal 或 unlisted。 |

很多 provider 允許你在 marketplace 上架前，先授權自己的帳號、測試使用者、workspace 或 organization。某些 provider 仍會因為敏感 scopes、正式環境使用、廣泛客戶分發或受管理 workspace，要求驗證、管理員核准或審核。Provider 授權頁和管理 console 是最終準確資訊。

## 第 3 步：複製 client 設定

建立 provider app 後，複製 OpenConnector 需要的 client 值。

| 值 | 是否必需 | 說明 |
| --- | --- | --- |
| `clientId` | 是 | 通常叫 Client ID、App ID、Application ID 或 Consumer Key。 |
| `clientSecret` | 通常需要 | 某些 provider 使用 public-client flow，不要求 secret。如果 OpenConnector 把該 provider 的 secret 標為選用，且 provider 端也明確不要求 secret，才可以留空。 |
| Extra fields | 有時需要 | 某些 provider 還需要額外 OAuth client 設定，例如 `tenant`、`subdomain`、`developerToken` 或帳號識別碼。請使用能展示該 provider 所需欄位的主控台版本。 |

不要把 OAuth client secret 放到瀏覽器程式碼、公開倉庫、截圖、issue 或 Agent prompt 中。

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

一般設定優先使用 OpenConnector Web 主控台：

1. 開啟 OpenConnector Web 主控台，例如 `http://localhost:3000`。
2. 開啟 **Providers**，選擇要連接的 provider。
3. 點擊 **Configure OAuth Client** 或 **Edit OAuth Client**。
4. 貼上 provider app 的 **Client ID** 和 **Client Secret**。
5. 點擊 **Save OAuth Client**。

如果 provider 需要額外 client 欄位，請在同一個 OAuth client 表單中填寫。例如 Microsoft provider 需要 `tenant` 值。如果你的主控台沒有展示 provider 必需欄位，請先升級到支援該 provider 完整 OAuth client 表單的 OpenConnector 版本，再繼續設定。

儲存後，provider 頁面會顯示 OAuth client 已設定。已儲存的 client secret 不會再次顯示。

## 第 5 步：連接測試帳號

儲存 OAuth client 後，停留在 provider 頁面並點擊 **Connect** 啟動授權。在 provider 授權頁核准授權。Provider 跳回 OpenConnector 後，確認 provider 頁面顯示帳號已連接。

## 第 6 步：測試 action

使用 provider 頁面或主控台 action 清單，執行一個低風險讀取 action。Action 詳情會顯示輸入 schema、需要的 scopes 和目前連接身分。

測試寫入類 action 時請使用 demo data。

## Provider 說明

建立 OAuth app 時，這些官方文件比較有用：

| Provider 類型 | 官方文件 | 常見設定點 |
| --- | --- | --- |
| Google APIs | [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server) | 使用 web application OAuth client。把 OpenConnector 的準確 redirect URI 加入 authorized redirect URIs。敏感或受限 scopes 在廣泛正式使用前可能需要 Google verification。 |
| Slack | [Installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth) | 把 OpenConnector 的準確 redirect URI 加到 app redirect URLs 中。如果 Slack 不接受本機 callback URL，請用公開 runtime origin 或 HTTPS tunnel。 |
| GitHub | [Creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) | GitHub OAuth app 只有一個 authorization callback URL。如果本機、staging 和 production 需要不同 callback URL，建議建立多個 app。 |
| Microsoft | [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2) | 設定 Web platform redirect URI，並建立 client secret。部分 OpenConnector Microsoft provider 需要 `tenant`，例如 `common`、`organizations` 或特定 tenant ID。 |
| HubSpot | [Working with OAuth](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) | Authorization request 裡的 scopes 必須符合 app 已設定的 scopes。正式環境 redirect URL 必須使用 HTTPS；localhost 測試可以使用 HTTP。 |
| Notion | [Authorization](https://developers.notion.com/guides/get-started/authorization) | 建立 public connection，並在 OAuth configuration 中加入 OpenConnector redirect URI。在自己的 workspace 之外使用前，請檢查 Notion 目前的 app type 和 capability 規則。 |

## 疑難排解建議

| 現象 | 檢查項目 |
| --- | --- |
| Provider 提示 `redirect_uri_mismatch`、invalid redirect URI 或 invalid callback URL。 | 確認 provider app 使用的是 `<openconnector-origin>/oauth/callback`。Scheme、host、port、path 和結尾斜線必須和他在瀏覽器中開啟的 origin 一致。 |
| Provider 拒絕 `http://localhost`。 | 使用支援 localhost 測試的 provider，或透過 HTTPS tunnel / 公開網域暴露 runtime，並在重啟 OpenConnector 前把 `OOMOL_CONNECT_ORIGIN` 設定為該 origin。 |
| Provider 提示 app 未驗證、未核准或 workspace 不允許。 | 檢查 provider 端 app distribution、test users、workspace app approval 和敏感 scope review 要求。Marketplace 上架通常和私有測試是兩回事，但具體規則以 provider 為準。 |
| 授權成功，但 action 因 missing 或 insufficient scopes 失敗。 | 把該 action 需要的 scopes 加到 provider app 中，儲存後重新連接 provider 帳號，讓新 scopes 生效。 |
| OpenConnector 提示 `oauth_client_config_not_found`。 | 確認你已經在啟動 **Connect** 的同一個 provider 頁面儲存了 OAuth client。 |
| 後續 token refresh 失敗。 | 確認 provider 發放了 refresh token。某些 provider 需要 offline-access 參數或重新 consent。沒有 refresh token 時，請重新連接帳號。 |
| 執行 action 時用了錯誤帳號。 | 使用已登入目標帳號的瀏覽器 profile 重新連接，然後在主控台中選擇目標連接再測試 action。 |

## 安全檢查

- 儲存 OAuth client secrets 或 connected account credentials 前，先設定 `OOMOL_CONNECT_ENCRYPTION_KEY`。
- 保護 `OOMOL_CONNECT_ADMIN_TOKEN`，`/v1` 和 `/mcp` 呼叫使用 runtime token。
- 在 provider 和 OpenConnector action set 允許時，使用最小權限 scopes。
- 如果 provider callback 規則讓環境難以區分，為 local、staging 和 production 使用不同 OAuth app，方便稽核。
- 刪除不再使用的 provider app、舊 client secret 和過期 OpenConnector connection。