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.

Set up automatic identity management​

Set up an Okta application​

  1. In the Okta admin console, go to Applications and Resources > Applications.
  2. Click Create App Integration, select Classic experience and API Services, and click Next.
  3. Enter a name for the app integration, such as "Databricks AIM", select Use Okta-generated client ID, 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 when you configure Okta in Databricks. Do not copy the public key or the PEM value.
  7. Click Save to activate the signing key.
  8. 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.
  9. On the General tab, in the General Settings section, under Proof of possession, clear Require DPoP Header and click Save.
  10. On the Okta API Scopes tab, grant the following scopes:
    • okta.groups.read
    • okta.users.read
  11. On the Admin Roles tab, assign the Read-only Administrator role to the app.

Configure Okta in Databricks​

  1. As an account admin, log in to the account console.
  2. In the sidebar, click Security.
  3. In the Identity provider setup tab, under Identity management, 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 when you set up the Okta application
  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​

When you enable automatic identity management, keep the following behaviors and limitations in mind.

Duplicate identities after enabling automatic identity management​

Databricks matches identities by comparing the Okta user or group ID against the externalId field on existing users and groups. If an existing identity has no Okta ID in its externalId, provisioning creates a duplicate entry. Both entries remain usable with their existing permissions.

If you previously synced with the Okta Databricks OIN app, user externalId values are usually populated but group values are not. To resolve duplicates, use the Account Users, Account Service Principals, or Account Groups API to set each object's externalId to the matching Okta user or group ID.

Unified login​

Databricks strongly recommends unified login so that SSO is consistent across the account and all workspaces. Without it, automatic identity management works only 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 username but workspace SSO maps email, and a user's username and email differ, login creates a second user instead of matching the existing one.

Also configure group claims in your Okta SSO app so that group memberships are included in the OIDC token.

Email or username changes in Okta​

Provisioning creates each Databricks user from the SSO username claim at login. If that claim changes (for example, a user's email changes in Okta, or an admin updates the SSO username claim field mapping), it creates a new user instead of updating the existing one. Contact Databricks support to run a username migration that realigns the Databricks username with the updated claim.

Verify Databricks username uniqueness before onboarding​

Databricks matches identities by username, comparing against both the Okta login field and email. Okta guarantees uniqueness only for the login field, not email. If multiple Okta users share an email, or a user's email matches another user's login field, provisioning can't reliably identify the correct user. Before you enable automatic identity management, verify that each Databricks username maps to a single Okta user across your tenant.

External identities appear only after they are provisioned​

Users and groups from your identity provider don't appear on the account console User management page until automatic identity management provisions them in Databricks. To find an identity before it's provisioned, search for it. Search returns matching identities from your identity provider, including ones that aren't provisioned yet.

On this page