Skip to main content
Last updated on

Configure Okta for automatic identity management

This page describes how to configure Okta to provision users and groups to your Databricks account using automatic identity management.

Before you begin​

  • You must be an account admin in Databricks.
  • You must have Okta admin access.
  • You must have Okta SSO configured for your Databricks account.

Step 1: Set up an Okta application​

  1. In the Okta admin console, go to Applications and Resources > Applications.
  2. Click Create App Integration, select API Services, and click Next.
  3. Enter a name for the app integration, such as "Databricks AIM", and click Save.
  4. On the General tab, in the Public keys section, click "Add" to add a new public key.
  5. Click Generate new key.
  6. Under Private key – Copy this!, copy the complete JSON value and store it securely. You use this value in Step 2 to configure Databricks. Do not copy the public key or the PEM value.
  7. After the signing key is active, on the General tab, go to the Client Credentials section. For Client authentication, change Client secret to Public Key / Private Key.
  8. On the General tab, in the General Settings section, under Proof of possession, clear Require DPoP Header and click Save.
  9. On the Okta API Scopes tab, grant the following scopes:
    • okta.groups.read
    • okta.users.read
  10. On the Admin Roles tab, assign the Read-only Administrator role to the app.

Step 2: Configure Okta in Databricks​

  1. As an account admin, log in to the account console.
  2. In the sidebar, click Security.
  3. In the User provisioning tab, next to Automatic identity management, click Configure.
  4. Enter the following values:
    • Okta org URL: Your Okta organization URL (for example, https://your-org.okta.com). Use the organization URL, not the admin console URL. The URL must not contain -admin.
    • Client ID: The client ID of the Okta app you created
    • Client Private key: The complete private key JSON value that you generated and copied in Step 1
  5. Click Test connection to verify the integration is successful.
  6. When the connection succeeds, click Enable AIM.

Troubleshoot the connection​

Invalid JSON​

The Client Private key field requires the complete private JWK in JSON format. Copy the entire value under Private key – Copy this! > JSON in Okta. Do not paste the public key, a PEM value, or only part of the JSON object.

302 Found​

Make sure that Okta org URL contains the Okta organization URL, not the admin console URL. Remove -admin from the hostname. For example, use https://your-org.okta.com, not https://your-org-admin.okta.com.

403 response from /api/v1/users​

On the Okta app's Okta API Scopes tab, verify that the app has the okta.users.read scope.

403 response from /api/v1/groups​

Verify that the Okta app has the okta.groups.read scope and the Read-only Administrator role.

Known issues and limitations​

Duplicate identities after enabling automatic identity management​

Databricks matches identities by comparing the Okta user ID or group ID against the externalId field on existing Databricks users and groups. If an existing identity does not have an Okta ID set as its externalId, automatic identity management creates a new entry, resulting in duplicate identities. Both entries remain usable with their existing permissions.

If you previously synced identities using the Okta Databricks OIN app, user externalId values are typically populated, but group externalId values are not. To resolve duplicates, use the Account Users, Account Service Principals, or Account Groups API to set the externalId on existing objects to the corresponding Okta user ID or group ID.

Unified login​

Databricks strongly recommends enabling unified login so that SSO is consistent across the account and all workspaces. Without unified login, automatic identity management can work if account-level and workspace-level SSO use the same identity provider and map the same field to the Databricks username. If account SSO maps the identity provider username while workspace SSO maps email, and a user's username and email differ, login creates a second Databricks user instead of matching the existing one.

Databricks also recommends configuring group claims in your Okta SSO app so that group memberships are included in the OIDC token.

Email or username changes in Okta​

When automatic identity management is enabled, it provisions a new Databricks user based on the SSO username claim at login. If that claim changes (for example, because a user's email changed in Okta, or an admin updated the SSO username claim field mapping), automatic identity management creates a new Databricks user instead of updating the existing one. Contact Databricks support to perform a username migration to align the Databricks username with the updated Okta SSO username claim.

Verify Databricks username uniqueness before onboarding​

Databricks uses the username to match Databricks identities to Okta identities, comparing against both the Okta login field and email. Okta guarantees uniqueness only across the login field, not across email. If multiple Okta users share the same email, or a user's email matches another user's login field, automatic identity management cannot reliably identify the correct user.

Before enabling automatic identity management, verify that each Databricks username maps uniquely to a single Okta user across your Okta tenant.

On this page