Configure a Sigma OAuth application

This document guides you through steps to create a Sigma OAuth application in your identity provider (IdP) to enable authentication to be handled by your IdP. You can then configure Sigma to connect to your OAuth application, either as an authentication method for login to 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 are using:

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

💡

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. See Connect to Snowflake with connection-level OAuth or Connect to Databricks.

Requirements

• A supported identity provider (IdP). Sigma supports Okta, Microsoft Entra ID, Auth0, PingIdentity, or Databricks Authorization Server.
• If you are 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 a custom OAuth application to authenticate to 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 will need to configure a separate OAuth app for each method. Repeat the steps below 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, so if you do 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, so if you do 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 Sigma's 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}}/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 jws keys 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 TTL setting determines how long users can be logged into Sigma before being prompted to log 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.

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)

Create a security integration in Snowflake to allow Snowflake to trust your IdP.

📘

This step is necessary only if you want to use this Sigma OAuth application to authenticate one or more Snowflake connections with OAuth. If you don't use Snowflake, or if you are configuring the OAuth application only for authenticating users to your Sigma organization, then this step of establishing the trust relationship between your authorization server and Snowflake is not necessary.

See the CREATE SECURITY INTEGRATION command reference in the Snowflake documentation. When creating the security integration, you need to provide the issuer url and jws keys 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 steps above, you must set up a federation policy in Databricks.

📘

This step is only necessary if you are authenticating to Databricks and are not using Databricks as your IdP. If you are not authenticating to Databricks, skip this step. If you are using Databricks Authorization server as your IdP, see Configure an OAuth application for Databricks instead.

When configuring your federation policy, you must 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, you should provide a jwks_uri value instead, 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.

Once you have created your OAuth application, proceed to Step 2: Confirm your Databricks connection configuration options in Configure an OAuth application for Databricks.