Connector for SaaS 使用指南

Connector for SaaS 是給 SaaS 產品使用的使用者帳號連接方案。適合需要讓每個終端使用者連接自己的 Gmail、Slack、Notion 等第三方帳號，並由產品後端在使用者授權後執行 Connector action 的情境。它在 OOMOL Console 中管理 Project、provider configs、API keys 和 connected accounts；你的後端負責建立授權連結、處理回呼、選擇帳號並發起 action 呼叫。

一次完整接入包含兩部分：先在 OOMOL Console 完成專案和服務設定，再由你的後端建立授權連結、處理回呼、選擇帳號並執行 action。

主要內容：

• 管理員需要在 OOMOL Console 裡準備哪些資源。
• 你的後端需要保存哪些 ID 和密鑰。
• 終端使用者連接帳號時，你的前端和後端分別做什麼。
• 使用者連接完成後，如何選擇帳號並執行 action。
• 出問題時應該查哪些狀態。

接入自製 Agent 時，閱讀ProjectConnector 指南，了解前後端邊界和工具 handler 範例。

接入模型

SaaS 接入分為設定期和執行期。

設定期在 OOMOL Console 完成，用來準備專案、服務設定和後端 API Key，並記錄執行期所需的 ID 和密鑰。終端使用者不會參與這些步驟。

執行期發生在你的產品後端。它代表你的 SaaS Project 建立帳號授權請求、查詢請求狀態和執行 action，請求需要帶 Project API key：

authorization: Bearer <project-api-key>

Project API key 只在你的後端使用。終端使用者只會打開你的產品頁面，或打開 Connector 返回的 OAuth 授權連結。

你需要保存的資料

一次接入通常需要保存這些值：

如果你的使用者可以連接多個 Gmail 帳號，保存每個帳號對應的 connectedAccountId 或 alias，避免執行期只能依賴「最新帳號」預設選擇。

第 1 步：建立專案

Project 是 SaaS 接入的隔離單元，會隔離服務設定、API Keys、連接帳號、執行記錄和用量。

在 OOMOL Console 裡操作：

1. 打開左側「專案」。
2. 點擊「建立專案」。
3. 按表單填寫專案名稱。
4. 建立後進入專案詳情頁，保存專案 ID，後面記為 PROJECT_ID。

專案詳情頁左側會出現「服務設定」「API Keys」「連接帳號」「執行記錄」「用量」等入口。後續設定都在該專案內完成。

專案名稱會顯示在 OAuth 授權入口頁。生產環境建議使用終端使用者能識別的產品名稱，明確授權對象。

第 2 步：建立服務設定

服務設定（後端參數裡的 providerConfig）定義該專案如何連接某個 Connector 服務。以 Gmail OAuth 為例：

1. 在專案詳情頁打開左側「服務設定」。
2. 點擊右上角「建立服務設定」。
3. 按表單選擇或填寫下面這些欄位。
4. 點擊「建立」。

建立完成後，在「服務設定」清單中找到該設定，點擊「服務設定 ID」（providerConfigId）旁的複製按鈕。將複製的完整值儲存為 PROVIDER_CONFIG_ID。後端建立授權連結和執行操作時都建議明確傳入它。設定標識（slug，例如 gmail）是另一個欄位。

每個 SaaS 專案需要使用自己的 OAuth client 時，把「Client 設定來源」改成自訂 Client，並填寫對應的 clientId 和 clientSecret。

使用自訂 OAuth client 時，需要在 provider 後台設定 Connector 的回呼地址。OOMOL Console 或部署設定會提供這個僅供管理員使用的地址。

接入 API key 類型服務時，在「授權類型」裡選擇對應的 API key 模式。終端使用者連接帳號時，你的後端把使用者提供的服務方 API key 交給 Connector 保存。

第 3 步：建立 API Key

Project API key 只給你的後端使用，不能發送到瀏覽器、行動端或終端使用者裝置。

在專案詳情頁裡操作：

1. 打開左側「API Keys」。
2. 點擊「建立 API Key」。
3. 填寫 Key 名稱。建議寫清用途和環境，例如 production server key 或 staging server key，方便後續輪換和排查。
4. 點擊「建立」。
5. 複製一次性彈窗裡的明文 key，後面記為 PROJECT_API_KEY。

明文 key 只返回一次。之後列表裡只會看到 key 前綴、建立時間和最近使用時間等資訊。key 洩露時，在 Console 裡吊銷並重新建立。

第 4 步：讓終端使用者連接帳號

現在進入產品執行時流程。假設你的產品裡有一個使用者 ID 是 customer-1，他要連接自己的 Gmail 帳號。

你的後端建立 OAuth 授權連結：

CONNECTOR=https://connector.oomol.com
PROJECT_API_KEY=oo_proj_...
PROVIDER_CONFIG_ID='<provider-config-id>'

curl -sS -X POST "$CONNECTOR/v1/saas/connected-accounts/link" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -d "{
    \"providerConfigId\": \"$PROVIDER_CONFIG_ID\",
    \"userId\": \"customer-1\",
    \"alias\": \"work\",
    \"returnUri\": \"https://app.example/connector/callback\"
  }"

返回值包含 data.id 和 data.authorizationUrl。跳轉前，可信後端應保存 data.id，並記錄該請求預期的 Project、服務設定和產品使用者；隨後再把使用者跳轉到 Connector 提供的 data.authorizationUrl。

該頁面會短暫展示專案的展示名稱、圖示和服務設定的顯示名稱，然後跳轉到真實 provider OAuth 頁面。使用者授權完成後，provider 會回呼 Connector，Connector 再重定向到你傳入的 returnUri。

成功時，returnUri 會帶上這些 query 參數：

status=success
service=gmail
providerConfigId=pc-1
externalUserId=customer-1
connectedAccountId=ca-1

這些 query 參數只用於展示跳轉結果，不應作為帳號綁定依據。不要直接保存瀏覽器傳回的 connectedAccountId。後端應使用 Project API key 查詢之前保存的連接請求；API 路徑沿用 connection-requests 命名：

curl -sS "$CONNECTOR/v1/saas/connection-requests/$REQUEST_ID" \
  -H "authorization: Bearer $PROJECT_API_KEY"

僅當返回值中的 data.status 為 connected，並且 projectId、providerConfigId、externalUserId 都與後端為該請求保存的值一致時，才持久化 data.connectedAccountId。failed 與 expired 都是終態，不應建立帳號綁定。

如果使用者取消授權或 provider 返回錯誤，returnUri 會帶上：

status=error
code=<connector-error-code>
message=<human-readable-message>

returnUri 只允許 http 或 https。OAuth link 預設 10 分鐘過期。

第 5 步：執行 action

使用者連接成功後，後端即可用保存的帳號執行 action。

CONNECTOR=https://connector.oomol.com
PROJECT_API_KEY=oo_proj_...
PROVIDER_CONFIG_ID='<provider-config-id>'

curl -sS -X POST "$CONNECTOR/v1/saas/actions/gmail.send_email" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -H "x-request-id: req-saas-action-1" \
  -d "{
    \"providerConfigId\": \"$PROVIDER_CONFIG_ID\",
    \"userId\": \"customer-1\",
    \"connectedAccountId\": \"ca-1\",
    \"input\": {
      \"to\": \"someone@example.com\",
      \"subject\": \"Hello\",
      \"body\": \"Hello from My SaaS\"
    }
  }"

規則：

• providerConfigId / service 二選一。生產環境推薦傳 providerConfigId。
• connectedAccountId / alias 最多傳一個。生產環境推薦顯式傳其中一個。
• 如果不傳帳號選擇器，Connector 會選擇同一 projectId + providerConfigId + userId 下最新的 active connected account。
• Action ID 的 service 前綴必須和 provider config 的 service 一致。例如 gmail.send_email 必須使用 Gmail provider config。

成功回應會返回 executionId、actionId 和 action 輸出。可將 executionId 保存到自己的操作日誌中，方便後續排查。

第 6 步：管理使用者連接

產品通常需要展示使用者已連接的帳號。推薦做法是：連接成功後，把回呼裡的 connectedAccountId、alias、service、providerConfigId 和你的 userId 一起保存到業務資料庫，並用這些資料渲染帳號列表。

需要校驗 Connector 側即時狀態時，可在 OOMOL Console 的「連接帳號」頁查看當前專案下的 connected accounts。

返回項裡的 available 表示該帳號當前是否能執行 action。只有 provider config 未刪除、connected account 是 active、底層 app 是 active 且 credential 存在時才是 true。

如果產品允許使用者給帳號改名，建議先在業務資料庫裡更新顯示名；管理員需要核對 Connector 側狀態時，再到 Console 查看對應帳號。

使用者斷開帳號時，建議由產品後端執行斷開流程，並同步更新業務資料庫。管理員排查時可在 Console 查看該帳號是否仍然可用。

Disconnect 會保留 connected account 記錄，但移除底層 credential。歷史日誌仍可關聯到該帳號，後續 action 不能再使用它。

第 7 步：排查和營運

排查某個使用者的 action 問題時，在 OOMOL Console 的「執行記錄」裡查看 execution logs。常見過濾條件包括 providerConfigId、userId、appId、status=success|error 和 action。

排查時至少按服務或服務設定縮小範圍。業務日誌保存了 executionId 時，可以用它把產品側的一次操作和 Connector 側日誌對應起來。

營運時可在「用量」裡查看每日用量趨勢，也可以查看按 service 聚合的用量，常用窗口是 7、30 或 90 天。

days 只支援 7、30、90。

後端執行期要呼叫什麼

這篇指南的 Gmail OAuth 主流程裡，後端需要處理三件事：

• 建立授權連結，把使用者帶到 Connector 授權入口。
• 在回呼後確認授權請求狀態，並保存 connectedAccountId。
• 使用者觸發功能時，用保存的帳號執行 action。

建立專案、建立服務設定、建立 API Key、查看連接帳號、執行記錄和用量這些設定或營運動作，優先於 OOMOL Console 完成。

排查建議

連接或 action 執行失敗時，按這個順序排查：

1. 確認後端使用的是當前 Project 的 PROJECT_API_KEY，並且未放到瀏覽器或行動端。
2. 確認請求中的 providerConfigId 使用複製的服務設定 ID，未誤用設定標識（slug）。
3. 確認對同一使用者設定了唯一的 alias。
4. 在 Console 的「連接帳號」裡查看帳號是否仍然可用。
5. 在 Console 的「執行記錄」裡按服務設定、使用者 ID 或 executionId 查詢失敗原因。

透過 SaaS Proxy 呼叫供應商 API.