SCIM API (Preview)

Azure Databricks supports SCIM, or System for Cross-domain Identity Management, an open standard that allows you to automate user provisioning using a REST API and JSON. SCIM lets you create users in Azure Databricks and give them the proper level of access, as well as remove access for users (deprovision them) when they leave your organization or no longer need access to Azure Databricks.

The Azure Databricks SCIM API follows version 2.0 of the SCIM protocol.

Note

You must be an Azure Databricks administrator to invoke this API.

Call the SCIM API

Resource URL

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

Where <databricks-instance> is the <REGION>.azuredatabricks.net domain name of your Azure Databricks deployment.

Header parameters

Parameter Type Description
Authorization (required) STRING Set to bearer: <access_token>. See Authentication to learn how to generate tokens using the UI, and Token API to learn how to generate tokens using the API.
Content-Type (required for write operations) STRING Set to application/scim+json.
Accept (required for read operations) STRING Set to application/scim+json.

SCIM API endpoints

Get Users

Endpoint HTTP Method
2.0/preview/scim/v2/Users GET

Retrieve a list of all users in the Azure Databricks workspace.

Example request

GET /api/2.0/preview/scim/v2/Users  HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

You can use filters to specify subsets of users. For example, you can apply the eq (equals) filter parameter to userName to retrieve a specific user or subset of users:

GET /api/2.0/preview/scim/v2/Users?filter=userName+eq+example@databricks.com  HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Get User by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} GET

Retrieve a single user resource from the Azure Databricks workspace, given their Azure Databricks ID.

Example request

GET /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Create User

Endpoint HTTP Method
2.0/preview/scim/v2/Users POST

Create users in the Azure Databricks workspace.

Request parameters follow the standard SCIM 2.0 protocol.

Requests must include the following attributes:

  • schemas set to urn:ietf:params:scim:schemas:core:2.0:User
  • userName

Example request

POST /api/2.0/preview/scim/v2/Users HTTP/1.1
Host: <region>.azuredatabricks.net
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json

{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User"
   ],
   "userName":"example@databricks.com",
   "groups":[
      {
         "value":"123456"
      }
   ],
   "entitlements":[
      {
         "value":"allow-cluster-create"
      }
   ]
}

Update User by ID (PATCH)

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} PATCH

Update a user resource with operations on specific attributes, except those that are immutable. The PATCH method is recommended over the PUT method for setting or updating user entitlements.

Request parameters follow the standard SCIM 2.0 protocol and depend on the value of the schemas attribute.

Example request

PATCH /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <region>.azuredatabricks.net
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
   ],
   "Operations":[
      {
         "op":"add",
         "path":"entitlements",
         "value":[
            {
               "value":"allow-cluster-create"
            }
         ]
      }
   ]
}

Update User by ID (PUT)

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} PUT

Overwrite the user resource across multiple attributes, except those that are immutable.

Request must include the schemas attribute, set to urn:ietf:params:scim:schemas:core:2.0:User.

Note

The PATCH method is recommended over the PUT method for setting or updating user entitlements.

Example request

PUT /api/2.0/preview/scim/v2/Users/123456  HTTP/1.1
Host: <region>.azuredatabricks.net
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User"
   ],
   "userName":"example@databricks.com",
   "entitlements":[
      {
         "value":"allow-cluster-create"
      }
   ],
   "groups":[
      {
         "value":"100000"
      }
   ]
}

Delete User by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} DELETE

Inactivate a user resource. A user that does not own or belong to a workspace in Azure Databricks is automatically purged after 30 days.

Example request

DELETE /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Get Groups

Endpoint HTTP Method
2.0/preview/scim/v2/Groups GET

Retrieve a list of all groups in the Azure Databricks workspace.

Example request

GET /api/2.0/preview/scim/v2/Groups  HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

You can use Filters to specify subsets of groups. For example, you can apply the sw (starts with) filter parameter to displayName to retrieve a specific group or set of groups:

GET /api/2.0/preview/scim/v2/Groups?filter=displayName+sw+eng    HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Get Group by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Groups/{id} GET

Retrieve a single group resource.

Example request

GET /api/2.0/preview/scim/v2/Groups/123456  HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Create Group

Endpoint HTTP Method
2.0/preview/scim/v2/Groups POST

Create a group in Azure Databricks.

Request parameters follow the standard SCIM 2.0 protocol.

Requests must include the following attributes:

  • schemas set to urn:ietf:params:scim:schemas:core:2.0:Group
  • displayName

Members list is optional and can include users and other groups. You can also add members to a group using PATCH.

Example request

POST /api/2.0/preview/scim/v2/Groups HTTP/1.1
Host: <region>.azuredatabricks.net
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json

{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:Group"
   ],
   "displayName":"newgroup",
   "members":[
      {
         "value":"100000",
      },
      {
         "value":"100001",
      }
   ]
}

Update Group

Endpoint HTTP Method
2.0/preview/scim/v2/Groups/{id} PATCH

Update a group in Azure Databricks by adding or removing members. Can add and remove individual members or groups within the group.

Request parameters follow the standard SCIM 2.0 protocol and depend on the value of the schemas attribute.

Note

Azure Databricks does not support the update of group names.

Example request

PATCH /api/2.0/preview/scim/v2/Groups/123456 HTTP/1.1
Host: <region>.azuredatabricks.net
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json

{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
   ],
   "Operations":[
      {
         "op":"add",
         "value":{
            "members":[
               {
                  "value":"100000"
               }
            ]
         }
      }
   ]
}

Delete Group

Endpoint HTTP Method
2.0/preview/scim/v2/Groups/{id} DELETE

Remove a group from Azure Databricks. Users in the group are not removed.

Example request

DELETE /api/preview/scim/v2/Groups/123456  HTTP/1.1
Host: <region>.azuredatabricks.net
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Filters

Use filters with Users and Groups GET calls to return a subset of users or groups.

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.