OOMOL Connector SaaS ガイド

OOMOL Connector SaaS は、SaaS 製品向けのアカウント接続レイヤーです。各エンドユーザーが自分の Gmail、Slack、Notion、またはその他の第三者アカウントを接続し、認可後に backend が Connector actions を実行する必要がある場合に使用します。OOMOL Console は projects、provider configs、API keys、connection records を管理し、backend は authorization links の作成、callbacks の処理、accounts の選択、action calls の開始を行います。

完全な統合は 2 つの部分で構成されます。まず OOMOL Console で project と service を設定し、次に backend が authorization links を作成し、callbacks を処理し、accounts を選択し、actions を実行します。

主な内容:

• 管理者が OOMOL Console で準備する resources。
• backend が保存する必要のある IDs と secrets。
• エンドユーザーが account を接続するときに frontend と backend が行うこと。
• 接続済み account を選択して action を実行する方法。
• トラブルシューティングに役立つ Console pages、statuses、logs、usage views。

統合モデル

SaaS 統合には setup phase と runtime phase があります。

setup phase は OOMOL Console で行います。project、provider config、backend API key を準備し、runtime に必要な IDs と secrets を記録します。エンドユーザーはこれらの手順に関与しません。

runtime phase は製品 backend で行います。account links の作成、connection request status の読み取り、actions の実行時に SaaS project を表します。runtime requests には project API key が含まれます。

authorization: Bearer <project-api-key>

project API key は backend に保持します。エンドユーザーは製品 UI を使うか、Connector が返す OAuth authorization URL を開くだけです。

保存するデータ

一般的な統合では以下の値を保存します。

ユーザーが複数の Gmail accounts を接続できる場合、各 account の connectedAccountId または alias を保存し、runtime calls がデフォルトの「最新 account」選択に依存しないようにします。

ステップ 1: project を作成する

project は SaaS 統合の隔離境界です。provider configs、API keys、connected accounts、execution logs、usage を隔離します。

OOMOL Console で:

1. 左サイドバーから Projects を開きます。
2. Create project をクリックします。
3. project name を入力します。
4. 作成後、project を開き、project ID を PROJECT_ID として保存します。

project page には Provider configs、API Keys、Connected accounts、Execution logs、Usage などの項目があります。残りの setup はこの project 内で行います。

project name は OAuth authorization entry page に表示されます。本番統合では、エンドユーザーが認識できる product name を使い、authorization target を明確にしてください。

ステップ 2: provider config を作成する

provider config は、この project が 1 つの Connector service に接続する方法を定義します。runtime requests では providerConfigId として渡します。Gmail OAuth の場合:

1. project sidebar から Provider configs を開きます。
2. Create provider config をクリックします。
3. 以下の fields を選択または入力します。
4. Create をクリックします。

作成後、provider config ID を PROVIDER_CONFIG_ID として保存します。backend は authorization links の作成と actions 実行時に明示的に渡すべきです。

各 SaaS project が独自の OAuth client を使う場合、Client config source を custom client に変更し、対応する clientId と clientSecret を提供します。

custom OAuth client では、provider console に Connector callback URL を設定します。OOMOL Console または deployment configuration がその URL を提供します。エンドユーザーはこの URL を必要としません。

API-key service では、対応する API-key auth type を選択します。エンドユーザーが account を接続するとき、backend はユーザーの provider API key を Connector に送信して保存します。

ステップ 3: project API key を作成する

project API key は backend 専用です。browsers、mobile clients、エンドユーザーの devices には送信しないでください。

project page で:

1. project sidebar から API Keys を開きます。
2. Create API Key をクリックします。
3. key name を入力します。production server key や staging server key など、rotation と troubleshooting がしやすい名前を使います。
4. Create をクリックします。
5. 1 回だけ表示される dialog から平文 key をコピーし、PROJECT_API_KEY として保存します。

平文 key は 1 回だけ返されます。以後の一覧には key prefix、creation time、recent usage time などの metadata だけが表示されます。key が漏れた場合は Console で revoke し、新しい key を作成してください。

ステップ 4: エンドユーザーに account を接続させる

ここからは product runtime flow です。製品に customer-1 という ID の user がいて、Gmail を接続したいとします。

backend は OAuth authorization link を作成します。

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"
  }'

response には Connector 所有の authorization entry URL である data.authorizationUrl が含まれます。エンドユーザーをこの URL にリダイレクトします。

この page は project display title、project icon、provider config display name を短く表示し、その後実際の provider OAuth page にリダイレクトします。ユーザーが認可すると、provider は Connector に callback し、Connector は指定された returnUri にリダイレクトします。

成功時、returnUri は次のような query parameters を受け取ります。

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

frontend は connectedAccountId を backend に送信して保存できます。backend は connection request status を問い合わせることもできます。

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

ユーザーがキャンセルした場合や provider が error を返した場合、returnUri は次を受け取ります。

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

returnUri は http または https を使う必要があります。OAuth links はデフォルトで 10 分後に期限切れになります。

ステップ 5: action を実行する

account が接続された後、backend は保存済み account selector で actions を実行できます。

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 のどちらか 1 つだけを渡します。本番統合では providerConfigId を優先してください。
• connectedAccountId または alias は多くても 1 つだけ渡します。本番統合ではどちらかを明示的に渡してください。
• account selector がない場合、Connector は同じ projectId + providerConfigId + userId 配下の最新 active connected account を選びます。
• action ID の service prefix は provider config service と一致する必要があります。たとえば gmail.send_email は Gmail provider config を使う必要があります。

success response には executionId、actionId、action output が含まれます。support と troubleshooting のために、executionId を自社 operation logs に保存してください。

ステップ 6: user connections を管理する

製品では通常、ユーザーに接続済み accounts を表示する必要があります。推奨される方法は、成功 callback 後に connectedAccountId、alias、service、providerConfigId、自社の userId を製品 database に保存し、そのデータから account list を表示することです。

Connector 側の状態を確認するには、OOMOL Console の Connected accounts で現在の project 配下の connected accounts を確認します。

available field は、その account が現在 actions を実行できるかを示します。provider config が active、connected account が active、underlying app が active、credential が存在する場合にのみ true になります。

製品でユーザーが accounts の名前を変更できる場合は、まず製品 database の display name を更新します。管理者が Connector 側の状態を確認する必要がある場合は、Console で対応 account を確認します。

ユーザーが account を disconnect する場合、製品 backend で disconnect flow を実行し、製品 database を更新します。管理者は Console で account がまだ available か確認できます。

Disconnect は connected account record を保持しますが、underlying credential を削除します。過去の logs は account を参照できますが、future actions では使用できません。

ステップ 7: トラブルシューティングと運用

ユーザーの action をトラブルシュートするときは、OOMOL Console の Execution logs を開きます。よく使う filters は providerConfigId、userId、appId、status=success|error、action です。

troubleshooting では、まず service または provider config で表示を絞ります。operation logs に executionId を保存している場合、それを使って product-side operation と Connector-side log を結び付けます。

運用では Usage を使い、daily usage trends と service ごとの usage を確認します。一般的な windows は 7、30、90 日です。

days は 7、30、90 のみをサポートします。

runtime で backend が呼び出すもの

このガイドの Gmail OAuth flow では、backend は 3 つの job を処理します。

• authorization link を作成し、ユーザーを Connector authorization entry に送る。
• callback 後に connection request を確認し、connectedAccountId を保存する。
• ユーザーが product feature をトリガーしたとき、保存済み account で actions を実行する。

project 作成、provider config 作成、project API key 作成、connected accounts の確認、execution logs の読み取り、usage の確認などの setup と operations には OOMOL Console を優先してください。

トラブルシューティング

account connection または action execution が失敗した場合は、以下の順序で確認します。

1. backend が現在の project の PROJECT_API_KEY を使用しており、その key が browsers や mobile clients に露出していないことを確認します。
2. request が作成した provider config の providerConfigId を使用していることを確認します。
3. 同じ user が既存の alias を再利用していないことを確認します。
4. Console の Connected accounts を開き、account がまだ available か確認します。
5. Console の Execution logs を開き、provider config、user ID、または executionId で filter します。