--- title: OpenConnector OAuth app setup guide description: Create a provider OAuth app, configure its redirect URI, and connect it to a self-hosted OOMOL OpenConnector runtime. lang: en canonical_url: https://oomol.com/en/docs/openconnector-oauth-apps/ markdown_url: https://oomol.com/en/docs/openconnector-oauth-apps.md --- # OpenConnector OAuth app setup guide OOMOL OpenConnector uses your own provider OAuth app when an OAuth2 provider needs user authorization. Create the app in the provider's developer console, copy the exact callback URL from your OpenConnector runtime into that app, then save the app's client configuration in OpenConnector. Use this guide for OAuth2 providers such as Gmail, Google Drive, Google Calendar, Slack, HubSpot, GitHub, Microsoft Outlook, Notion, Zoom, Zendesk, Jira, Dropbox, and other OAuth providers shown in the OpenConnector provider catalog. This guide covers OAuth app setup. For providers that use another auth type, use the credential fields shown by the OpenConnector provider page. ## What you need - A running OOMOL OpenConnector runtime. - Access to the OpenConnector web console. - The admin token if `OOMOL_CONNECT_ADMIN_TOKEN` is set. - Permission to create an OAuth app in the provider's developer or admin console. - A test account in the provider workspace, tenant, organization, or portal you want to connect. If your runtime is reachable through a public domain, tunnel, or Cloudflare Worker URL, set `OOMOL_CONNECT_ORIGIN` before creating provider OAuth apps. The redirect URI is derived from this origin. ```bash 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 ``` ## Step 1: Set the OpenConnector callback URL Build the callback URL from the origin users open in the browser: ```text /oauth/callback ``` With the default local runtime, use: ```text http://localhost:3000/oauth/callback ``` When `OOMOL_CONNECT_ORIGIN` is set to a public origin, the callback URL uses that origin: ```text https://connect.example.com/oauth/callback ``` Enter this exact callback URL in the provider OAuth app. Do not add a trailing slash unless your OpenConnector origin itself includes one. ## Step 2: Create the provider OAuth app Open the provider's developer console and create an OAuth app, integration, connected app, public app, or application registration. Provider naming varies, but the required fields are usually the same. | Provider app field | What to enter | | --- | --- | | App name | A name you recognize, such as `OpenConnector Local` or your internal tool name. | | Homepage or website URL | Your product, internal tool, repository, or runtime URL. Use a value your users and admins can recognize. | | Redirect URI, callback URL, or reply URL | The exact OpenConnector callback URL, such as `https://connect.example.com/oauth/callback`. | | Scopes or permissions | The scopes required by the OpenConnector provider. Copy them from the provider page or the provider action guide. | | Distribution, install, or visibility | Keep the app private, test-only, internal, or unlisted when the provider allows it and you only need your own accounts. | Many providers let you authorize your own account, test users, workspace, or organization before marketplace listing. Some providers still require verification, admin approval, or review for sensitive scopes, production use, broad customer distribution, or managed workspaces. The provider's authorization screen and admin console are the source of truth. ## Step 3: Copy the client configuration After creating the provider app, copy the client values needed by OpenConnector. | Value | Required | Notes | | --- | --- | --- | | `clientId` | Yes | Usually called Client ID, App ID, Application ID, or Consumer Key. | | `clientSecret` | Usually | Some providers use public-client flows and do not require a secret. If OpenConnector marks the provider secret as optional, leave it empty only when the provider also treats it as optional. | | Extra fields | Sometimes | Some providers need extra OAuth client config, such as `tenant`, `subdomain`, `developerToken`, or account-specific identifiers. Use a console version that exposes the fields required by that provider. | Do not put OAuth client secrets in browser code, public repositories, screenshots, issue reports, or agent prompts. ## Step 4: Save the OAuth client in OpenConnector Use the OpenConnector web console for the normal setup path: 1. Open the OpenConnector web console, such as `http://localhost:3000`. 2. Open **Providers** and select the provider you want to connect. 3. Choose **Configure OAuth Client** or **Edit OAuth Client**. 4. Paste the provider app's **Client ID** and **Client Secret**. 5. Choose **Save OAuth Client**. If the provider needs extra client fields, fill them in the same OAuth client form. For example, Microsoft providers need a `tenant` value. If your console does not show a field that the provider requires, upgrade OpenConnector to a version that supports that provider's full OAuth client form before continuing. After saving, the provider page shows the OAuth client as configured. The stored client secret is not shown again. ## Step 5: Connect a test account After saving the OAuth client, stay on the provider page and choose **Connect** to start authorization. Approve the provider authorization screen. After the provider redirects back to OpenConnector, confirm that the provider page shows the account as connected. ## Step 6: Test an action Use the provider page or the console action list to run a low-risk read action for the provider you connected. Action details show the input schema, required scopes, and current connection identity. Use demo data when testing write actions. ## Provider notes These provider docs are useful when creating OAuth apps: | Provider family | Official docs | Common setup note | | --- | --- | --- | | Google APIs | [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server) | Use a web application OAuth client. Add the exact OpenConnector redirect URI to the authorized redirect URIs. Sensitive or restricted scopes may require Google verification before broad production use. | | Slack | [Installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth) | Add the exact OpenConnector redirect URI to the app's redirect URLs. Use a public runtime origin or HTTPS tunnel if Slack does not accept your local callback URL. | | GitHub | [Creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) | A GitHub OAuth app has one authorization callback URL. Create separate apps if you need separate local, staging, and production callback URLs. | | Microsoft | [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2) | Configure a Web platform redirect URI and create a client secret. Some OpenConnector Microsoft providers require a `tenant` value such as `common`, `organizations`, or a tenant ID. | | HubSpot | [Working with OAuth](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) | The scopes in the authorization request must match the app's configured scopes. Production redirect URLs must use HTTPS; localhost can use HTTP for testing. | | Notion | [Authorization](https://developers.notion.com/guides/get-started/authorization) | Create a public connection and add the OpenConnector redirect URI under OAuth configuration. Review Notion's current app type and capability rules before using the app beyond your own workspace. | ## Troubleshooting | Symptom | What to check | | --- | --- | | Provider says `redirect_uri_mismatch`, invalid redirect URI, or invalid callback URL. | Confirm the provider app uses `/oauth/callback`. The scheme, host, port, path, and trailing slash must match the origin users open in the browser. | | Provider rejects `http://localhost`. | Use a provider that supports localhost for testing, or expose the runtime through an HTTPS tunnel or public domain and set `OOMOL_CONNECT_ORIGIN` to that origin before restarting OpenConnector. | | Provider says the app is not verified, not approved, or not allowed in the workspace. | Check provider-side app distribution, test users, workspace app approval, and sensitive-scope review requirements. Marketplace listing is often separate from private testing, but provider rules vary. | | Authorization succeeds but an action fails with missing or insufficient scopes. | Add the scopes required by the action to the provider app, save the app, and reconnect the provider account so the new scopes are granted. | | OpenConnector says `oauth_client_config_not_found`. | Save the OAuth client on the same provider page where you start **Connect**. | | Token refresh fails later. | Confirm the provider issued a refresh token. Some providers require offline-access parameters or re-consent. Reconnect the account if no refresh token is available. | | The wrong account is used during execution. | Reconnect from a browser profile signed in to the intended account, then select the intended connection in the console before testing actions. | ## Security checklist - Set `OOMOL_CONNECT_ENCRYPTION_KEY` before storing OAuth client secrets or connected account credentials. - Keep `OOMOL_CONNECT_ADMIN_TOKEN` private and use runtime tokens for `/v1` and `/mcp` callers. - Use least-privilege scopes when the provider and OpenConnector action set allow it. - Keep separate OAuth apps for local, staging, and production when provider callback rules make that simpler to audit. - Remove unused provider apps, old client secrets, and stale OpenConnector connections.