Configure a Sigma OAuth application

This document guides you through steps to create a Sigma OAuth application in your identity provider (IdP) to enable your IdP to handle authentication. You can then configure Sigma to connect to your OAuth application, either as an authentication method for your Sigma organization, or to authenticate Sigma connections to your data platform, or both.

The steps to create an OAuth application depend on the IdP you're using:

• If you're using Databricks as your IdP, see Configure an OAuth application for Databricks first.
• If you're using a different supported IdP, see Configure a Sigma OAuth application in an external IdP.

💡

As a best practice, configure whichever IdP you use to notify you when your OAuth credentials are nearing expiration to avoid users getting locked out of your Sigma organization or your data connections.

To configure organization-level OAuth for your organization, see Configure OAuth authentication for your Sigma organization.

If your organization has multiple identity providers enabled, you must use connection-level OAuth instead of organization-level OAuth. Follow the relevant guide for your data platform:

• Connect to Snowflake with connection-level OAuth
• Connect to Databricks with connection-level OAuth
• Connect to BigQuery with OAuth

Requirements

• A supported identity provider (IdP). Sigma supports Okta, Microsoft Entra ID, Auth0, PingIdentity, or Databricks Authorization Server.
• If you're using Okta, you must have Okta API Access Management enabled in your Okta instance to create an authorization server. This requires Okta Enterprise.

Configure a Sigma OAuth application in an external IdP

Follow these steps to configure an OAuth app for Sigma in an external IdP such as Okta, Microsoft Entra ID, Auth0, or PingIdentity. If you are using Databricks, refer instead to Configure an OAuth application for Databricks.

For more information on setting up OAuth for specific IdPs, see the Sigma Community post on Guidelines For Configuring OAuth and SAML Authentication.

📘

If your organization has multiple identity providers enabled, and you want to set up multiple OAuth authentication methods, you must configure a separate OAuth app for each method. Repeat the steps in this document for each application.

High-level overview

The exact implementation of these steps varies depending on your IdP. Visit your IdP’s documentation for detailed instructions.

• Step 1: Create an app for Sigma in your IdP
• Step 2: Add OAuth users to your app
• Step 3: Create an OAuth authorization server
• Step 4: Add an access policy for the authorization server
• Step 5: Create a security integration (Snowflake only)
• Step 6: Configure Databricks OAuth token federation (Databricks only)

Step 1: Create an app for Sigma in your IdP

First, create a Web OpenID Connect app within your IdP for Sigma. The exact configuration steps and wording of the options differ depending on your IdP.

🚩

You must manually update the URL to use the {{baseUrl}} specific to where your Sigma organization is hosted. The {{baseUrl}} value is listed in the API endpoint column of the Supported cloud platforms and regions table.

Within the app, do the following:

1. Enable the authorization code grant type.

2. (Recommended) Enable the refresh token grant type. This step is required if you specify the offline_access scope (recommended) when you create an authorization server in Step 3: Create an OAuth authorization server.

3. (Optional) To require Proof Key for Code Exchange (PKCE) for additional verification, select that option in your app configuration.

   📘

   PKCE is not supported for organization-level authentication. If you enable it, do not use this app to authenticate users to your Sigma organization. Instead, create a separate app for organization-level authentication that does not use PKCE.

4. (Optional) If you want to use JSON Web Tokens (JWTs) to authenticate with a public key and private key instead of a client secret, select that option in your app configuration. In your IdP, this might be called "JWT bearer tokens" or "Public key / Private key".

   📘

   JWTs are not supported for organization-level authentication. If you enable JWT authentication, do not use this app to authenticate users to your Sigma organization. Instead, create a separate app for organization-level authentication that does not use JWTs.

5. (Optional) If you select the option to use JWTs, provide the Sigma public certificate when prompted. Format the URI to the certificate like https://{{baseUrl}}/api/v2/.well-known/jwks.json. For example, https://api.sigmacomputing.com/api/v2/.well-known/jwks.json for a Sigma organization hosted on GCP-US.

6. Set the login redirect URL that matches the cloud provider where your Sigma organization is hosted. Format the URL like https://{{baseUrl}}/api/v2/oauth/1/authcode. For example, https://api.sigmacomputing.com/api/v2/oauth/1/authcode for a Sigma organization hosted on GCP-US.

Creating your Sigma OAuth app generates a Client ID and (optionally) a Client secret. These fields are required to complete your OAuth configuration in Sigma in a later procedure.

Step 2: Add OAuth users to your app

After creating your OAuth app, add a list of your OAuth users. If you use this OAuth configuration to authenticate connections to your data platform, then these users are mapped to both Sigma and your data platform.

All users must be granted sufficient privileges in the data platform that you want to use to run queries from Sigma.

Step 3: Create an OAuth authorization server

An authorization server is used to grant tokens to your users that identify them to Sigma and/or your data platform. Create an authorization server in your IdP that grants tokens with the following scopes:

For example, if you are configuring the authorization server to connect to Sigma and Snowflake, enter the following values:

The authorization server provides a metadata URI. The metadata URI is required to complete your OAuth configuration in Sigma in a later procedure.

The server also provides an issuer URL and JWKS URL, both of which are needed for the Snowflake security integration, which is required if you are using your OAuth app to connect to a Snowflake warehouse (step 5).

📘

If you are using Okta, you must have Okta API Access Management enabled in your Okta Enterprise instance to create an authorization server.

Step 4: Add an access policy for the authorization server

1. Create and/or assign an access policy to your new app (created in step 1). Access policies define rules for access and token lifetimes on an individual app.
2. Within the access policy, define access and refresh token lifetimes as desired for all grant types, users, and scopes.

📘

The refresh token time to live (TTL) setting determines how long users can be logged into Sigma before being prompted to sign in again. Set a value consistent with your organization's security policies. To avoid frequent interruptions for your users, Sigma Computing recommends a TTL value of 90 days. To avoid disruption to scheduled exports, do not set a value lower than 7 days.

Next, follow the relevant step if you are using your OAuth application for connection-level OAuth:

• If you are authenticating to Snowflake, see Step 5: Create a security integration (Snowflake only).
• If you are authenticating to Databricks, see Step 6: Configure Databricks OAuth token federation (Databricks only).

Step 5: Create a security integration (Snowflake only)

🚩

This step is required to use this Sigma OAuth application to authenticate one or more Snowflake connections with OAuth.

If you don't use Snowflake, or if you plan to use this OAuth application only to authenticate users to your Sigma organization, this step is not required.

Create a security integration in Snowflake to allow Snowflake to trust your IdP. See the CREATE SECURITY INTEGRATION command reference in the Snowflake documentation.

When creating the security integration, you need to provide the issuer URL and JWKS URL (created in step 3).

The following is an example of the SQL statement you run in Snowflake if Okta is your IdP, with placeholder values in angle brackets. The values vary depending on your IdP.

create security integration <name>
   type = external_oauth
   enabled = true
   external_oauth_type = okta
   external_oauth_issuer = 'https://<COMPANY>.okta.com/oauth2/<ID>'
   external_oauth_jws_keys_url = 'https://<COMPANY>.okta.com/oauth2/<ID>/v1/keys'
   external_oauth_token_user_mapping_claim = 'snowflake_username'
   external_oauth_snowflake_user_mapping_attribute = 'login_name'
   external_oauth_any_role_mode = 'ENABLE';

Step 6: Configure Databricks OAuth token federation (Databricks only)

After configuring your OAuth application and authorization server in the IdP of your choice in the previous steps, you must set up a federation policy in Databricks.

🚩

This step is only necessary if you plan to use connection-level OAuth to connect to Databricks and are not using Databricks as your IdP.

If you plan to use Databricks as your IdP, see Configure an OAuth application for Databricks instead.

When you configure your federation policy, specify the following information:

• Issuer URL, specified in the iss claim:

  • For most IdPs, you obtain the issuer URL from your authorization server’s well-known endpoint, which is likely to end with well-known/oauth-authorization-server. For example, https://test-eng.idp.com/oauth2/xxxxx/.well-known/oauth-authorization-server. The JSON object returned by the well-known endpoint contains an issuer key with the issuer URL.

  • If you are using Microsoft Entra ID, provide a jwks_uri value instead, listed in Advanced fields.

• Audiences, specified in the aud claim: The audience value can be found inside your authorization server's access token payload.

• Subject claim, typically specified in the sub claim: Your Databricks user identifier (such as the email address associated with your Databricks account).

See the Databricks documentation on Account-wide token federation for more information.

After you create your OAuth application, proceed to Step 2: Configure relevant OAuth options.