Skip to main content

​
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: 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.
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.

​
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.
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.

​
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. 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 Raw view or server.log) for: OAuth token request failed: ...; status=<code>; response_body=<snippet> 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).