Manage identity attributes with account SCIM

The account System for Cross-domain Identity Management (SCIM) 2.1 API provisions the nine identity attributes to Databricks account users, either through a provisioning connector or directly.

Beta

This feature is in Beta. Account admins can manage access to this feature from the account console Previews page. See Manage account-level previews.

Databricks recommends automatic identity management over SCIM for managing identity attributes. For more information, see Automatic identity management.

Prerequisites

You must be an account admin.
Set up account-level SCIM provisioning for your account. See Sync users and groups to your Databricks account.
Identity attributes are managed on account SCIM 2.1, at https://accounts.cloud.databricks.com/api/2.1/accounts/<account-id>/scim/v2/. This is the only surface that reads and writes the full set of attributes.
You don't need to enable the Identity Attribute Control List feature preview to write attributes through SCIM. If the preview is enabled, make sure the attributes you intend to push are on your account's attribute control list, or the write is rejected. See Identity Attribute Control List.

Configure a SCIM connector

Identity attributes reach Databricks from your identity provider either through a SCIM provisioning connector that pushes them, or through automatic identity management, which pulls them. This section covers the connector route for Okta and Microsoft Entra ID.

In both providers the work is the same in outline: extend the provider's outbound schema so it knows the nine Databricks attributes exist, map each one to a source attribute on the user profile, then sync. You can update your existing SCIM connector application to do this; you don't need to create a new app in your identity provider.

Okta

Create the Databricks SCIM connector application first, following the standard Okta setup for Databricks. Then extend its outbound schema.

Go to Applications > your Databricks application > Provisioning > To App, then open Go to Profile Editor.
Choose Add Attribute and add the nine attributes in the following table. All nine are of data type string.
For External namespace, use urn:ietf:params:scim:schemas:core:2.0:User for the first five attributes (Title through Work Country) and urn:ietf:params:scim:schemas:extension:enterprise:2.0:User for the last four (Cost Center through Department).
Return to the Provisioning tab and edit the Mappings section to map each Databricks attribute to the Okta user-profile attribute it should draw from.

The External name and External namespace are what Okta sends on the wire, so they must match the SCIM paths exactly.

Display name	Variable name	External name
Title	`title`	`title`
User Type	`userType`	`userType`
Work Locality	`workLocality`	`addresses.^[type=='work'].locality`
Work Region	`workRegion`	`addresses.^[type=='work'].region`
Work Country	`workCountry`	`addresses.^[type=='work'].country`
Cost Center	`costCenter`	`costCenter`
Organization	`organization`	`organization`
Division	`division`	`division`
Department	`department`	`department`

Display name	Variable name	External name
Title	`title`	`title`
User Type	`userType`	`userType`
Work Locality	`workLocality`	`addresses.^[type=='work'].locality`
Work Region	`workRegion`	`addresses.^[type=='work'].region`
Work Country	`workCountry`	`addresses.^[type=='work'].country`
Cost Center	`costCenter`	`costCenter`
Organization	`organization`	`organization`
Division	`division`	`division`
Department	`department`	`department`

To test the result, create a user under Directory > People > Add person, set the mapped attributes on their profile, then assign them to the application under the Assignments tab. Open the Provisioning tab and choose Force Sync if you need the attributes synced immediately. The attributes appear on the user in the Databricks account console within about five minutes.

The Okta connector behaves as follows:

Attribute values are case-sensitive and are stored exactly as sent.
The symbols _, -, . and spaces sync without trouble.
Array-valued attributes are not supported. Mapping one produces an error in Okta and the value in Databricks is left unchanged. This applies even to a single-element array.

Microsoft Entra ID

Create the SCIM provisioning application in Microsoft Entra ID following the standard Microsoft Entra ID setup for Databricks.

The schema editor isn't exposed by default. Append ?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true to the portal URL and keep it set for the whole configuration session. Without it, the Edit schema option won't appear.

Open your application and go to Provisioning > Attribute mapping.
Under Advanced options, choose Edit Databricks User Attributes.
Add the following nine attributes, all of type String:
- title
- userType
- addresses[type eq "work"].locality
- addresses[type eq "work"].region
- addresses[type eq "work"].country
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
Return to the attribute-mapping screen and choose Add Attribute Mapping for each attribute, using a Direct mapping type and the source attributes in the following table.

Microsoft Entra ID has no native source field for cost center or division, so leave those two unmapped unless you have a suitable custom extension attribute or expression to bind them to.

Databricks target	Microsoft Entra ID source attribute
`title`	`jobTitle`
`userType`	`employeeType`
`addresses[type eq "work"].locality`	`city`
`addresses[type eq "work"].region`	`state`
`addresses[type eq "work"].country`	`country`
`...:enterprise:2.0:User:organization`	`companyName`
`...:enterprise:2.0:User:department`	`department`
`...:enterprise:2.0:User:costCenter`	not mapped
`...:enterprise:2.0:User:division`	not mapped

Databricks target	Microsoft Entra ID source attribute
`title`	`jobTitle`
`userType`	`employeeType`
`addresses[type eq "work"].locality`	`city`
`addresses[type eq "work"].region`	`state`
`addresses[type eq "work"].country`	`country`
`...:enterprise:2.0:User:organization`	`companyName`
`...:enterprise:2.0:User:department`	`department`
`...:enterprise:2.0:User:costCenter`	not mapped
`...:enterprise:2.0:User:division`	not mapped

To test, create a user under Users > New User and populate the mapped fields. Add them to the application under Provisioning > Users and Groups, then open Provision on demand and select the user. The attributes then appear on the user's Identity attributes tab in the Databricks account console. Clearing an attribute's value on the Microsoft Entra ID user and provisioning on demand again removes the value in Databricks, so the two sides stay in step.

note

If a previously healthy connector begins failing after the attribute control list is enabled or narrowed, the cause is almost always that the connector is still pushing an attribute the account no longer allows. Databricks rejects the whole request with a 400, so the sync fails rather than partially applying. To fix it, either add the attribute back to the control list or remove that attribute from the connector's mapping, then force a sync again. A connector re-pushing an unchanged value isn't rejected, because enforcement only applies to values that actually change. See Identity Attribute Control List.

Manage attributes with the SCIM API

Identity attributes are managed on account SCIM 2.1. Five of the attributes sit on the SCIM core User schema, and the other four sit on the standard enterprise user extension, whose URN is urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.

Attribute	Where it lives in SCIM
`title`	Core User: `title`
`userType`	Core User: `userType`
`locality`	Core User: `addresses[type eq "work"].locality`
`region`	Core User: `addresses[type eq "work"].region`
`country`	Core User: `addresses[type eq "work"].country`
`costCenter`	Enterprise extension: `costCenter`
`organization`	Enterprise extension: `organization`
`division`	Enterprise extension: `division`
`department`	Enterprise extension: `department`

Attribute	Where it lives in SCIM
`title`	Core User: `title`
`userType`	Core User: `userType`
`locality`	Core User: `addresses[type eq "work"].locality`
`region`	Core User: `addresses[type eq "work"].region`
`country`	Core User: `addresses[type eq "work"].country`
`costCenter`	Enterprise extension: `costCenter`
`organization`	Enterprise extension: `organization`
`division`	Enterprise extension: `division`
`department`	Enterprise extension: `department`

In requests and responses, the four enterprise attributes are addressed by their fully-qualified path. For example, urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter.

Create a user with identity attributes

Text
POST /api/2.1/accounts/<account-id>/scim/v2/Users
Authorization: Bearer <token>
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane.doe@example.com",
  "displayName": "Jane Doe",
  "title": "Staff Engineer",
  "userType": "Employee",
  "addresses": [
    { "locality": "Mountain View", "region": "CA", "country": "US" }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "costCenter": "4130",
    "organization": "Databricks",
    "division": "Platform",
    "department": "Identity"
  }
}

Databricks responds 201 Created with the full user record. The response shape has the following characteristics:

schemas always advertises both the core User URN and the enterprise extension URN, even when no enterprise attributes are set.
Attributes with no stored value are omitted entirely rather than returned as null.
Exactly one address is stored per user, so addresses always holds a single element. Databricks stamps it "type": "work" and "primary": true automatically; both are read-only and can't be mapped from an identity provider.
Account SCIM 2.1 doesn't return meta or entitlements on users.

Read identity attributes

Text
GET /api/2.1/accounts/<account-id>/scim/v2/Users/<user-id>
Authorization: Bearer <token>

The response has the same shape as the create response. Reads are never filtered by the attribute control list. An attribute stored earlier stays fully visible on a GET even after it is removed from the control list. Only writes are gated.

Update identity attributes

All three PATCH operation forms (add, replace, and remove) work for every attribute, including the fully-qualified enterprise paths.

Text
PATCH /api/2.1/accounts/<account-id>/scim/v2/Users/<user-id>
Authorization: Bearer <token>
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "title", "value": "Principal Engineer" },
    { "op": "replace", "path": "userType", "value": "Contractor" },
    {
      "op": "replace",
      "path": "addresses",
      "value": [{ "locality": "Seattle", "region": "WA", "country": "US" }]
    },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter",
      "value": "9001"
    }
  ]
}

Databricks responds 200 OK with the updated user. addresses is replaced as a whole complex value, so send every sub-field you want to keep. Omitting country from the value above would clear it.

Remove identity attributes

Text
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "remove", "path": "userType" },
    {
      "op": "remove",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division"
    }
  ]
}

Databricks responds 200 OK, and the removed attributes no longer appear in the user record. Removals always succeed regardless of the attribute control list, so an administrator can always retire a stored value, including for an attribute the account is no longer permitted to write.

When the attribute control list rejects a write

Once your account is enrolled in the Identity Attribute Control List preview, writing an attribute that isn't on the list is rejected. For example, sending {"op": "replace", "path": "userType", "value": "Vendor"} when userType is off the list returns 400 Bad Request:

JSON
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "The following identity attributes are not on this account's attribute control list and cannot be created or updated: userType. Add them to the control list, or remove them from the request. Existing values can still be removed."
}

Before you integrate, understand the following enforcement behaviors:

Enforcement is per attribute, not per schema. An off-list enterprise attribute such as division is rejected even when other enterprise attributes in the same request are allowed.
A PATCH is atomic. If any operation targets an off-list attribute, the whole request is rejected and none of the allowed changes apply. Validation runs before the user record is touched.
Only changed values are checked. Re-sending a value identical to the stored one is a no-op and passes even for an off-list attribute. This matters for identity provider connectors, which re-push unchanged values on every sync.
Address sub-fields are checked individually. locality, region, and country each need their own control-list entry.

For how to configure the list, see Identity Attribute Control List.

Discover supported attributes

GET /api/2.1/accounts/<account-id>/scim/v2/Schemas returns a SCIM ListResponse. When identity attributes are enabled for the surface, it contains four schema resources: User (which supports the additional attributes described on this page), Group, ServicePrincipal, and the enterprise user extension.

The core User schema advertises title, userType, and addresses. Within addresses, the three identity provider-sourced sub-attributes are readWrite, while type and primary are readOnly because Databricks sets them:

JSON
{
  "name": "addresses",
  "type": "complex",
  "multiValued": true,
  "description": "A physical mailing address for this user.",
  "mutability": "readWrite",
  "returned": "default",
  "subAttributes": [
    { "name": "locality", "type": "string", "mutability": "readWrite" },
    { "name": "region", "type": "string", "mutability": "readWrite" },
    { "name": "country", "type": "string", "mutability": "readWrite" },
    { "name": "type", "type": "string", "mutability": "readOnly", "canonicalValues": ["work"] },
    { "name": "primary", "type": "boolean", "mutability": "readOnly" }
  ]
}

The enterprise extension is also resolvable on its own at GET /api/2.1/accounts/<account-id>/scim/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User, which returns the four enterprise attributes as readWrite strings:

JSON
{
  "id": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
  "name": "EnterpriseUser",
  "description": "Enterprise User",
  "attributes": [
    { "name": "costCenter", "type": "string", "mutability": "readWrite" },
    { "name": "department", "type": "string", "mutability": "readWrite" },
    { "name": "division", "type": "string", "mutability": "readWrite" },
    { "name": "organization", "type": "string", "mutability": "readWrite" }
  ],
  "meta": { "resourceType": "Schema" }
}

The /Schemas output is static. It isn't affected by the attribute control list or by what any individual user has set. It reflects only whether the surface manages identity attributes at all.

Read your own attributes

Account SCIM for workspaces is served from the workspace host at https://<workspace-host>/api/2.0/account/scim/v2/. This surface doesn't expose identity attributes on reads or writes, and workspace administrators aren't permitted to read or modify other users' identity attributes.

warning

Writes to identity attributes on this surface return 2xx but are silently dropped, not rejected. A successful response does not mean the attribute was stored. To write identity attributes, use account SCIM 2.1. See Manage attributes with the SCIM API.

/Me is the single exception. Because it returns only the caller's own profile, a user can read their own identity attributes there:

Text
GET /api/2.0/account/scim/v2/Me
Authorization: Bearer <workspace-token>

JSON
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "1234567890123456",
  "userName": "jane.doe@example.com",
  "displayName": "Jane Doe",
  "active": true,
  "emails": [{ "type": "work", "primary": true, "value": "jane.doe@example.com" }],
  "name": { "givenName": "Jane", "familyName": "Doe" },
  "title": "Staff Engineer",
  "userType": "Employee",
  "addresses": [
    {
      "locality": "Mountain View",
      "region": "CA",
      "country": "US",
      "type": "work",
      "primary": true
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "costCenter": "4130",
    "organization": "Databricks",
    "division": "Platform",
    "department": "Identity"
  },
  "groups": [{ "value": "987654321098765", "display": "engineering" }]
}

Keep the following in mind about /Me:

/Me is read-only here. POST, PUT, PATCH, and DELETE return 501 with "detail": "Endpoint not supported."
groups is always returned on /Me, unlike an administrative user read.
The attribute control list has no effect on /Me, since the list governs writes and /Me can't write.
Workspace-level SCIM (/api/2.0/preview/scim/v2/) is a different API and never exposes account-level identity attributes on any endpoint, including its own /Me.

Prerequisites​

Configure a SCIM connector​

Okta​

Microsoft Entra ID​

Manage attributes with the SCIM API​

Create a user with identity attributes​

Read identity attributes​

Update identity attributes​

Remove identity attributes​

When the attribute control list rejects a write​

Discover supported attributes​

Read your own attributes​