Configure workspace-level SCIM provisioning using Okta (legacy)
Important
This documentation has been retired and might not be updated. Workspace-level SCIM provisioning is legacy. Databricks recommends that you use account-level SCIM provisioning, see Sync users and groups from your identity provider.
Preview
This feature is in Public Preview.
This section describes how to set up provisioning from Okta directly to Databricks workspaces.
Get the API token and SCIM URL in Databricks
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.
Make a note of the following URL, which is required for configuring Okta:
https://<databricks-instance>/api/2.0/preview/scim/v2
Replace
<databricks-instance>
with the workspace URL of your Databricks deployment. See Get identifiers for workspace objects.
Keep this browser tab open.
Configure SCIM provisioning in the Databricks SAML application in Okta
Go to Applications and click Databricks.
Click Provisioning. Enter the following information obtained from the above section:
Provisioning Base URL: the provisioning endpoint
Provisioning API Token: the personal access token
Click Test API Credentials.
Reload the Provisioning tab. Additional settings appear after a successful test of the API credentials.
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 Map application attributes on the Provisioning page in the Okta documentation.
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.
Test the integration
To test the configuration, use Okta to invite a user to your Databricks workspace.
In Okta, go to Applications and click Databricks.
Click the Assign tab, then Assign to people.
Search for an Okta user, and click Assign.
Confirm the user’s details. Click Done.
In the Databricks workspace admin settings page, click Identity and access tab, then go to the Users section 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.
Delete a deactivated user from the workspace
If you delete a user from the workspace-level Databricks application in Okta, the user is deactivated in the Databricks workspace but is not removed from the workspace. A deactivated user does not have the workspace-access
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.
Important
Do not deactivate the administrator who configured the Okta SCIM provisioning app. Otherwise, the SCIM integration cannot authenticate to Databricks.
To remove a user from a Databricks workspace:
In the admin settings page, go to the Users tab.
Click the x at the end of the line for the user.
Be aware of the following consequences of removing the user:
Applications or scripts that use the tokens generated by the user will no longer be able to access the Databricks API
Jobs owned by the user will fail
Clusters owned by the user will stop
Queries or dashboards created by the user and shared using the Run as Owner credential will have to be assigned to a new owner to prevent sharing from failing
Use Okta to manage workspace admins, entitlements, and IAM roles
Databricks supports the assignment of workspace admins, IAM roles, and workspace entitlements from workspace-level Databricks applications in Okta. The assignment of roles and entitlements is not supported from the account-level Databricks application in Okta. If you want to assign IAM roles and workspace entitlements from Okta, you must create a workspace-level Databricks application in Okta to that workspace.
Databricks recommends that you instead use an account-level Databricks application in Okta to provision users, service principals, and groups to the account level. You assign users and groups to workspaces using identity federation and manage their entitlements and IAM roles within Databricks.
Sync workspace admins
Databricks supports the assignment of the workspace admin role from the workspace-level Databricks application in Okta. Workspace admins are members of the Databricks admins
group. Databricks groups are automatically pushed to Okta. To add a new admin user in Okta, add that user to the admins
group.
Important
Do not remove the administrator who configured the Okta SCIM provisioning app, and do not remove them from the admins
group. Otherwise, the SCIM integration cannot authenticate to Databricks.
Assign workspace entitlements from Okta
Databricks supports the assignment of entitlements from the workspace-level Databricks application in Okta. However, in most instances, Databricks recommends managing entitlements from within Databricks. Within Databricks, you can easily assign or revoke an entitlement. Configuring the mappings in Okta is complex, and you must configure two mappings for each entitlement.
This section describes how to configure the mappings to grant the databricks-sql-access
entitlement to an Okta user.
Important
By default, Databricks users inherit the workspace-access
and databricks-sql-access
entitlements. By default, Databricks admin users inherit the create-cluster
entitlement. You don’t need to assign these inherited entitlements from Okta.
To revoke an inherited entitlement from a user, either remove the user from the group or remove the entitlement from the group. To remove an entitlement, you must use the Databricks admin console.
To assign the databricks-sql-access
entitlement:
In the Okta admin console, go to Directory > Profile Editor.
Click the Profile edit button for the Okta user profile.
Click the + Add Attribute button to add a role.
In the Add Attribute dialog, set the Display name to
Databricks SQL
and the Variable name todatabricks_sql
.Note
Okta variables cannot contain the hyphen (
-
) character.Return to the Profile Editor and click the Profile edit button for the Databricks provisioning app user profile.
Click the + Add Attribute button to add a role.
On the Add Attribute dialog, give the role attribute the following values:
Display name:
Databricks SQL
Variable name:
databricks_sql
External Name in the format
entitlements.^[type==‘$TYPE’].value
.$TYPE
is the API name of the entitlement without dashes (-
). For example, the External Name fordatabricks-sql-access
isentitlements.^[type=='databrickssqlaccess'].value
.
Important
In the External Name format, you must use apostrophe characters (
'
). If you use curly quote characters (’
), aRequest is unparseable
error occurs.External Namespace:
urn:ietf:params:scim:schemas:core:2.0:User
.
Return to the Profile Editor and click the Mappings edit button for the Databricks provisioning app user profile.
For Databricks to Okta, map
appuser.databricks_sql
in the Databricks column todatabricks_sql
in the Okta column.For Okta to Databricks, map
user.databricks_sql
in the Databricks column todatabricks_sql
in the Okta column.Click Save Mappings.
To add an entitlement 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. In the field for the entitlement, enter the API name of the entitlement without dashes, such as
databrickssqlaccess
. When you assign the user to the app, the role is populated with the value that you entered.
Repeat this procedure to assign additional entitlements.
Assign IAM roles from Okta
In order to assign IAM roles to users 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 IAM roles to a user, you must create two attributes in the Databricks provisioning app and map one Okta user attribute to each.
Databricks recommends managing IAM role assignments from within Databricks. Within Databricks, you can easily assign or revoke an IAM role. Configuring the mappings in Okta is complex, and you must configure separate mappings for each IAM role.
The following instructions assign the primary_role
attribute.
In the Okta admin console, go to Directory > Profile Editor.
Click the Profile edit button for the Okta user profile.
Click the + Add Attribute button to add a role.
In the Add Attribute dialog, set Display name to
Primary role
and Variable name toprimary_role
.Return to the Profile Editor and click the Profile edit button for the Databricks provisioning app user profile.
Click the + Add Attribute button to add a role.
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 wereprimary
, 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 (’
), aRequest is unparseable
error occurs.External Namespace:
urn:ietf:params:scim:schemas:core:2.0:User
.Return to the Profile Editor and click the Mappings edit button for the Databricks provisioning app user profile.
For Databricks to Okta, map
appuser.primary_role
in the Databricks column toprimary_role
in the Okta column.For Okta to Databricks, map
user.primary_role
in the Databricks column toprimary_role
in the Okta column.Click Save Mappings.
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.