> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Providers

> Connect Genesis to OAuth-based services. Most setups only need the Connections page — this guide explains when and why you might also touch the OAuth Providers section in Advanced Settings.

## The short version

For most customers, **all OAuth setup happens on the Connections page**. Open
**Config -> Connections**, pick a connector, choose the **User OAuth** mode, and
enter the OAuth application details Genesis asks for. You should not need to
visit Advanced Settings.

The **Advanced Settings -> OAuth Providers** page exists only as a shared
default. It is useful when an administrator wants to register **one** OAuth
application that **many** Genesis users can reuse. If that does not describe
your setup, you can ignore it.

The rest of this page explains both flows so you know which one fits your
situation.

## Background: what an OAuth connection actually needs

When Genesis connects to a service like BigQuery, GitHub, GitLab, Snowflake,
Databricks, Jira, Confluence, ServiceNow, Salesforce, SharePoint, Microsoft Teams, or Google Workspace using OAuth,
two pieces
of identity are involved:

1. **The OAuth application.** This represents *Genesis itself* to the third
   party. It is created once, in the third party's developer console (for
   example, a GitHub OAuth App or a Snowflake Security Integration). It
   produces a **Client ID** and **Client Secret** plus a **Redirect URI** that
   you must register so the third party knows where to send users back after
   they authorize.
2. **The user's authorization.** When someone clicks **Authorize** on a
   Genesis connection, the third party shows that user a consent screen and
   returns an access token tied to that user. Genesis stores those tokens on
   the connection.

Genesis can hold the OAuth application credentials (Client ID, Client Secret,
URLs) in **two** places:

| Location | Scope | Best for |
| - | - | - |
| On the connection itself, on the Connections page | Just that one connection | Most customers, single connections, or trying things out |
| In Advanced Settings -> OAuth Providers | Shared default for every connection of that type on this Genesis instance | Admins registering one OAuth app for the whole team |

Both locations store secrets through Genesis Secrets, and both feed the same
OAuth flow at runtime. When a connection has its own values, Genesis uses
those. When it does not, Genesis falls back to the shared values from
Advanced Settings.

## The normal scenario: set everything on the Connections page

This is the recommended flow for almost everyone.

1. In the third-party service's developer console, create an OAuth application.
   * You will be asked for a **Redirect URI**. Leave the field blank for now;
     Genesis will display the exact value to paste in step 4.
   * Once the app is created, copy the **Client ID** and **Client Secret**.
2. In Genesis, open **Config -> Connections** and pick the connector tile
   (GitHub, GitLab, Snowflake, Databricks, Jira, Confluence, ServiceNow, Salesforce, SharePoint, Microsoft Teams,
   Google Workspace, Linear, etc.).
3. In the **Connection mode** chooser, select **User OAuth** (Genesis
   pre-selects the first available mode when the modal opens, so this may already
   be selected).
4. Fill in the form:
   * The connection's own fields (account / host / org, depending on the
     connector).
   * **OAuth Client ID** and **OAuth Client Secret** from step 1. For GitHub
     and GitLab, you can also save these from the post-save setup guide instead.
   * **Authorization URL** and **Token URL** are pre-filled with the standard
     defaults for that service. Only change them for self-hosted or non-default
     instances (for example, an enterprise GitHub server).
   * For Snowflake, the connection `account` field can be a bare account
     identifier, a full account host, or a full `https://...` account URL.
     When you leave **Authorization URL** and **Token URL** at the standard
     Snowflake defaults, Genesis derives those hosts from `account`. If you
     override the URLs, Genesis uses the hosts in those URLs instead. Bare
     identifiers resolve to `<account>.snowflakecomputing.com`; full public
     hosts keep suffixes such as `snowflakecomputing.cn`,
     `snowflakecomputing.app`, and `snowflake.app`. During Snowflake
     **User OAuth**, when Genesis can tell that the request came from either a
     public Snowflake host or a `*.privatelink.*` host, it rewrites recognized
     `snowflakecomputing.com` / `snowflakecomputing.cn` authorization and token
     URLs to the matching public or PrivateLink form automatically. If the
     request origin is local or otherwise unknown, or the configured URL uses
     another host family, Genesis leaves the URL unchanged. In Snowflake Native
     App / SPCS deployments, Genesis may additionally retarget **Token URL**
     (not **Authorization URL**) to the SPCS-injected `SNOWFLAKE_HOST` for
     same-account connections only; when the connection's `account` clearly
     targets a different Snowflake account, **Token URL** stays on that
     account's host and token exchange/refresh egresses through approved
     external access.
   * For Microsoft Teams, the default URLs are tenant-aware templates:
     `https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize` and
     `https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token`.
     Genesis resolves `{tenant_id}` from the connection's `tenant_id`.
   * Genesis displays the **Redirect URI** here, with **Copy**: the callback URL
     the server's sign-in sends, so the form asks for no Genesis base URL. Copy
     it back into the OAuth application you created in step 1, then save the
     OAuth app. The **?** beside the heading says where the provider keeps its
     redirect URIs. In a Databricks App, Genesis gets the callback base from the
     server's OAuth configuration; if it cannot resolve the App's public URL,
     the page shows the reason instead of offering a guessed URI; make the
     public URL available to the App before continuing.
5. Save the connection. For **User OAuth** the create modal shows **Test
   Connection** disabled, since nothing can be tested before a sign-in; the
   guided panel that opens after saving offers it once you have signed in.
6. Genesis opens the guided post-save panel. For GitHub and GitLab, if the
   connection has no OAuth app and no shared app is available, a user who can
   edit the connection can first register its app from the guide. The guide
   provides the provider registration link and exact callback URL, then saves
   the app's Client ID and Client Secret on that connection. Otherwise, continue
   to **Authorize** (**Connect OAuth**). The step shows the exact redirect URI
   for this saved connection name with **Copy redirect URI**, because the
   create-modal copy action may no longer be visible and provider error pages
   name `redirect_uri_mismatch` without showing the URL that would satisfy it. A
   popup launches the third party's consent screen. After you approve, Genesis
   stores the tokens and the popup closes automatically.
   If the provider denies authorization, start **Authorize** again from the
   guide; the retry opens in a separate popup so the earlier callback cannot
   close the new attempt.
7. Click **Test Connection** in the post-save guide to confirm everything works.

That is the full flow. You never have to open Advanced Settings.

<Note>
  In Snowflake Native App / SPCS deployments and other environments where the
  popup is isolated from the main Genesis window, Genesis falls back
  automatically so the OAuth flow can still finish without extra setup.
</Note>

## Why Advanced Settings -> OAuth Providers exists

The OAuth Providers page is a convenience for administrators who expect
**multiple connections of the same type** on a single Genesis instance, all
backed by **the same OAuth application**.

Without it, every user who creates a new GitHub connection (for example) would
need to be handed the same Client ID and Client Secret to paste in. That works,
but it is repetitive and gives more people direct access to the secret.

When you save values in Advanced Settings -> OAuth Providers:

* New connections of that type can be created **without** filling in the OAuth
  client fields. Genesis uses the shared values automatically.
* Existing connections that left those fields blank inherit the shared values.
* Any connection that fills in its own values takes precedence over the shared
  defaults for itself only.

In other words, Advanced Settings is not a replacement for the Connections
page — it is an optional, install-wide **default** that the Connections page
falls back to.

## When would a Genesis customer actually use Advanced Settings?

Use **Advanced Settings -> OAuth Providers** when one or more of the following
are true:

* **You expect many users to create their own connections** to the same
  service (for example, every analyst on the team will create a personal
  GitHub or Snowflake OAuth connection). Pre-configuring the OAuth app once
  here means each user only has to click **Authorize** when they create a
  connection, instead of being given client credentials.
* **You are standardizing on one OAuth application across the company.**
  Putting it in Advanced Settings keeps the secret in one place that only
  admins can edit, instead of being copied into every connection record.
* **You are bootstrapping a new Genesis environment** (dev, staging, prod) and
  want to seed the OAuth app credentials before users start creating
  connections.
* **Your security policy** requires that OAuth client secrets be administered
  centrally rather than entered by individual connection owners.

You do **not** need to use Advanced Settings if:

* You only need one or two connections per service.
* Each user manages their own OAuth application registration.
* You are testing or evaluating Genesis.

## How to fill in Advanced Settings -> OAuth Providers (when you choose to)

1. In the third-party service's developer console, create the OAuth
   application you want to share. Note the **Client ID** and **Client Secret**
   it generates, and copy the redirect URI Genesis will display in the next
   step into the OAuth app's allowed redirect URIs.
2. In Genesis, open **Config -> Advanced Settings** and scroll to the
   **OAuth Providers** section.
3. Find the row for your provider (for example `databricks.client_id`,
   `snowflake.client_id`, `github.client_id`, `gitlab.client_id`,
   `jira.client_id`, `servicenow.client_id`, `salesforce.client_id`, `sharepoint.client_id`, `microsoft_teams.client_id`,
   `google_workspace.client_id`, `linear.client_id`).
4. Enter the **Client ID** and click **Configure** on the matching
   **Client Secret** row to store the secret.
5. Leave **Authorization URL**, **Token URL**, and **Scopes** at their defaults
   unless you have a specific reason to change them (for example, a
   self-hosted GitLab or an enterprise GitHub).
6. Save.

For Microsoft Teams, the default delegated scopes are
`ChannelMessage.Send`, `ChatMessage.Send`, `Chat.ReadWrite`,
`Team.ReadBasic.All`, `Channel.ReadBasic.All`, `User.Read.All`, and
`offline_access`.

After that, anyone in the workspace can create a new connection of that type
on the Connections page, leave the OAuth client fields blank, and proceed
straight to the **Authorize** step.

<Note>
  The OAuth Providers page does **not** authorize any user by itself. It only
  registers the shared OAuth application. Each user still has to click
  **Authorize** on their own connection to grant Genesis access to their
  account in the third-party service.
</Note>

## Supported providers

The following connectors support OAuth and can be configured either way
(per-connection on the Connections page, or once in Advanced Settings):

* BigQuery
* Databricks
* Snowflake
* GitHub
* GitLab
* Jira
* Confluence
* ServiceNow
* Salesforce
* SharePoint
* Microsoft Teams
* Google Workspace
* Linear

Other connectors that use Personal Access Tokens, passwords, or key pairs do
not use the OAuth Providers section at all.

## Common questions

**I already created a connection and entered the OAuth client details there.
Do I also have to copy them into Advanced Settings?**
No. The values you entered on the connection are sufficient for that
connection to work. Advanced Settings only acts as a default for *future*
connections that leave those fields blank.

**If I save values in Advanced Settings, will my existing connections start
using them?**
Only the connections that left their own OAuth client fields blank. Any
connection that already has its own Client ID and Client Secret keeps using
its own values.

**Can different connections of the same type use different OAuth
applications?**
Yes. Fill in the OAuth client fields directly on each connection. Each
connection's own values override the shared defaults from Advanced Settings.

**What happens if I leave both places blank?**
The connection's authorize step will fail with an
`oauth_provider_not_configured` error listing which fields are missing
(typically `client_id`, `client_secret`, `authorization_url`, and
`token_url`). Fill them in either on the connection or in Advanced Settings
and try again.

## Troubleshooting

### `redirect_uri_mismatch` during authorization

If the provider's consent screen or popup reports `redirect_uri_mismatch`, the
callback URL registered in the third-party OAuth application does not exactly
match what Genesis sent. Genesis builds the redirect URI from the Genesis host
and the saved connection name, so every connection needs its own entry in the
provider's allowed callback URLs.

On the **Connect OAuth** step in the post-save guide (or the OAuth recovery
guide opened via `?open_oauth=<type>.<name>`), Genesis shows the exact URL to
register and a **Copy redirect URI** action. Some providers also show where in
their console to paste it — for Salesforce, see
[Salesforce](/docs/Setup/Salesforce#user_oauth).

When creating a connection, keep the suggested connection name or replace it
entirely — Genesis selects the suggested name on focus so typing does not append
to it and silently change the callback URL.

### OAuth token endpoint failures

When Genesis exchanges an authorization code or refreshes tokens, the
third-party **token URL** can return an HTTP error (for example `400` or
`401`). Genesis records these failures in server logs with the provider's
response body so you can see codes such as `invalid_grant`,
`invalid_client`, `unauthorized_client`, or `access_denied` instead of only
a generic HTTP status line.

Search server logs ([Pulse Monitoring](/docs/User-Guide/Pulse-Monitoring)
**Raw** view or `server.log`) for:

`OAuth token request failed: ...; status=<code>; response_body=<snippet>`

| Field | Meaning |
| - | - |
| `status` | HTTP status code from the provider's token endpoint |
| `response_body` | Up to 2048 characters of the provider's response (often JSON). This is the **response** from the provider, not the request Genesis sent. |

Genesis **never** logs the outbound token request body. That payload can
include `client_secret`, authorization codes, or `code_verifier` values.

Reproduce the failure by clicking **Authorize** or **Test Connection** on
the affected connection, then inspect the log line immediately afterward.
Use the provider's documentation to interpret the error code in
`response_body` (for example, a mismatched redirect URI, an expired
authorization code, or incorrect client credentials).

## Related pages

* [Connections](/docs/Setup/Connections)
* [Advanced Settings](/docs/Setup/Advanced-Settings)
* [Linear](/docs/Setup/Linear)
* [Microsoft Teams](/docs/Setup/Microsoft-Teams)
* [SharePoint](/docs/Setup/SharePoint)
* [Slack Integration](/docs/Workspaces/Slack/Activate-Genbots-On-Slack)