SCIM API 2.0

  • Article
  • 4 minutes to read

This article describes how to use the Azure Databricks SCIM APIs to provision users, service principals, and groups to Azure Databricks.

SCIM, or System for Cross-domain Identity Management, is an open standard that allows you to automate user provisioning. Azure Databricks supports both UI-based SCIM provisioning and provisioning using REST APIs and JSON. The Azure Databricks SCIM API follows version 2.0 of the SCIM protocol.

For UI-based SCIM provisioning setup, see Sync users and groups from Azure Active Directory.

Account-level and workspace-level SCIM provisioning

You can either configure one SCIM provisioning connector from Azure Active Directory to your Azure Databricks account, using account-level SCIM provisioning, or configure separate SCIM provisioning connectors to each workspace, using workspace-level SCIM provisioning.

  • Account-level SCIM provisioning: Azure Databricks recommends you use account-level SCIM provisioning to create, update, and delete all users from the account. You will manage the assignment of users and groups to workspaces within Databricks. Your workspaces must be enabled for identity federation, in order to manage the assignment of users to workspaces. Azure Databricks recommends you assign users to workspaces using the workspace assignment API.

Account-level SCIM diagram

  • Workspace-level SCIM provisioning (public preview): If none of your workspaces are enabled for identity federation, or if you have a mix of workspaces, some enabled for identity federation and others not, you must manage account-level and workspace-level SCIM provisioning in parallel. In a mixed scenario, you don’t need workspace-level SCIM provisioning for any workspaces that are enabled for identity federation.

    If you already have workspace-level SCIM provisioning set up for workspaces that you are enabling for identity federation, we recommend that you set up account-level SCIM provisioning and turn off the workspace-level SCIM provisioner. See Migrate workspace-level SCIM provisioning to the account level.

To manage account-level SCIM provisioning for users, service principals, and groups using the REST API, see:

To manage workspace-level SCIM provisioning (public preview) using the REST API, see:

For more information about workspace-level vs account-level SCIM provisioning, see Sync users and groups from Azure Active Directory.

Your Azure Databricks account must have the Premium Plan.

SCIM 2.0 APIs

An Azure Databricks account admins can invoke the account-level SCIM API endpoints:

An Azure Databricks workspace admin can invoke all workspace-level SCIM API endpoints:

Non-admin users and service principals can invoke the workspace-level Me Get endpoint, the workspace-level Users Get endpoint to display names and IDs, and the workspace-level Group Get endpoint to display group display names and IDs.

For error codes, see SCIM API 2.0 Error Codes.

Call account-level SCIM APIs

You must be an account admin to call SCIM API 2.0 (Accounts) .

You call the account-level SCIM API on the accounts.azuredatabricks.net domain, not your workspace domain. For example:

https://accounts.azuredatabricks.net/api/2.0/accounts/{account_id}/scim/v2/Users/{user_id}

Call workspace-level SCIM APIs

Important

This feature is in Public Preview.

To call workspace-level SCIM APIs, replace <databricks-instance> with the workspace URL of your Azure Databricks deployment.

https://<databricks-instance>/api/2.0/preview/scim/v2/<api-endpoint>

Header parameters

Parameter Type Description
Authorization (required)

Or:

The .netrc file (if using curl)		 STRING Set to Bearer <access-token>.

See Authentication using Azure Databricks personal access tokens, Authenticate using Azure Active Directory tokens, and Token API 2.0 to learn how to generate tokens.

Important! The Azure Databricks admin user who generates this token should not be managed by your identity provider (IdP). An Azure Databricks admin user who is managed by the IdP can be deprovisioned using the IdP, which would cause your SCIM provisioning integration to be disabled.

Instead of an Authorization header, you can use the .netrc file along with the --netrc (or -n) option. This file stores machine names and tokens separate from your code and reduces the need to type credential strings multiple times. The .netrc contains one entry for each combination of <databricks-instance> and token. For example:

machine <databricks-instance> login token password <access-token>
Content-Type (required for write operations) STRING Set to application/scim+json.
Accept (required for read operations) STRING Set to application/scim+json.

Filter results

Use filters to return a subset of users or groups. For all users, the user userName and group displayName fields are supported. Admin users can filter users on the active attribute.

Operator Description Behavior
eq equals Attribute and operator values must be identical.
ne not equal to Attribute and operator values are not identical.
co contains Operator value must be a substring of attribute value.
sw starts with Attribute must start with and contain operator value.
and logical AND Match when all expressions evaluate to true.
or logical OR Match when any expression evaluates to true.

Sort results

Sort results using the sortBy and sortOrder query parameters. The default is to sort by ID.