Configure an OAuth application for Databricks

You can configure a custom OAuth application to authenticate access to Databricks by using either the Databricks Authorization Server, or by using a different identity provider (IdP) of your choice in combination with Databricks OAuth token federation. This document covers the steps required to configure an OAuth application for Databricks.

To configure a Sigma OAuth application to authenticate access to a different data platform, see Configure a Sigma OAuth application.

User requirements

• In Databricks, you need Account Admin privileges. See What are account admins? in the Databricks documentation for more information.

High-level overview

Configuring a custom OAuth application for Databricks is a multi-step process:

• Step 1: Create your custom OAuth application
• Step 2: Confirm your Databricks connection configuration options.
• Step 3: Determine the metadata URI for your Databricks Authorization Server.

Step 1: Create your OAuth application

The steps to create an OAuth application differ depending on if you want to use Databricks or another platform as your IdP. If you want to use Databricks as your IdP, see Option 1: Create a custom OAuth application in Databricks Authorization Server. If you want to use another platform as your IdP, see Option 2: Configure a custom OAuth application using Databricks OAuth token federation.

Option 1: Create a custom OAuth application in Databricks Authorization Server

To enable a custom OAuth application in Databricks Authorization Server, see the relevant Databricks documentation:

• See Enable custom OAuth applications using the Azure Databricks UI for Databricks on Azure.
• See Enable custom OAuth applications using the Databricks UI for Databricks on AWS.

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

Option 2: Configure a custom OAuth application using Databricks OAuth token federation

If you want to use your own non-Databricks IdP to authenticate to Databricks, you will need to use Databricks OAuth token federation. To configure this, follow steps 1 to 4 and step 6 in Configure a Sigma OAuth application.

Once you have completed those steps, you can continue the steps in this document and Confirm your Databricks connection configuration options.

Prerequisites:

• In Databricks, you need Account Admin privileges. See What are account admins? in the Databricks documentation.
• In the IdP of your choosing, you need to set up an OAuth application and authorization server. Follow your IdP's documentation for further instructions.

After configuring your OAuth application and authorization server in the IdP of your choice, you must set up a federation policy in Databricks. 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, in addition to the Issuer URL, you should provide a JWKS URI value. This can be found in the jwks_uri field of the JSON object returned by the well-known endpoint. Enter this value when prompted for Token signature validation.

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

Step 2: Confirm your Databricks connection configuration options

When you create the connection for the application in Databricks, you have several configuration options. Sigma requires the following configurations for your OAuth connection to work:

• Redirect URLs: Enter a redirect URL that matches your Sigma deployment. You can find the URL in the OAuth features section when creating your connection, in the Redirect URI field. Alternatively, you can manually format a URL, using the following format: 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.

  🚩

  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.

• Access scopes: When you are prompted to select an access scope, select All APIs. Keep the default scopes of openid, email, profile, and offline_access selected.

  📘

  If you are using Microsoft Entra ID as your IdP, you must also create a custom databricks scope.

• Client secret: Enable the option to generate a client secret, as Sigma requires this for secure connection.

• Refresh token time-to-live (TTL): This value 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.

Record your client ID and client secret. You need these values for the Sigma configuration.

Once you have configured the options above, proceed to Step 3: Determine your metadata URI.

Step 3: Determine your metadata URI

Determine the metadata URI that Sigma will require to complete the OAuth configuration. The metadata URI includes the unique ID for your Databricks account, and is required complete your OAuth configuration in Sigma. Store this value for later use when creating your connection in Sigma.

The process to determine your metadata URI depends on your chosen IdP:

• If you are using Databricks as your IdP, see Determine your metadata URI for your Databricks Authorization Server.
• If you are using another IdP, see Determine your metadata URI for your external IdP.

Determine your metadata URI for your Databricks Authorization Server

For information about how to retrieve your Databricks account ID, see Locate your account ID in the Databricks documentation.

Form your metadata URI using your Databricks account ID. The format for your metadata URI required depends on your environment and configurations:

• Azure: https://accounts.azuredatabricks.net/oidc/accounts/<your-databricks-account-id>/.well-known/openid-configuration
• AWS:
  • If your organization uses workspace-level legacy SSO, and has unified login enabled: https://<server_hostname>/oidc/.well-known/openid-configuration
  • If your organization does not use workspace-level legacy SSO, or does not have unified login enabled: https://accounts.cloud.databricks.com/oidc/accounts/<your-databricks-account-id>/.well-known/openid-configuration

Determine your metadata URI for your external IdP

The process to determine your metadata URI is specific to your IdP. Check your IdP's documentation for information on how to determine your metadata URI.