Skip to main content

Databricks: SSO for Direct Connect

SqlDBM Support
Updated

Single sign-on (SSO) lets your team connect SqlDBM to Databricks with their existing Databricks identity instead of personal access tokens (PATs).

SqlDBM offers two separate SSO logins:

How Databricks SSO works

Databricks SSO doesn't use an external identity provider such as Azure AD or Okta, the way Snowflake or BigQuery do. Databricks acts as its own OAuth authorization server, using User-to-Machine (U2M) OAuth. You register a custom OAuth app in your Databricks account console, and SqlDBM connects to it.

  • Configured once, per account. A single setup works for every workspace in your Databricks account.
  • Confidential client. The app uses a client secret. SqlDBM stores it securely and uses it only on its servers, so it is never exposed to the browser.
  • Automatic token renewal. Users aren't asked to sign in again every hour.

Before you start

You will need:

  • A Databricks account admin to register the OAuth app in the account console (Step 1).
  • A SqlDBM account admin or alternate admin to save the settings in SqlDBM (Step 2).
  • Users with the required Unity Catalog privileges. See Account Settings and Privileges.

Step 1: Register a custom OAuth app in Databricks

A Databricks account admin registers the app in the account console, not in a workspace.

  1. Open the account console for your cloud:

    Cloud Account console
    AWS accounts.cloud.databricks.com
    Azure accounts.azuredatabricks.net
    GCP accounts.gcp.databricks.com
  2. Go to Settings → App connections and add a connection.
  3. Set the Redirect URL to SqlDBM's callback. It must match exactly:
 
   https://app.sqldbm.com/login/sso/oauth

  1. Under Access scopes, select the granular scopes rather than All APIs:

    • API scopes: unity-catalog, provisioning, sql, command-execution, clusters, files
    • Technical scopes: offline_access, openid, profile, email

    SqlDBM currently requests unity-catalog, sql, and offline_access. Granting the full list keeps the app ready for upcoming SqlDBM features, so you won't need to register it again later. An app granted only All APIs can't satisfy the granular scopes SqlDBM requests, so select them explicitly.

  2. Turn on Generate a client secret and click Save.
  3. Copy the Client ID and Client secret. The secret is shown only once.
  4. Copy your Account ID from the user menu in the top right of the account console.

Databricks references:

Step 2: Configure SSO in SqlDBM

A SqlDBM account admin or alternate admin completes this step. Once it's saved, Login with SSO is available in Direct Connect for all users on the account.

  1. Open the account menu and click SSO settings.
  2. Select Databricks.

  3. Fill in the fields:

    Field Value
    Cloud The cloud your Databricks account runs on: AWS, Azure, or GCP.
    Account ID Your Databricks Account ID from Step 1.
    Client ID The Client ID of the OAuth app from Step 1.
    Client secret The client secret from Step 1.
  4. Click Save.

SqlDBM works out the Databricks OAuth endpoints and scopes from the Cloud and Account ID, so there's nothing else to enter.

Note: The client secret is write-only. SqlDBM never displays it again, and you must re-enter it (the same one or a new one) whenever you save changes to these settings.

Step 3: Connect with SSO

  1. In the Tool, start a Databricks direct connection (Reverse Engineer).
  2. Choose Login with SSO.

  3. Enter the Server URL of the workspace you want to connect to:

    Cloud Server URL format
    AWS dbc-xxxx.cloud.databricks.com
    Azure adb-xxxx.azuredatabricks.net
    GCP xxxx.gcp.databricks.com
  4. Click Connect and authorize in the Databricks popup.
  5. Select your catalog and schemas, and continue with reverse engineering.

Because sign-in happens at the account level, the same login works for any workspace the user belongs to. The Server URL only selects which workspace to browse.

Upgrading from the previous workspace-level setup

Earlier versions of this integration registered the OAuth app in a single workspace and asked the SqlDBM admin to enter a Server URL. Those configurations no longer work. Login with SSO won't appear in Direct Connect until you complete the setup on this page:

  1. Register a new account-level OAuth app with a client secret (Step 1).
  2. Update SqlDBM's SSO settings with the Cloud, Account ID, Client ID, and Client secret (Step 2).

After that, users provide the Server URL themselves when they connect (Step 3).

Troubleshooting

  • The authorization popup fails. The redirect URL in your Databricks app must exactly match https://app.sqldbm.com/login/sso/oauth. This is the most common setup error.
  • Databricks shows a consent or scope error. Check that the app grants the granular scopes from Step 1. At minimum it needs unity-catalog, sql, and offline_access, and it must not be set to All APIs only.
  • Login with SSO doesn't appear in Direct Connect. Either SSO hasn't been configured yet, or it still uses the old workspace-level setup. See Upgrading.
  • Token lifetime. Databricks access tokens last about an hour. SqlDBM renews them automatically using the offline_access scope. Users only need to sign in again if their Databricks session expires or is revoked.
  • Client secret security. The token exchange runs on SqlDBM's servers with the stored secret, and the browser never sees it. Only Databricks sign-ins started from SqlDBM can use it.
  • Access denied to catalogs or schemas. SSO handles authentication only. Each user still needs the Unity Catalog privileges listed in Account Settings and Privileges.

See also