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。
• 出问题时应该查哪些状态。

接入模型

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. 点击「创建」。

创建完成后保存 provider config ID，后面记为 PROVIDER_CONFIG_ID。后端创建授权链接和执行 action 时都推荐显式传它。

每个 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_...

curl -sS -X POST "$CONNECTOR/v1/saas/connected-accounts/link" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -d '{
    "providerConfigId": "pc-1",
    "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。

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": "pc-1",
    "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。
3. 确认为同一用户配置了唯一的 alias。
4. 在 Console 的「连接账号」里查看账号是否仍然可用。
5. 在 Console 的「执行记录」里按服务配置、用户 ID 或 executionId 查询失败原因。