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 產生。

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：

<openconnector-origin>/oauth/callback

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

http://localhost:3000/oauth/callback

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

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 主控台：

開啟 OpenConnector Web 主控台，例如 http://localhost:3000。
開啟 Providers，選擇要連接的 provider。
點擊 Configure OAuth Client 或 Edit OAuth Client。
貼上 provider app 的 Client ID 和 Client Secret。
點擊 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	使用 web application OAuth client。把 OpenConnector 的準確 redirect URI 加入 authorized redirect URIs。敏感或受限 scopes 在廣泛正式使用前可能需要 Google verification。
Slack	Installing with OAuth	把 OpenConnector 的準確 redirect URI 加到 app redirect URLs 中。如果 Slack 不接受本機 callback URL，請用公開 runtime origin 或 HTTPS tunnel。
GitHub	Creating an OAuth app	GitHub OAuth app 只有一個 authorization callback URL。如果本機、staging 和 production 需要不同 callback URL，建議建立多個 app。
Microsoft	Register an application with the Microsoft identity platform	設定 Web platform redirect URI，並建立 client secret。部分 OpenConnector Microsoft provider 需要 `tenant`，例如 `common`、`organizations` 或特定 tenant ID。
HubSpot	Working with OAuth	Authorization request 裡的 scopes 必須符合 app 已設定的 scopes。正式環境 redirect URL 必須使用 HTTPS；localhost 測試可以使用 HTTP。
Notion	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。