SCIM API (Groups)

Preview

This feature is in Public Preview.

Note

  • A Databricks administrator can invoke all SCIM API endpoints.
  • Non-admin users can invoke the Groups Get endpoint to read group display names and IDs.

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.

Example request

GET /api/2.0/preview/scim/v2/Groups  HTTP/1.1
Host: <databricks-instance>
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: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Get group by ID

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

Admin users: Retrieve a single group resource.

Example request

GET /api/2.0/preview/scim/v2/Groups/123456  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

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 request

POST /api/2.0/preview/scim/v2/Groups HTTP/1.1
Host: <databricks-instance>
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

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 requests

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

Add to group

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

Remove from group

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

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 request

DELETE /api/preview/scim/v2/Groups/123456  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

You can also add roles to a group using the SCIM API

Add role to a group by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Groups/{id} PATCH
PATCH /api/2.0/preview/scim/v2/Groups/100757  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b
{
  "schemas":[
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
    {
      "op":"add",
      "path":"roles",
      "value":[
        {
           "value":"arn:aws:iam::123456789012:role/<role-name>"
        }
      ]
    }
  ]
}

Remove role from a group by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Groups/{id} PATCH
PATCH /api/2.0/preview/scim/v2/Groups/100757  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b
{
  "schemas":[
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
    {
      "op":"remove",
      "path": "roles[value eq \"arn:aws:iam::123456789012:role/<role-name>\"]"
    }
  ]
}