Configure OAuth connection in Databricks platform

Use OAuth to authorize an external application to access your Databricks workspace.

Prerequisites

Ensure you have the following prerequisites:
  • Databricks account admin or workspace admin privileges.
    • Account admin — Required to access the Databricks account console, register OAuth applications under Settings > App connections , and manage service principals under User management. This is an account-level role.
    • Workspace admin — Required to manage permissions within a specific Databricks workspace — for example, assigning a service principal access to workspace resources.
      Depending on the tasks, the required privilege might vary, some of the tasks are:
      Task Required privilege
      Register an OAuth app / App connection Account admin
      Create a service principal Account admin
      Assign workspace permissions to a service principal Workspace admin
      Configure Workload Identity Federation trust policies Account admin
  • Your Databricks workspace URL (https://dbc-workspace-id.cloud.databricks.com/ or equivalent)
  • The external application's redirect URI (for U2M)
Databricks supports two flows depending on whether a user identity is involved.
User-to-Machine (U2M) Machine-to-Machine (M2M)
When to use A named user authorizes access interactively via browser Automated access with no user interaction — bots, scheduled jobs, service accounts
Identity End user Service principal
Requires browser Yes No
Secrets involved No long-lived secrets Client secret or federated identity

Procedure

  1. Register an OAuth application in Databricks.
    Both flows require an OAuth application registered in your Databricks account.
    1. Sign in to your Databricks account console at https://accounts.azuredatabricks.net.
    2. Go to Settings > App connections.
    3. Select Add connection and enter a name for the application.
    4. Provide the Redirect URL supplied by the external application.
    5. Select the required scopes. Grant only the minimum scopes required for the integration.
    6. Save the connection. Databricks generates a Client ID.
      Note: You need to provide The Client ID to the external application during its connection setup.
  2. Configure the OAuth flow.
    U2M — User-to-Machine

    Use this flow when the external application needs to act on behalf of a specific Databricks user.

    1. Confirm the registered application has the correct Redirect URL (provided by the external application).
    2. For SaaS or multi-user applications, enable OIDC U2M in the application settings.
    3. Share the Client ID and Redirect URL with the external application administrator.
    4. When the external application initiates the connection, Databricks opens a browser-based authorization prompt.
      The user signs in with their Databricks credentials and approves the requested scopes.
    5. Databricks issues an access token (1-hour TTL for desktop flows) and a refresh token to the external application.

      The external application acts with the permissions of the user who authorized it. Ensure the user has the appropriate workspace permissions before authorizing.

    M2M — Machine-to-Machine

    Use this flow when the external application connects without a signed-in user — for example, scheduled automation or background services.

    1. In your Databricks account console, go to User management > Service principals.
    2. Select Add service principal and enter a name.
    3. Assign the service principal the minimum workspace permissions required for the integration.
    4. Go to the service principal's detail page and select Secrets > Generate secret.
      • Copy the Client ID and Client Secret immediately - the secret is not shown again.
      • Use this option only if your environment does not support federated identity.
    5. To avoid long-lived secrets, configure Workload Identity Federation instead:
      • Go to the service principal's detail page and select OAuth Trust Policies.
      • Define a trust policy that allows your external application's identity provider to issue tokens on behalf of the service principal.
      • No client secret is required when federation is configured.
    6. Provide the Client ID (and Client Secret if applicable) to the external application administrator.

      Workload Identity Federation is the recommended option. Use client secrets only when the external platform does not support federated identity.

  3. Verify the connection.

    After the external application completes its connection setup using the credentials you provided:

    1. Go to Settings > App connections in your Databricks account console.
    2. Confirm the application appears with an active status.
    3. For M2M, run a test job or API call from the external application and verify it completes without authentication errors.
    4. For U2M, have a user start the browser-based authorization and confirm the token is issued.
  4. Optional: Revoke access: To disconnect the external application from your Databricks workspace:
    • U2M: Go to Settings > App connections, select the application, and remove it. Active tokens are invalidated.
    • M2M: Go to User management > Service principals, select the service principal, and either delete the secret or remove the service principal entirely.