Configure Okta for automatic identity management

Preview

This feature is in Private Preview. To request access, contact your account team.

This page describes how to configure Okta to provision users, groups, and service principals 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, create a new app integration and select API Services.
2. Select Public Key / Private Key as the client authentication method.
3. Grant the following API scopes to the app:
   • okta.groups.read
   • okta.users.read
4. Grant the Read-Only Admin role to the app.
5. Disable the DPoP (Demonstrating Proof of Possession) header in requests.
6. Generate a private key for the app and save it securely.

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)
   • Client ID: The client ID of the Okta app you created
   • Client Private key: The private key you generated
5. Click Test connection to verify the integration is successful.
6. When the connection succeeds, click Enable AIM.

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.