mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
Wim Van LaerandGitHub
699ed17918
# Which Problems Are Solved naming inconsistencies: Configuration <-> Settings # How the Problems Are Solved # Additional Changes # Additional Context - Closes #11282
125 lines
14 KiB
Plaintext
125 lines
14 KiB
Plaintext
---
|
||
title: SCIM v2.0
|
||
---
|
||
|
||
Zitadel’s **[SCIM v2](https://scim.cloud/) service provider interface** enables standardized provisioning and lifecycle management of users and other instance resources.
|
||
By implementing the official *System for Cross-domain Identity Management (SCIM) v2.0* specification, Zitadel allows seamless and automated user creation, updates, deactivation, and deprovisioning across systems.
|
||
|
||
## API
|
||
|
||
For full reference details of Zitadel’s SCIM API, consult the API documentation [here](/apis/scim2).
|
||
|
||
## Provisioning domain
|
||
|
||
A **provisioning domain** represents an external administrative domain—separate from the service provider—typically introduced for legal, organizational, or technical reasons.
|
||
Refer to the SCIM specification definitions in **RFC7643**:
|
||
https://datatracker.ietf.org/doc/html/rfc7643#section-1.2
|
||
|
||
Zitadel uses provisioning domains to scope the handling of the SCIM **`externalId`**, ensuring that different customers or systems provisioning users do not conflict with each other.
|
||
|
||
### Setting a provisioning domain
|
||
|
||
A provisioning domain can be assigned to a **service account** by adding the following metadata entry:
|
||
|
||
- **Key:** `urn:zitadel:scim:provisioningDomain`
|
||
- **Value:** the name of the provisioning domain
|
||
|
||
### How Zitadel stores `externalId`
|
||
|
||
If a service account has a provisioning domain set, any SCIM `externalId` provided during user provisioning or lookup is stored under:
|
||
`urn:zitadel:scim:{provisioningDomain}:externalId`
|
||
|
||
If *no* provisioning domain is configured, Zitadel falls back to a simplified metadata key:
|
||
`urn:zitadel:scim:externalId`
|
||
|
||
This ensures that different provisioning sources remain isolated, and the correct `externalId` is returned when queried through SCIM.
|
||
|
||
## Mapping
|
||
|
||
The following table describes how Zitadel maps SCIM User attributes to Zitadel user fields.
|
||
Attributes without a direct Zitadel equivalent are stored in **user metadata**.
|
||
For more information about user metadata, see [here](../customize/user-metadata).
|
||
|
||
| SCIM | Zitadel | Remarks |
|
||
|------------------------|-----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| `id` | `userId` | |
|
||
| `username` | `username` | |
|
||
| `name.formatted` | `profile.displayName` | The SCIM attribute `displayName` takes precedence over `name.formatted` |
|
||
| `name.familyName` | `profile.familyName` | |
|
||
| `name.middleName` | `metadata[urn:zitadel:scim:name.middleName]` | |
|
||
| `name.honorificPrefix` | `metadata[urn:zitadel:scim:name.honorificPrefix]` | |
|
||
| `name.honorificSuffix` | `metadata[urn:zitadel:scim:name.honorificSuffix]` | |
|
||
| `displayName` | `profile.displayName` | The SCIM attribute `displayName` takes precedence over `name.formatted` |
|
||
| `nickName` | `profile.nickName` | |
|
||
| `profileUrl` | `metadata[urn:zitadel:scim:profileUrl]` | |
|
||
| `title` | `metadata[urn:zitadel:scim:title]` | |
|
||
| `preferredLanguage` | `profile.preferredLanguage` | |
|
||
| `locale` | `metadata[urn:zitadel:scim:locale]` | |
|
||
| `timezone` | `metadata[urn:zitadel:scim:timezone]` | |
|
||
| `active` | `state` | `Initial` and `Active` are mapped to `active = true`, all other states are mapped to `active = false`.<br />The `active` value can only be updated if the user is in the state `Active` or `Inactive`. |
|
||
| `password` | `password` | |
|
||
| `emails` | `email` | Only the `primary` email is stored in Zitadel, if there is no `primary` email, the first one is stored. By default emails from SCIM are considered verified, this can be adjusted in the [settings](#settings). |
|
||
| `phoneNumbers` | `phone` | Only the `primary` phone number is stored in Zitadel, if there is no `primary` phone number, the first one is stored. By default phone numbers from SCIM are considered verified, this can be adjusted in the [settings](#settings). |
|
||
| `ims` | `metadata[urn:zitadel:scim:ims]` | Serialized as JSON. |
|
||
| `photos` | `metadata[urn:zitadel:scim:photos]` | Serialized as JSON. |
|
||
| `addresses` | `metadata[urn:zitadel:scim:addresses]` | Serialized as JSON. |
|
||
| `entitlements` | `metadata[urn:zitadel:scim:entitlements]` | Serialized as JSON. |
|
||
| `roles` | `metadata[urn:zitadel:scim:roles]` | Serialized as JSON. |
|
||
| `externalId` | `metadata[urn:zitadel:scim:externalId]`<br />`metadata[urn:zitadel:scim:{provisioningDomain}:externalId]` | See [provisioning domain](#provisioning-domain). |
|
||
|
||
## Settings
|
||
|
||
This section provides details on the runtime settings of the SCIM interface of Zitadel.
|
||
|
||
### Defaults
|
||
|
||
- Emails from SCIM are treated as **verified**
|
||
- Phone numbers from SCIM are treated as **verified**
|
||
- Bulk SCIM operations can include up to **100 operations**
|
||
- Maximum SCIM request body size is **1 MB**
|
||
|
||
This behavior can be adjusted through the Zitadel runtime settings:
|
||
|
||
```yaml
|
||
SCIM:
|
||
EmailVerified: true
|
||
PhoneVerified: true
|
||
MaxRequestBodySize: 1_000_000
|
||
Bulk:
|
||
MaxOperationsCount: 100
|
||
```
|
||
|
||
## Limitations
|
||
|
||
Zitadel’s SCIM implementation follows the core SCIM specification but includes the following limitations.
|
||
|
||
### Supported schemas
|
||
|
||
Zitadel currently supports only the SCIM User schema: `urn:ietf:params:scim:schemas:core:2.0:User`
|
||
Group provisioning and other extended schemas are not supported.
|
||
|
||
### Required attributes
|
||
|
||
In addition to SCIM-standard required fields, Zitadel requires:
|
||
|
||
* `name.familyName`
|
||
* `name.givenName`
|
||
* `emails`: at least one email is required
|
||
|
||
### Duplicated attribute mapping
|
||
|
||
The SCIM user attributes `name.formatted` and `displayName` are both mapped to the `profile.displayName` attribute in
|
||
Zitadel.
|
||
If both are provided, `displayName` always takes precedence and is the value that will be stored and returned in future SCIM queries.
|
||
|
||
## Resources
|
||
|
||
- **[Zitadel SCIM API Documentation](/apis/scim2)**: Documentation of Zitadel's SCIM API implementation.
|
||
- **[SCIM](https://scim.cloud/)**: The Webpage of SCIM.
|
||
- **[RFC7643](https://tools.ietf.org/html/rfc7643) Core Schema**:
|
||
The Core Schema provides a platform-neutral schema and extension model for representing users and groups.
|
||
- **[RFC7644](https://tools.ietf.org/html/rfc7644) Protocol**:
|
||
The SCIM Protocol is an application-level, REST protocol for provisioning and managing identity data on the web.
|
||
- **[RFC7642](https://tools.ietf.org/html/rfc7642) Definitions, Overview, Concepts, and Requirements**:
|
||
This document lists the user scenarios and use cases of System for Cross-domain Identity Management (SCIM).
|