mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
d8ea041c56
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
859 lines
23 KiB
Plaintext
859 lines
23 KiB
Plaintext
---
|
|
title: SCIM v2.0 (Preview)
|
|
---
|
|
|
|
The Zitadel [SCIM v2](https://scim.cloud/) service provider interface enables seamless integration of identity and
|
|
access management (IAM) systems with Zitadel,
|
|
following the System for Cross-domain Identity Management (SCIM) v2.0 specification.
|
|
This interface allows standardized management of IAM resources, making it easier to automate user provisioning and
|
|
deprovisioning.
|
|
|
|
## Supported endpoints
|
|
|
|
The Zitadel SCIM v2.0 service provider implementation supports the following endpoints.
|
|
The base URL for the SCIM endpoint in Zitadel is: `https://${CUSTOM_DOMAIN}/scim/v2/{orgId}`.
|
|
|
|
| Endpoint | Remarks |
|
|
|-------------------------------------------------------------------------|------------------------------------------------------------|
|
|
| `GET /scim/v2/{orgId}/ServiceProviderConfig` | Retrieve the configuration of the Zitadel service provider |
|
|
| `GET /scim/v2/{orgId}/Schemas` | Retrieve all supported schemas |
|
|
| `GET /scim/v2/{orgId}/Schemas/{id}` | Retrieve a known supported schema |
|
|
| `GET /scim/v2/{orgId}/ResourceTypes` | Retrieve all supported resource types |
|
|
| `GET /scim/v2/{orgId}/ResourceTypes/{name}` | Retrieve a known supported resource type |
|
|
| `GET /scim/v2/{orgId}/Users/{id}` | Retrieve a known user |
|
|
| `GET /scim/v2/{orgId}/Users`<br />`POST /scim/v2/{orgId}/Users/.search` | Query users (including filtering, sorting, paging) |
|
|
| `POST /scim/v2/{orgId}/Users` | Create a user |
|
|
| `PUT /scim/v2/{orgId}/Users/{id}` | Replace a user |
|
|
| `PATCH /scim/v2/{orgId}/Users/{id}` | Modify a user |
|
|
| `DELETE /scim/v2/{orgId}/Users/{id}` | Delete a user |
|
|
| `POST /scim/v2/{orgId}/Bulk` | Apply multiple operations in a single request |
|
|
|
|
## Authentication
|
|
|
|
The SCIM interface adheres to Zitadel's standard API authentication methods.
|
|
For detailed instructions on authenticating with the SCIM interface, refer to the [Authenticate Service Users Guide](/guides/integrate/service-users/authenticate-service-users).
|
|
|
|
## Query
|
|
|
|
The list users endpoint supports sorting and filtering for both `GET /scim/v2/{orgId}/Users` and `POST /scim/v2/{orgId}/Users/.search` requests.
|
|
By default, the response includes up to 100 users, with a maximum allowable value for `count` set to 100.
|
|
|
|
### Sort
|
|
|
|
The following attributes are supported in the `SortBy` attribute.
|
|
|
|
- `meta.created`
|
|
- `meta.lastModified`
|
|
- `id`
|
|
- `username`
|
|
- `name.familyName`
|
|
- `name.givenName`
|
|
- `emails` and `emails.value`
|
|
|
|
### Filter
|
|
|
|
The following filter attributes and operators are supported:
|
|
|
|
| Attribute | Supported operators |
|
|
|------------------------------|------------------------------|
|
|
| `meta.created` | `EQ`, `GT`, `GE`, `LT`, `LE` |
|
|
| `meta.lastModified` | `EQ`, `GT`, `GE`, `LT`, `LE` |
|
|
| `id` | `EQ`, `NE`, `CO`, `SW`, `EW` |
|
|
| `externalId` | `EQ`, `NE` |
|
|
| `username` | `EQ`, `NE`, `CO`, `SW`, `EW` |
|
|
| `name.familyName` | `EQ`, `NE`, `CO`, `SW`, `EW` |
|
|
| `name.givenName` | `EQ`, `NE`, `CO`, `SW`, `EW` |
|
|
| `emails`<br />`emails.value` | `EQ`, `NE`, `CO`, `SW`, `EW` |
|
|
| `active` | `EQ`, `NE` |
|
|
|
|
Filters can have a maximum length of 1000 characters.
|
|
|
|
## Examples
|
|
|
|
Here are practical examples demonstrating how to interact with the SCIM API,
|
|
providing clear guidance on common use cases such as creating a user.
|
|
Make sure to replace any placeholder values (`${}`) with the actual values from your environment.
|
|
|
|
<details>
|
|
<summary>`POST /Users`: Create a minimal user</summary>
|
|
|
|
```bash
|
|
curl -X POST "https://${DOMAIN}/scim/v2/${ORG_ID}/Users" \
|
|
-H 'Content-Type: application/scim+json' \
|
|
-H 'Accept: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
|
--data-raw '
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
|
|
"userName": "john.doe",
|
|
"name": {
|
|
"familyName": "Doe",
|
|
"givenName": "John"
|
|
},
|
|
"password": "Password1!",
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"primary": true
|
|
}
|
|
]
|
|
}
|
|
'
|
|
```
|
|
|
|
**Response (`201 Created`)**
|
|
```json
|
|
{
|
|
"schemas": [
|
|
"urn:ietf:params:scim:schemas:core:2.0:User"
|
|
],
|
|
"meta": {
|
|
"resourceType": "User",
|
|
"created": "2025-01-27T15:30:27.651321Z",
|
|
"lastModified": "2025-01-27T15:30:27.651321Z",
|
|
"version": "2",
|
|
"location": "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/304499468865155777"
|
|
},
|
|
"id": "304499468865155777",
|
|
"userName": "john.doe",
|
|
"name": {
|
|
"familyName": "Doe",
|
|
"givenName": "John"
|
|
},
|
|
"preferredLanguage": "en",
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"primary": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`POST /Users`: Create a full user</summary>
|
|
|
|
```bash
|
|
curl -X POST "https://${DOMAIN}/scim/v2/${ORG_ID}/Users" \
|
|
-H 'Content-Type: application/scim+json' \
|
|
-H 'Accept: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
|
--data-raw '
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
|
|
"externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
|
|
"userName": "[email protected]",
|
|
"name": {
|
|
"formatted": "Mr. John J Doe, III",
|
|
"familyName": "Doe",
|
|
"givenName": "John",
|
|
"middleName": "Jim",
|
|
"honorificPrefix": "Mr.",
|
|
"honorificSuffix": "III"
|
|
},
|
|
"displayName": "John Doe",
|
|
"nickName": "Johnny",
|
|
"profileUrl": "https://login.example.com/john.doe",
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"type": "work",
|
|
"primary": true
|
|
}
|
|
],
|
|
"addresses": [
|
|
{
|
|
"type": "work",
|
|
"streetAddress": "100 Universal City Plaza",
|
|
"locality": "Hollywood",
|
|
"region": "CA",
|
|
"postalCode": "91608",
|
|
"country": "USA",
|
|
"formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
|
|
"primary": true
|
|
}
|
|
],
|
|
"phoneNumbers": [
|
|
{
|
|
"value": "+1 555-555-5555",
|
|
"type": "work",
|
|
"primary": true
|
|
}
|
|
],
|
|
"ims": [
|
|
{
|
|
"value": "@j.doe",
|
|
"type": "X"
|
|
}
|
|
],
|
|
"photos": [
|
|
{
|
|
"value": "https://photos.example.com/profilephoto/john.doe/F",
|
|
"type": "photo"
|
|
}
|
|
],
|
|
"roles": [
|
|
{
|
|
"value": "user-admin",
|
|
"display": "User administrator"
|
|
}
|
|
],
|
|
"entitlements": [
|
|
{
|
|
"value": "read-passports",
|
|
"display": "Read Passports"
|
|
}
|
|
],
|
|
"userType": "Employee",
|
|
"title": "Tour Guide",
|
|
"preferredLanguage": "en-US",
|
|
"locale": "en-US",
|
|
"timezone": "America/Los_Angeles",
|
|
"active": true,
|
|
"password": "Password1!"
|
|
}'
|
|
```
|
|
|
|
**Response (`201 Created`)**
|
|
```json
|
|
{
|
|
"schemas": [
|
|
"urn:ietf:params:scim:schemas:core:2.0:User"
|
|
],
|
|
"meta": {
|
|
"resourceType": "User",
|
|
"created": "2025-01-27T15:31:47.84572Z",
|
|
"lastModified": "2025-01-27T15:31:47.84572Z",
|
|
"version": "16",
|
|
"location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
|
|
},
|
|
"id": "304499603368096449",
|
|
"externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
|
|
"userName": "[email protected]",
|
|
"name": {
|
|
"formatted": "John Doe",
|
|
"familyName": "Doe",
|
|
"givenName": "John",
|
|
"middleName": "Jim",
|
|
"honorificPrefix": "Mr.",
|
|
"honorificSuffix": "III"
|
|
},
|
|
"displayName": "John Doe",
|
|
"nickName": "Johnny",
|
|
"profileUrl": "https://login.example.com/john.doe",
|
|
"title": "Tour Guide",
|
|
"preferredLanguage": "en-US",
|
|
"locale": "en-US",
|
|
"timezone": "America/Los_Angeles",
|
|
"active": true,
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"primary": true
|
|
}
|
|
],
|
|
"phoneNumbers": [
|
|
{
|
|
"value": "+15555555555",
|
|
"primary": true
|
|
}
|
|
],
|
|
"ims": [
|
|
{
|
|
"value": "@j.doe",
|
|
"type": "X"
|
|
}
|
|
],
|
|
"addresses": [
|
|
{
|
|
"type": "work",
|
|
"streetAddress": "100 Universal City Plaza",
|
|
"locality": "Hollywood",
|
|
"region": "CA",
|
|
"postalCode": "91608",
|
|
"country": "USA",
|
|
"formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
|
|
"primary": true
|
|
}
|
|
],
|
|
"photos": [
|
|
{
|
|
"value": "https://photos.example.com/profilephoto/john.doe/F",
|
|
"type": "photo"
|
|
}
|
|
],
|
|
"entitlements": [
|
|
{
|
|
"value": "read-passports",
|
|
"display": "Read Passports"
|
|
}
|
|
],
|
|
"roles": [
|
|
{
|
|
"value": "user-admin",
|
|
"display": "User administrator"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`GET /Users/{id}`: Retrieve a known user</summary>
|
|
|
|
```bash
|
|
curl -G "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
|
|
-H 'Accept: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}"
|
|
```
|
|
|
|
**Response (`200 OK`)**
|
|
```json
|
|
{
|
|
"schemas": [
|
|
"urn:ietf:params:scim:schemas:core:2.0:User"
|
|
],
|
|
"meta": {
|
|
"resourceType": "User",
|
|
"created": "2025-01-27T15:31:47.84572Z",
|
|
"lastModified": "2025-01-27T15:31:47.84572Z",
|
|
"version": "16",
|
|
"location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
|
|
},
|
|
"id": "304499603368096449",
|
|
"externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
|
|
"userName": "[email protected]",
|
|
"name": {
|
|
"formatted": "John Doe",
|
|
"familyName": "Doe",
|
|
"givenName": "John",
|
|
"middleName": "Jim",
|
|
"honorificPrefix": "Mr.",
|
|
"honorificSuffix": "III"
|
|
},
|
|
"displayName": "John Doe",
|
|
"nickName": "Johnny",
|
|
"profileUrl": "https://login.example.com/john.doe",
|
|
"title": "Tour Guide",
|
|
"preferredLanguage": "en-US",
|
|
"locale": "en-US",
|
|
"timezone": "America/Los_Angeles",
|
|
"active": true,
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"primary": true
|
|
}
|
|
],
|
|
"phoneNumbers": [
|
|
{
|
|
"value": "+15555555555",
|
|
"primary": true
|
|
}
|
|
],
|
|
"ims": [
|
|
{
|
|
"value": "@j.doe",
|
|
"type": "X"
|
|
}
|
|
],
|
|
"addresses": [
|
|
{
|
|
"type": "work",
|
|
"streetAddress": "100 Universal City Plaza",
|
|
"locality": "Hollywood",
|
|
"region": "CA",
|
|
"postalCode": "91608",
|
|
"country": "USA",
|
|
"formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
|
|
"primary": true
|
|
}
|
|
],
|
|
"photos": [
|
|
{
|
|
"value": "https://photos.example.com/profilephoto/john.doe/F",
|
|
"type": "photo"
|
|
}
|
|
],
|
|
"entitlements": [
|
|
{
|
|
"value": "read-passports",
|
|
"display": "Read Passports"
|
|
}
|
|
],
|
|
"roles": [
|
|
{
|
|
"value": "user-admin",
|
|
"display": "User administrator"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`GET /Users`: List users created after a given date sorted by the creation date</summary>
|
|
|
|
```bash
|
|
curl -G "https://${DOMAIN}/scim/v2/${ORG_ID}/Users" \
|
|
-H 'Accept: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
|
--data-urlencode "sortBy=meta.created" \
|
|
--data-urlencode "sortOrder=descending" \
|
|
--data-urlencode "filter=meta.created gt \"2025-01-24T09:22:35.695245Z\""
|
|
```
|
|
|
|
**Response (`200 OK`)**
|
|
```json
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
|
|
"itemsPerPage": 100,
|
|
"totalResults": 1,
|
|
"startIndex": 1,
|
|
"Resources": [
|
|
{
|
|
"schemas": [
|
|
"urn:ietf:params:scim:schemas:core:2.0:User"
|
|
],
|
|
"meta": {
|
|
"resourceType": "User",
|
|
"created": "2025-01-27T15:31:47.84572Z",
|
|
"lastModified": "2025-01-27T15:31:47.84572Z",
|
|
"version": "3",
|
|
"location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
|
|
},
|
|
"id": "304499603368096449",
|
|
"externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
|
|
"userName": "[email protected]",
|
|
"name": {
|
|
"formatted": "John Doe",
|
|
"familyName": "Doe",
|
|
"givenName": "John",
|
|
"middleName": "Jim",
|
|
"honorificPrefix": "Mr.",
|
|
"honorificSuffix": "III"
|
|
},
|
|
"displayName": "John Doe",
|
|
"nickName": "Johnny",
|
|
"profileUrl": "https://login.example.com/john.doe",
|
|
"title": "Tour Guide",
|
|
"preferredLanguage": "und",
|
|
"locale": "en-US",
|
|
"timezone": "America/Los_Angeles",
|
|
"active": true,
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"primary": true
|
|
}
|
|
],
|
|
"phoneNumbers": [
|
|
{
|
|
"value": "+15555555555",
|
|
"primary": true
|
|
}
|
|
],
|
|
"ims": [
|
|
{
|
|
"value": "@j.doe",
|
|
"type": "X"
|
|
}
|
|
],
|
|
"addresses": [
|
|
{
|
|
"type": "work",
|
|
"streetAddress": "100 Universal City Plaza",
|
|
"locality": "Hollywood",
|
|
"region": "CA",
|
|
"postalCode": "91608",
|
|
"country": "USA",
|
|
"formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
|
|
"primary": true
|
|
}
|
|
],
|
|
"photos": [
|
|
{
|
|
"value": "https://photos.example.com/profilephoto/john.doe/F",
|
|
"type": "photo"
|
|
}
|
|
],
|
|
"entitlements": [
|
|
{
|
|
"value": "read-passports",
|
|
"display": "Read Passports"
|
|
}
|
|
],
|
|
"roles": [
|
|
{
|
|
"value": "user-admin",
|
|
"display": "User administrator"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`PATCH /Users/{id}`: Set a user inactive</summary>
|
|
|
|
```bash
|
|
curl -X PATCH "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
|
|
-H 'Content-Type: application/scim+json' \
|
|
-H 'Accept: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
|
--data-raw '
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
|
|
"Operations": [
|
|
{
|
|
"op": "replace",
|
|
"path": "active",
|
|
"value": false
|
|
}
|
|
]
|
|
}
|
|
'
|
|
```
|
|
|
|
**Response**: `204 No Content`
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`PATCH /Users/{id}`: Set the password of a user</summary>
|
|
|
|
```bash
|
|
curl -X PATCH "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
|
|
-H 'Content-Type: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
|
--data-raw '
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
|
|
"Operations": [
|
|
{
|
|
"op": "replace",
|
|
"path": "password",
|
|
"value": "Password2!"
|
|
}
|
|
]
|
|
}
|
|
'
|
|
```
|
|
|
|
**Response**: `204 No Content`
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`PUT /Users/{id}`: Replace a full user</summary>
|
|
|
|
```bash
|
|
curl -X PUT "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
|
|
-H 'Content-Type: application/scim+json' \
|
|
-H 'Accept: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
|
--data-raw '
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
|
|
"externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
|
|
"userName": "[email protected]",
|
|
"name": {
|
|
"formatted": "Mr. John J Doe, III",
|
|
"familyName": "Doe",
|
|
"givenName": "John",
|
|
"middleName": "Jim",
|
|
"honorificPrefix": "Mr.",
|
|
"honorificSuffix": "III"
|
|
},
|
|
"displayName": "John Doe",
|
|
"nickName": "Johnny",
|
|
"profileUrl": "https://login.example.com/john.doe",
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"type": "work",
|
|
"primary": true
|
|
}
|
|
],
|
|
"addresses": [
|
|
{
|
|
"type": "work",
|
|
"streetAddress": "100 Universal City Plaza",
|
|
"locality": "Hollywood",
|
|
"region": "CA",
|
|
"postalCode": "91608",
|
|
"country": "USA",
|
|
"formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
|
|
"primary": true
|
|
}
|
|
],
|
|
"phoneNumbers": [
|
|
{
|
|
"value": "+1 555-555-5555",
|
|
"type": "work",
|
|
"primary": true
|
|
}
|
|
],
|
|
"ims": [
|
|
{
|
|
"value": "@j.doe",
|
|
"type": "X"
|
|
}
|
|
],
|
|
"photos": [
|
|
{
|
|
"value": "https://photos.example.com/profilephoto/john.doe/F",
|
|
"type": "photo"
|
|
}
|
|
],
|
|
"roles": [
|
|
{
|
|
"value": "user-admin",
|
|
"display": "User administrator"
|
|
}
|
|
],
|
|
"entitlements": [
|
|
{
|
|
"value": "read-passports",
|
|
"display": "Read Passports"
|
|
}
|
|
],
|
|
"userType": "Employee",
|
|
"title": "Tour Guide",
|
|
"preferredLanguage": "en-US",
|
|
"locale": "en-US",
|
|
"timezone": "America/Los_Angeles",
|
|
"active": true,
|
|
"password": "Password1!"
|
|
}'
|
|
```
|
|
|
|
**Response (`200 OK`)**
|
|
```json
|
|
{
|
|
"schemas": [
|
|
"urn:ietf:params:scim:schemas:core:2.0:User"
|
|
],
|
|
"meta": {
|
|
"resourceType": "User",
|
|
"created": "2025-01-27T15:31:47.84572Z",
|
|
"lastModified": "2025-01-27T15:31:47.84572Z",
|
|
"version": "16",
|
|
"location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
|
|
},
|
|
"id": "304499603368096449",
|
|
"externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
|
|
"userName": "[email protected]",
|
|
"name": {
|
|
"formatted": "John Doe",
|
|
"familyName": "Doe",
|
|
"givenName": "John",
|
|
"middleName": "Jim",
|
|
"honorificPrefix": "Mr.",
|
|
"honorificSuffix": "III"
|
|
},
|
|
"displayName": "John Doe",
|
|
"nickName": "Johnny",
|
|
"profileUrl": "https://login.example.com/john.doe",
|
|
"title": "Tour Guide",
|
|
"preferredLanguage": "en-US",
|
|
"locale": "en-US",
|
|
"timezone": "America/Los_Angeles",
|
|
"active": true,
|
|
"emails": [
|
|
{
|
|
"value": "[email protected]",
|
|
"primary": true
|
|
}
|
|
],
|
|
"phoneNumbers": [
|
|
{
|
|
"value": "+15555555555",
|
|
"primary": true
|
|
}
|
|
],
|
|
"ims": [
|
|
{
|
|
"value": "@j.doe",
|
|
"type": "X"
|
|
}
|
|
],
|
|
"addresses": [
|
|
{
|
|
"type": "work",
|
|
"streetAddress": "100 Universal City Plaza",
|
|
"locality": "Hollywood",
|
|
"region": "CA",
|
|
"postalCode": "91608",
|
|
"country": "USA",
|
|
"formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
|
|
"primary": true
|
|
}
|
|
],
|
|
"photos": [
|
|
{
|
|
"value": "https://photos.example.com/profilephoto/john.doe/F",
|
|
"type": "photo"
|
|
}
|
|
],
|
|
"entitlements": [
|
|
{
|
|
"value": "read-passports",
|
|
"display": "Read Passports"
|
|
}
|
|
],
|
|
"roles": [
|
|
{
|
|
"value": "user-admin",
|
|
"display": "User administrator"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`DELETE /Users/{id}`: Delete a user</summary>
|
|
|
|
```bash
|
|
curl -X DELETE "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}"
|
|
```
|
|
|
|
**Response**: `204 No Content`
|
|
|
|
</details>
|
|
<details>
|
|
<summary>`POST /Bulk`: Update the password of one user and delete another one</summary>
|
|
|
|
```bash
|
|
curl -X POST "https://${DOMAIN}/scim/v2/${ORG_ID}/Bulk" \
|
|
-H 'Content-Type: application/scim+json' \
|
|
-H 'Accept: application/scim+json' \
|
|
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
|
--data-raw '
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
|
|
"Operations": [
|
|
{
|
|
"method": "PATCH",
|
|
"path": "/Users/${USER_ID}",
|
|
"data": {
|
|
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
|
|
"Operations": [
|
|
{
|
|
"op": "replace",
|
|
"path": "password",
|
|
"value": "Password2!"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"method": "DELETE",
|
|
"path": "/Users/${USER_ID2}"
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
**Response**: `200 OK`
|
|
|
|
```json
|
|
{
|
|
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
|
|
"Operations": [
|
|
{
|
|
"method": "PATCH",
|
|
"location": "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}",
|
|
"status": "204"
|
|
},
|
|
{
|
|
"method": "DELETE",
|
|
"location": "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID2}",
|
|
"status": "204"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>`GET /ServiceProviderConfig`: Get service provider configuration</summary>
|
|
|
|
```bash
|
|
curl -G "https://${DOMAIN}/scim/v2/${ORG_ID}/ServiceProviderConfig" \
|
|
-H 'Accept: application/scim+json'
|
|
```
|
|
|
|
**Response**: `200 OK`
|
|
|
|
```json
|
|
{
|
|
"schemas": [
|
|
"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
|
|
],
|
|
"meta": {
|
|
"resourceType": "ServiceProviderConfig",
|
|
"location": "https://${DOMAIN}/scim/v2/${ORG_ID}/ServiceProviderConfig"
|
|
},
|
|
"documentationUri": "https://zitadel.com/docs/guides/manage/user/scim2",
|
|
"patch": {
|
|
"supported": true
|
|
},
|
|
"bulk": {
|
|
"supported": true,
|
|
"maxOperations": 100,
|
|
"maxPayloadSize": 1000000
|
|
},
|
|
"filter": {
|
|
"supported": true,
|
|
"maxResults": 100
|
|
},
|
|
"changePassword": {
|
|
"supported": true
|
|
},
|
|
"sort": {
|
|
"supported": true
|
|
},
|
|
"etag": {
|
|
"supported": false
|
|
},
|
|
"authenticationSchemes": [
|
|
{
|
|
"name": "Zitadel authentication token",
|
|
"description": "Authentication scheme using the OAuth Bearer Token Standard",
|
|
"specUri": "https://www.rfc-editor.org/info/rfc6750",
|
|
"documentationUri": "https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users",
|
|
"type": "oauthbearertoken",
|
|
"primary": false
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
## Error handling
|
|
|
|
The SCIM interface uses standard HTTP status codes and error messages to indicate the success or failure of API requests
|
|
following the error handling guidelines of [RFC7644](https://datatracker.ietf.org/doc/html/rfc7644#section-3.12).
|
|
|
|
In addition to the default SCIM error schema (`urn:ietf:params:scim:api:messages:2.0:Error`),
|
|
Zitadel extends the error response with a custom schema, `urn:ietf:params:scim:api:zitadel:messages:2.0:ErrorDetail`.
|
|
This schema includes additional attributes, such as the untranslated error message and an error id,
|
|
which aids pinpointing the source of the error in the system.
|
|
|
|
## Resources
|
|
|
|
- **[Zitadel SCIM Documentation](/guides/manage/user/scim2)**: Documentation of Zitadel's SCIM implementation, including configuration details and known limitations.
|
|
- **[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).
|