Configure SCIM provisioning for Okta

Preview

This feature is in Public Preview.

Databricks is available as a provisioning app in the Okta Integration Network (OIN), enabling you to use Okta to provision users and groups with Databricks automatically.

Features

The Databricks Okta application allows you to:

  • Invite users to a Databricks workspace
  • Add invited or active users to groups
  • Deactivate existing users in a Databricks workspace
  • Manage groups and group membership
  • Update and manage profiles

Requirements

  • Your Databricks account must have the Premium plan (or, for customers who subscribed to Databricks before March 3, 2020, the Operational Security package).
  • You must perform these procedures as a Databricks administrator and an Okta developer user.

Prepare Databricks for SSO

  1. As a Databricks workspace administrator, generate a personal access token. See Token management. Store the personal access token in a secure location.

    Important

    The user who owns this personal access token must not be managed within Okta. Otherwise, removing the user from Okta would disrupt the SCIM integration.

  2. In the admin console, go to the Single Sign-On tab.

  3. Click Enable SSO if it isn’t already enabled.

  4. Make a note of the following two URLs, which are required for configuring Okta:

    • Databricks SAML URL:

      https://<your-account>.cloud.databricks.com/saml/consume
      
    • Provisioning endpoint:

      https://<your-account>.cloud.databricks.com//api/2.0/preview/scim/v2
      

Keep this browser tab open.

Configure Okta

Configure the Databricks SAML application in Okta

  1. Open a new browser tab, and log into Okta as a developer user.
  2. If necessary, switch to the Classic UI. If you are using the new UI, then select Developer Console in the top left, and select Classic UI. If you do not see this option, you are already using the Classic UI.
  3. Follow the instructions to configure the Databricks SAML application, on the Okta website. For Databricks SAML URL, enter the Databricks SAML URL from Prepare Databricks for SSO.

While following those instructions, make a note of the following pieces of information, which you need to configure the Databricks workspace. You must be logged in for the values to be populated.

  • Single sign-on URL
  • X.509 certificate

Configure SCIM provisioning in the Databricks SAML application in Okta

  1. Go to Applications and click Databricks.
  2. Click Provisioning. Enter the following information from Prepare Databricks for SSO:
    • Provisioning Base URL: the provisioning endpoint
    • Provisioning API Token: the personal access token
  3. Click Test API Credentials.
  4. Reload the Provisioning tab. Additional settings appear after a successful test of the API credentials.
  5. To configure the behavior when pushing Okta changes to Databricks, click To App.
    • In General, click Edit. Enable the features you need. Databricks recommends enabling Create users at a minimum.
    • In Databricks Attribute Mappings, verify your Databricks Attribute Mappings. These mappings will depend on the options you enabled above. You can add and edit mappings to fit your needs. See Application-Based Mapping in the Okta documentation.
  6. To configure the behavior when pushing Databricks changes to Okta, click To Okta. The default settings work well for Databricks provisioning. If you want to update the default settings and attribute mappings, see Provisioning and Deprovisioning in the Okta documentation.

Finish configuring Databricks for SSO

Go back to the Databricks workspace browser tab. In the admin console, click the Single Sign-On tab.

  1. Set the Identity Provider Entity ID to the Single sign-on URL from Configure the Databricks SAML application in Okta.
  2. Set the x.509 Certificate to the X.509 certificate from Configure Databricks provisioning using Okta.

Test the integration

To test the configuration, use Okta to invite a user to your Databricks workspace.

  1. In Okta, go to Applications and click Databricks.
  2. Click Provisioning.
  3. Click Assign, then Assign to people.
  4. Search for an Okta user, and click Assign.
  5. Confirm the user’s details, then click Assign and go back. Click Done.
  6. In the Databricks Admin Console, click Users and confirm that the user is added. At a minimum, grant the user the Workspace entitlement.

After this simple test, you can perform bulk operations, as described in the following sections.

Use the Okta SCIM integration

Import users from Databricks to Okta

To import users from Databricks to Okta, go to the Import tab and click Import Now. You are prompted to review and confirm assignments for any users who are not automatically matched to existing Okta users by email address.

Add user and group assignments

To verify or add user and group assignments, go to the Assignments tab.

Push groups to Databricks

To push groups from Okta to Databricks, go to the Push Groups tab. Users who already exist in Databricks are matched by email address.

Sync admin users

Admin users are members of the Databricks admin group. Databricks groups are automatically pushed to Okta. To add a new admin user in Okta, add that user to the admin group.

Important

The user who owns this personal access token must not be managed within Okta. Otherwise, removing the user from Okta would disrupt the SCIM integration.

Delete a deactivated user

If you delete a user from the Databricks application in Okta, the user is deactivated the Databricks workspace, but is not removed from the workspace. A deactivated user does not have the access-workspace or databricks-sql-access entitlement. Reactivating a deactivated user is reversible, either by re-adding the user in Okta or by using the Databricks SCIM API directly. Removing a user from a Databricks workspace is disruptive and non-reversible.

To remove a user from a Databricks workspace:

  1. On the Admin Console, go to the Users tab.
  2. Click the x at the end of the line for the user.

The user is deleted and any notebooks owned by the user are archived.

Assign roles from Okta

Databricks supports the assignment of roles and entitlements from Okta. You must create a multi-valued attribute in the Okta user profile and the Okta Databricks provisioning app profile, and then map these attributes to attributes in the Databricks SCIM API. For example, if you want to assign two roles to a user, you must create two attributes in the Databricks provisioning app and map one Okta user attribute to each.

The following instructions assign the primary_role attribute.

  1. In the Okta admin console, go to Directory > Profile Editor.

  2. Click the Profile edit button for the Okta user profile.

  3. Click the + Add Attribute button to add a role.

  4. In the Add Attribute dialog, set Display name to Primary role and Variable name to primary_role.

    add okta role attribute
  5. Return to the Profile Editor and click the Profile edit button for the Databricks provisioning app user profile.

  6. Click the + Add Attribute button to add a role.

  7. On the Add Attribute dialog, give the role attribute the following values:

    Display name: Primary role

    Variable name: primary_role

    External Name in the format roles.^[type=='$TYPE'].value, where $TYPE is a string describing the role; in this case, if $TYPE were primary, the External Name would be roles.^[type==’primary’].value.

    Important

    In the External Name format, you must use apostrophe characters ('). If you use curly quote characters (), a Request is unparseable error occurs.

    External Namespace: urn:ietf:params:scim:schemas:core:2.0:User.

    add Databricks role attribute
  8. Return to the Profile Editor and click the Mappings edit button for the Databricks provisioning app user profile.

  9. For Databricks to Okta, map appuser.primary_role in the Databricks column to primary_role in the Okta column.

  10. For Okta to Databricks, map user.primary_role in the Databricks column to primary_role in the Okta column.

  11. Click Save Mappings.

  12. To add a role attribute value to a user, go to Directory > People, select a user, and go to the Profile tab in the user page.

    Click the Edit button to enter a Primary role value for the user. When you assign the user to the app, the role is populated with the value that you entered.

Repeat this procedure to assign additional roles.

Limitations

  • Removing a user from the Okta application deactivates the user in Databricks, rather than deleting the user. You must delete the user from Databricks directly.
  • You can reactivate a deactivated user by removing then re-adding them to Okta, with the exact same email address.

Troubleshooting and tips

  • Users without either First Name or Last Name in their Databricks profiles cannot be imported to Okta as new users.
  • Users who existed in Databricks prior to provisioning setup:
    • Are automatically linked to an Okta user if they already exist in Okta and are matched based on email address (username).
    • Can be manually linked to an existing user or created as a new user in Okta if they are not automatically matched.
  • User permissions that are assigned individually and duplicated through membership in a group remain after the group membership is removed for the user.
  • Users removed from a Databricks workspace lose access to that workspace but may still have access to other Databricks workspaces.
  • The admins group is a reserved group in Databricks and cannot be removed.
  • You cannot rename groups in Databricks; do not attempt to rename them in Okta.
  • You can use the Databricks Groups API or the Groups UI to get a list of members of any Databricks group.
  • You cannot update Databricks usernames and email addresses.