SCIM API 2.0 (ServicePrincipals) for workspaces
Important
This feature is in Public Preview.
This is a reference article for the workspace-level SCIM API for Service Principals.
You can use the SCIM (ServicePrincipals) to add, read, update, and delete Azure Active Directory service principals in Azure Databricks.
For information about using APIs to provision service principals directly to your account instead, see SCIM API 2.0 (Accounts). For information about when to use account-level or workspace-level SCIM provisioning, see Account-level and workspace-level SCIM provisioning.
For error codes, see SCIM API 2.0 Error Codes.
For more examples, see Service principals for Azure Databricks automation.
Requirements
Your Azure Databricks account must have the Premium Plan.
Get service principals
| Endpoint | HTTP Method |
|---|---|
2.0/preview/scim/v2/ServicePrincipals |
GET |
Retrieve a list of all service principals in the Azure Databricks workspace.
When invoked by a non-admin user, only the username, user display name, and object are returned.
Examples
curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals \
| jq .
You can use filters to specify subsets of service principals. For example, you can apply the eq (equals) filter parameter to applicationId to retrieve a specific service principal:
curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals?filter=applicationId+eq+<application-id>" \
| jq .
In workspaces with a large number of service principals, you can exclude attributes from the request to improve performance.
curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals?excludedAttributes=entitlements,groups" \
| jq .
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<application-id>with theapplicationIdvalue of the service principal, for example12345a67-8b9c-0d1e-23fa-4567b89cde01.
These examples use a .netrc file and jq.
Get service principal by ID
| Endpoint | HTTP Method |
|---|---|
2.0/preview/scim/v2/ServicePrincipals/{id} |
GET |
Retrieve a single service principal resource from the Azure Databricks workspace, given a service principal ID.
Example
curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
| jq .
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.
This example uses a .netrc file and jq.
Add service principal
| Endpoint | HTTP Method |
|---|---|
2.0/preview/scim/v2/ServicePrincipals |
POST |
Add an Azure Active Directory (Azure AD) service principal to the Azure Databricks workspace. In Azure Databricks, you must create an application in Azure Active Directory and then add it to your Azure Databricks workspace to use as a service principal. The service principal will automatically be added to the account. See How does Databricks sync identities between workspaces and the account?. Service principals count toward the limit of 10000 users per workspace.
Request parameters follow the standard SCIM 2.0 protocol.
Example
curl --netrc -X POST \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals \
--header 'Content-type: application/scim+json' \
--data @add-service-principal.json \
| jq .
add-service-principal.json:
{
"schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal" ],
"applicationId": "<azure-application-id>",
"displayName": "<display-name>",
"groups": [
{
"value": "<group-id>"
}
],
"entitlements": [
{
"value":"allow-cluster-create"
}
]
}
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<azure-application-id>with the application ID of the Azure Active Directory (Azure AD) application, for example12345a67-8b9c-0d1e-23fa-4567b89cde01<display-name>with the display name of the service principal, for examplesomeone@example.com.<group-id>with the ID of the group in the Azure Databricks workspace, for example2345678901234567. To get the group ID, call Get groups.
This example uses a .netrc file and jq.
For lists of available entitlements by Azure Databricks identity type, see:
- Assigning entitlements
- Assign entitlements to a workspace user
- Manage a group’s workspace entitlements
- Manage entitlements for a service principal
Update service principal by ID (PATCH)
| Endpoint | HTTP Method |
|---|---|
2.0/preview/scim/v2/ServicePrincipals/{id} |
PATCH |
Update a service principal resource with operations on specific attributes,
except for displayName, applicationId, and id, which are immutable.
Use the PATCH method to add, update, or remove individual attributes.
Use the PUT method to overwrite the
entire service principal in a single operation.
Request parameters follow the standard SCIM 2.0 protocol and depend on the value
of the schemas attribute.
Add entitlements
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @change-service-principal.json \
| jq .
change-service-principal.json:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "add",
"path": "entitlements",
"value": [
{
"value": "allow-cluster-create"
}
]
}
]
}
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.
This example uses a .netrc file and jq.
For lists of available entitlements by Azure Databricks identity type, see:
- Assigning entitlements
- Assign entitlements to a workspace user
- Manage a group’s workspace entitlements
- Manage entitlements for a service principal
Remove entitlements
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @change-service-principal.json \
| jq .
change-service-principal.json:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "remove",
"path": "entitlements",
"value": [
{
"value": "allow-cluster-create"
}
]
}
]
}
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.
This example uses a .netrc file and jq.
For lists of available entitlements by Azure Databricks identity type, see:
- Assigning entitlements
- Assign entitlements to a workspace user
- Manage a group’s workspace entitlements
- Manage entitlements for a service principal
Add to a group
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @change-service-principal.json \
| jq .
change-service-principal.json:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "add",
"path": "groups",
"value": [
{
"value": "<group-id>"
}
]
}
]
}
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.<group-id>with the ID of the group in the Azure Databricks workspace, for example2345678901234567. To get the group ID, call Get groups.
This example uses a .netrc file and jq.
Remove from a group
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @remove-from-group.json \
| jq .
remove-from-group.json:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "remove",
"path": "members[value eq \"<service-principal-id>\"]"
}
]
}
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<group-id>with the ID of the group in the Azure Databricks workspace, for example2345678901234567. To get the group ID, call Get groups.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.
This example uses a .netrc file and jq.
Update service principal by ID (PUT)
| Endpoint | HTTP Method |
|---|---|
2.0/preview/scim/v2/ServicePrincipals/{id} |
PUT |
Overwrite the entire service principal resource, except for displayName, applicationId, and id, which are immutable.
Use the PATCH method to add, update, or remove individual attributes.
Important
You must include the schemas attribute in the request, with the exact
value urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal.
Examples
Add an entitlement
curl --netrc -X PUT \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @update-service-principal.json \
| jq .
update-service-principal.json:
{
"schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal" ],
"applicationId": "<applicationId-id>",
"displayName": "<display-name>",
"groups": [
{
"value": "<group-id>"
}
],
"entitlements": [
{
"value":"allow-cluster-create"
}
]
}
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.<application-id>with theapplicationIdvalue of the service principal, for example12345a67-8b9c-0d1e-23fa-4567b89cde01.<display-name>with the display name of the service principal, for examplesomeone@example.com.<group-id>with the ID of the group in the Azure Databricks workspace, for example2345678901234567. To get the group ID, call Get groups.
This example uses a .netrc file and jq.
For lists of available entitlements by Azure Databricks identity type, see:
- Assigning entitlements
- Assign entitlements to a workspace user
- Manage a group’s workspace entitlements
- Manage entitlements for a service principal
Remove all entitlements and groups
Removing all entitlements and groups is a reversible alternative to deactivating the service principal.
Use the PUT method to avoid the need to check the existing entitlements and
group memberships first.
curl --netrc -X PUT \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @update-service-principal.json \
| jq .
update-service-principal.json:
{
"schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal" ],
"applicationId": "<application-id>",
"displayName": "<display-name>",
"groups": [],
"entitlements": []
}
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.<application-id>with theapplicationIdvalue of the service principal, for example12345a67-8b9c-0d1e-23fa-4567b89cde01.<display-name>with the display name of the service principal, for examplesomeone@example.com.
This example uses a .netrc file and jq.
Deactivate service principal by ID
| Endpoint | HTTP Method |
|---|---|
2.0/preview/scim/v2/ServicePrincipals/{id} |
DELETE |
Deactivate a service principal resource. This operation isn’t reversible.
Example
curl --netrc -X DELETE \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id>
Replace:
<databricks-instance>with the Azure Databricks workspace instance name, for exampleadb-1234567890123456.7.azuredatabricks.net.<service-principal-id>with the ID of the service principal, for example2345678901234567. To get the service principal ID, call Get service principals.
This example uses a .netrc file.
As a reversible alternative, you can remove all of its entitlements and groups instead of deleting the service principal.
A service principal that does not own or belong to an Azure Databricks workspace is automatically purged after 30 days.
Feedback
Submit and view feedback for