OpenConnector OAuth app 設定ガイド

OAuth2 provider で user authorization が必要な場合、OOMOL OpenConnector は自分の provider OAuth app を使用します。provider の developer console で app を作成し、OpenConnector runtime の正確な callback URL を app にコピーして、その client configuration を OpenConnector に保存します。

このガイドは、Gmail、Google Drive、Google Calendar、Slack、HubSpot、GitHub、Microsoft Outlook、Notion、Zoom、Zendesk、Jira、Dropbox、および OpenConnector provider catalog に表示されるその他の OAuth providers に使用します。

このガイドでは OAuth app setup を説明します。別の auth type を使用する providers では、OpenConnector provider page に表示される credential fields を使用してください。

必要なもの

実行中の OOMOL OpenConnector runtime。
OpenConnector web console へのアクセス。
OOMOL_CONNECT_ADMIN_TOKEN が設定されている場合は admin token。
provider の developer または admin console で OAuth app を作成する permission。
接続する provider workspace、tenant、organization、portal の test account。

runtime が public domain、tunnel、Cloudflare Worker URL からアクセスできる場合は、provider OAuth apps を作成する前に OOMOL_CONNECT_ORIGIN を設定してください。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 を設定する

users が browser で開く origin から callback URL を作成します。

<openconnector-origin>/oauth/callback

default local runtime では次の URL を使用します。

http://localhost:3000/oauth/callback

OOMOL_CONNECT_ORIGIN に public origin を設定すると、callback URL はその origin を使用します。

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

provider OAuth app に、この callback URL を正確に入力します。OpenConnector origin 自体に trailing slash が含まれていない限り、末尾に slash を追加しないでください。

手順 2：provider OAuth app を作成する

provider の developer console を開き、OAuth app、integration、connected app、public app、application registration のいずれかを作成します。名称は provider によって異なりますが、必要な fields は通常同じです。

Provider app field	入力内容
App name	`OpenConnector Local` や internal tool name など、識別できる名前。
Homepage または website URL	product、internal tool、repository、runtime URL。users と admins が識別できる値を使用します。
Redirect URI、callback URL、reply URL	`https://connect.example.com/oauth/callback` など、正確な OpenConnector callback URL。
Scopes または permissions	OpenConnector provider が必要とする scopes。provider page または provider action guide からコピーします。
Distribution、install、visibility	自分の accounts だけを使用し、provider が許可する場合は、app を private、test-only、internal、unlisted に保ちます。

多くの providers では、marketplace listing の前に、自分の account、test users、workspace、organization を認証できます。sensitive scopes、production use、広範な customer distribution、managed workspaces には、verification、admin approval、review が必要な場合があります。provider の authorization screen と admin console が正確な情報源です。

手順 3：client configuration をコピーする

provider app を作成した後、OpenConnector に必要な client values をコピーします。

Value	必須	Notes
`clientId`	はい	通常は Client ID、App ID、Application ID、Consumer Key と呼ばれます。
`clientSecret`	通常	一部の providers は public-client flows を使用し、secret を必要としません。OpenConnector で provider secret が optional と表示される場合も、provider 側でも optional のときだけ空にします。
Extra fields	場合による	`tenant`、`subdomain`、`developerToken`、account-specific identifiers など、追加の OAuth client config が必要な providers があります。必要な fields を表示できる console version を使用してください。

OAuth client secrets を browser code、public repositories、screenshots、issue reports、Agent prompts に含めないでください。

手順 4：OAuth client を OpenConnector に保存する

通常の setup path では OpenConnector web console を使用します。

http://localhost:3000 などの OpenConnector web console を開きます。
Providers を開き、接続する provider を選択します。
Configure OAuth Client または Edit OAuth Client を選択します。
provider app の Client ID と Client Secret を貼り付けます。
Save OAuth Client を選択します。

provider が extra client fields を必要とする場合は、同じ OAuth client form に入力します。たとえば、Microsoft providers では tenant value が必要です。provider が必要とする field が console に表示されない場合は、完全な OAuth client form に対応する OpenConnector version に upgrade してから続行してください。

保存後、provider page に OAuth client が configured と表示され、client secret は非表示になります。

手順 5：test account を接続する

OAuth client を保存した後、そのまま provider page で Connect を選択して authorization を開始します。provider authorization screen を承認します。provider から OpenConnector に redirect されたら、provider page に account が connected と表示されることを確認します。

手順 6：action をテストする

provider page または console action list から、接続した provider の low-risk read action を実行します。action details には、input schema、required scopes、current connection identity が表示されます。

write actions のテストには demo data を使用してください。

provider ごとの注意事項

OAuth apps の作成には、次の provider docs が役立ちます。

Provider family	Official docs	一般的な設定上の注意
Google APIs	Using OAuth 2.0 for Web Server Applications	web application OAuth client を使用します。authorized redirect URIs に正確な OpenConnector redirect URI を追加します。sensitive または restricted scopes は、広範な production use の前に Google verification が必要になる場合があります。
Slack	Installing with OAuth	app の redirect URLs に正確な OpenConnector redirect URI を追加します。Slack が local callback URL を受け付けない場合は、public runtime origin または HTTPS tunnel を使用します。
GitHub	Creating an OAuth app	GitHub OAuth app に設定できる authorization callback URL は 1 つです。local、staging、production で別々の callback URLs が必要な場合は、個別の apps を作成します。
Microsoft	Register an application with the Microsoft identity platform	Web platform redirect URI を設定し、client secret を作成します。一部の OpenConnector Microsoft providers では、`common`、`organizations`、tenant ID などの `tenant` value が必要です。
HubSpot	Working with OAuth	authorization request の scopes は app の configured scopes と一致する必要があります。production redirect URLs には HTTPS が必要ですが、testing の localhost では HTTP を使用できます。
Notion	Authorization	public connection を作成し、OAuth configuration に OpenConnector redirect URI を追加します。自分の workspace 以外で app を使用する前に、現在の Notion app type と capability rules を確認します。

トラブルシューティング

症状	確認事項
Provider が `redirect_uri_mismatch`、invalid redirect URI、invalid callback URL を表示する。	provider app が `<openconnector-origin>/oauth/callback` を使用していることを確認します。scheme、host、port、path、trailing slash が users の開く origin と一致する必要があります。
Provider が `http://localhost` を拒否する。	testing で localhost に対応する provider を使うか、HTTPS tunnel または public domain で runtime を公開し、OpenConnector の再起動前に `OOMOL_CONNECT_ORIGIN` をその origin に設定します。
Provider が app を unverified、not approved、workspace で not allowed と表示する。	provider 側の app distribution、test users、workspace app approval、sensitive-scope review requirements を確認します。marketplace listing と private testing は通常別ですが、provider rules は異なります。
Authorization は成功するが、action が missing または insufficient scopes で失敗する。	action に必要な scopes を provider app に追加して保存し、provider account を再接続して新しい scopes を付与します。
OpenConnector が `oauth_client_config_not_found` を表示する。	Connect を開始する同じ provider page で OAuth client を保存します。
後で token refresh が失敗する。	provider が refresh token を発行したか確認します。一部の providers は offline-access parameters または re-consent を必要とします。refresh token がない場合は account を再接続します。
実行時に誤った account が使用される。	対象 account にサインインした browser profile から再接続し、actions のテスト前に console で対象 connection を選択します。

security checklist

OAuth client secrets または connected account credentials を保存する前に、OOMOL_CONNECT_ENCRYPTION_KEY を設定します。
OOMOL_CONNECT_ADMIN_TOKEN を非公開にし、/v1 と /mcp の callers には runtime tokens を使用します。
provider と OpenConnector action set が許可する範囲で least-privilege scopes を使用します。
provider callback rules によって audit が容易になる場合は、local、staging、production 用に別々の OAuth apps を用意します。
使用していない provider apps、古い client secrets、不要な OpenConnector connections を削除します。