SCIM API 2.0 (Groups)

Preview

This feature is in Public Preview.

Requirements

Your Databricks account must have the Premium plan (or, for customers who subscribed to Databricks before March 3, 2020, the Operational Security package).

Note

  • A Databricks administrator can invoke all SCIM API endpoints.
  • Non-admin users can invoke the Get groups endpoint to read group display names and IDs.
  • You can have no more than 10,000 users and 5,000 groups in a workspace.

SCIM (Groups) lets you create groups in Databricks and give them the proper level of access, remove access for groups (deprovision them), and add roles to and remove roles from groups.

Get groups

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

Admin users: Retrieve a list of all groups in the Databricks workspace.

Non-admin users: Retrieve a list of all groups in the Databricks workspace, returning group display name and object ID only.

Examples

curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups \
| jq .

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. This example retrieves all groups with a displayName field that start with my-.

curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/Groups?filter=displayName+sw+my-" \
| jq .

Replace <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

This example uses a .netrc file and jq.

Get group by ID

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

Admin users: Retrieve a single group resource.

Example request

curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
| jq .

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.
  • <group-id> with the Databricks workspace ID of the group, for example 2345678901234567. To get the group ID, call Get groups.

This example uses a .netrc file and jq.

Create group

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

Admin users: Create a group in 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

curl --netrc -X POST \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups \
--header 'Content-type: application/scim+json' \
--data @create-group.json \
| jq .

create-group.json:

{
  "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ],
  "displayName": "<group-name>",
  "members": [
    {
      "value":"<user-id>"
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.
  • <group-name> with the Databricks workspace name of the group, for example my-group.
  • <user-id> with the Databricks workspace ID of the user, for example 2345678901234567. To get the user ID, call Get users.

This example uses a .netrc file and jq.

Update group

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

Admin users: Update a group in 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

Databricks does not support updating group names.

Example

curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @update-group.json \
| jq .

Add to group

update-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op":"add",
      "value": {
        "members": [
          {
            "value":"<user-id>"
          }
        ]
      }
    }
  ]
}

Remove from group

update-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"<user-id>\"]"
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.
  • <group-id> with the Databricks workspace ID of the group, for example 2345678901234567. To get the group ID, call Get groups.
  • <user-id> with the Databricks workspace ID of the user, for example 2345678901234567. To get the user ID, call Get users.

This example uses a .netrc file and jq.

Delete group

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

Admin users: Remove a group from Databricks. Users in the group are not removed.

Example

curl --netrc -X DELETE \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id>

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.
  • <group-id> with the Databricks workspace ID of the group, for example 2345678901234567. To get the group ID, call Get groups.

This example uses a .netrc file.

You can also add roles to a group or remove roles from a group using the SCIM API.

Add role to a group by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Groups/{id} PATCH
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @add-role-to-group.json \
| jq .

add-role-to-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "add",
      "path": "roles",
      "value": [
        {
          "value": "<role-arn>"
        }
      ]
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.
  • <group-id> with the Databricks workspace ID of the group, for example 2345678901234567. To get the group ID, call Get groups.
  • <role-arn> with the Amazon Resource Name (ARN) of the role, for example arn:aws:iam::123456789012:role/my-role.

This example uses a .netrc file and jq.

Remove role from a group by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Groups/{id} PATCH
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @remove-role-from-group.json \
| jq .

remove-role-from-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "remove",
      "path": "roles[value eq \"<role-arn>\"]"
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.
  • <group-id> with the Databricks workspace ID of the group, for example 2345678901234567. To get the group ID, call Get groups.
  • <role-arn> with the Amazon Resource Name (ARN) of the role, for example arn:aws:iam::123456789012:role/my-role.

This example uses a .netrc file and jq.