SCIM provisioning API basic implementation #17144
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| Implement a SCIM provisioning API. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,284 @@ | ||
| # SCIM API | ||
|
|
||
| Synapse implements a basic subset of the SCIM 2.0 provisioning protocol as defined in [RFC7643](https://datatracker.ietf.org/doc/html/rfc7643) and [RFC7644](https://datatracker.ietf.org/doc/html/rfc7643). | ||
| This allows Identity Provider software to update user attributes in a standard and centralized way. | ||
|
|
||
| The SCIM endpoint is `/_synapse/admin/scim/v2`. | ||
|
|
||
| <div class="warning"> | ||
|
|
||
| The synapse SCIM API is an experimental feature, and it is disabled by default. | ||
| It might be removed someday in favor of an implementation in the [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service). | ||
|
|
||
| </div> | ||
|
|
||
| ## Installation | ||
|
|
||
| SCIM support for Synapse requires python 3.9+. The `matrix-synapse` package should be installed with the `scim` extra. e.g. with `pip install matrix-synapse[scim]`. For compatibility reasons, the SCIM support cannot be included in the `all` extra, so you need to explicitly use the `scim` extra to enable the API. | ||
|
|
||
| Then it must be explicitly enabled by configuration: | ||
|
|
||
| ```yaml | ||
| experimental_features: | ||
| msc4098: | ||
|
There was a problem hiding this comment. if this is no longer tracking an MSC, let's rename this feature to just I understand what MatMaul is saying but I would still prefer it in an experimental feature that is disabled by default. |
||
| enabled: true | ||
| idp_id: <my-provider> | ||
| ``` | ||
|
|
||
| ## Examples | ||
|
|
||
| This sections presents examples of SCIM requests and responses that are supported by the synapse implementation. | ||
| Tools like [scim2-cli](https://scim2-cli.readthedocs.io) can be used to manually build payloads and send requests to the SCIM endpoint. | ||
|
|
||
| ### Create user | ||
|
|
||
| #### Request | ||
|
|
||
| ``` | ||
| POST /_synapse/admin/scim/v2/Users | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], | ||
| "userName": "bjensen", | ||
| "externalId": "bjensen@test", | ||
| "phoneNumbers": [{"value": "+1-12345678"}], | ||
| "emails": [{"value": "[email protected]"}], | ||
| "photos": [ | ||
| { | ||
| "type": "photo", | ||
| "primary": true, | ||
| "value": "https://mydomain.tld/photo.webp" | ||
| } | ||
| ], | ||
| "displayName": "bjensen display name", | ||
| "password": "correct horse battery staple" | ||
| } | ||
| ``` | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| { | ||
| "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], | ||
| "meta": { | ||
| "resourceType": "User", | ||
| "created": "2024-07-22T16:59:16.326188+00:00", | ||
| "lastModified": "2024-07-22T16:59:16.326188+00:00", | ||
| "location": "https://synapse.example/_synapse/admin/scim/v2/Users/@bjensen:test", | ||
| }, | ||
| "id": "@bjensen:test", | ||
| "externalId": "@bjensen:test", | ||
| "phoneNumbers": [{"value": "+1-12345678"}], | ||
| "userName": "bjensen", | ||
| "emails": [{"value": "[email protected]"}], | ||
| "active": true, | ||
| "photos": [ | ||
| { | ||
| "type": "photo", | ||
| "primary": true, | ||
| "value": "https://mydomain.tld/photo.webp" | ||
| } | ||
| ], | ||
| "displayName": "bjensen display name" | ||
| } | ||
| ``` | ||
|
|
||
| ### Get user | ||
|
|
||
| #### Request | ||
|
|
||
| ``` | ||
| GET /_synapse/admin/scim/v2/Users/@bjensen:test | ||
| ``` | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| { | ||
| "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], | ||
| "meta": { | ||
| "resourceType": "User", | ||
| "created": "2024-07-22T16:59:16.326188+00:00", | ||
| "lastModified": "2024-07-22T16:59:16.326188+00:00", | ||
| "location": "https://synapse.example/_synapse/admin/scim/v2/Users/@bjensen:test", | ||
| }, | ||
| "id": "@bjensen:test", | ||
| "externalId": "@bjensen:test", | ||
| "phoneNumbers": [{"value": "+1-12345678"}], | ||
| "userName": "bjensen", | ||
| "emails": [{"value": "[email protected]"}], | ||
| "active": true, | ||
| "photos": [ | ||
| { | ||
| "type": "photo", | ||
| "primary": true, | ||
| "value": "https://mydomain.tld/photo.webp" | ||
| } | ||
| ], | ||
| "displayName": "bjensen display name" | ||
| } | ||
| ``` | ||
|
|
||
| ### Get users | ||
|
|
||
| #### Request | ||
|
|
||
| Note that requests can be paginated using the `startIndex` and the `count` query string parameters: | ||
|
|
||
| ``` | ||
| GET /_synapse/admin/scim/v2/Users?startIndex=10&count=1 | ||
| ``` | ||
|
|
||
| <div class="warning"> | ||
|
|
||
| For performances reason, the page count will be maxed to 1000. | ||
|
|
||
| </div> | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| { | ||
| "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], | ||
| "totalResults": 123, | ||
| "Resources": [ | ||
| { | ||
| "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], | ||
| "meta": { | ||
| "resourceType": "User", | ||
| "created": "2024-07-22T16:59:16.326188+00:00", | ||
| "lastModified": "2024-07-22T16:59:16.326188+00:00", | ||
| "location": "https://synapse.example/_synapse/admin/scim/v2/Users/@bjensen:test", | ||
| }, | ||
| "id": "@bjensen:test", | ||
| "externalId": "@bjensen:test", | ||
| "phoneNumbers": [{"value": "+1-12345678"}], | ||
| "userName": "bjensen", | ||
| "emails": [{"value": "[email protected]"}], | ||
| "active": true, | ||
| "photos": [ | ||
| { | ||
| "type": "photo", | ||
| "primary": true, | ||
| "value": "https://mydomain.tld/photo.webp" | ||
| } | ||
| ], | ||
| "displayName": "bjensen display name" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ### Replace user | ||
|
|
||
| #### Request | ||
|
|
||
| ``` | ||
| PUT /_synapse/admin/scim/v2/Users/@bjensen:test | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], | ||
| "userName": "bjensen", | ||
| "externalId": "bjensen@test", | ||
| "phoneNumbers": [{"value": "+1-12345678"}], | ||
| "emails": [{"value": "[email protected]"}], | ||
| "active": true, | ||
| "photos": [ | ||
| { | ||
| "type": "photo", | ||
| "primary": true, | ||
| "value": "https://mydomain.tld/photo.webp" | ||
| } | ||
| ], | ||
| "displayName": "bjensen new display name", | ||
| "password": "correct horse battery staple" | ||
| } | ||
| ``` | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| { | ||
| "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], | ||
| "meta": { | ||
| "resourceType": "User", | ||
| "created": "2024-07-22T16:59:16.326188+00:00", | ||
| "lastModified": "2024-07-22T17:34:12.834684+00:00", | ||
| "location": "https://synapse.example/_synapse/admin/scim/v2/Users/@bjensen:test", | ||
| }, | ||
| "id": "@bjensen:test", | ||
| "externalId": "@bjensen:test", | ||
| "phoneNumbers": [{"value": "+1-12345678"}], | ||
| "userName": "bjensen", | ||
| "emails": [{"value": "[email protected]"}], | ||
| "active": true, | ||
| "photos": [ | ||
| { | ||
| "type": "photo", | ||
| "primary": true, | ||
| "value": "https://mydomain.tld/photo.webp" | ||
| } | ||
| ], | ||
| "displayName": "bjensen new display name" | ||
| } | ||
| ``` | ||
|
|
||
| ### Delete user | ||
|
|
||
| User deletion requests [deactivate](../../../admin_api/user_admin_api.md) users, with the `erase` option. | ||
|
|
||
| #### Request | ||
|
|
||
| ``` | ||
| DELETE /_synapse/admin/scim/v2/Users/@bjensen:test | ||
| ``` | ||
|
|
||
|
There was a problem hiding this comment. maybe worth noting that deleting a user triggers the deactivation of that user, including the erase option There was a problem hiding this comment. I don't think this was noted on the documentation? |
||
| ## Implementation details | ||
|
|
||
| ### Models | ||
|
|
||
| The only SCIM resource type implemented is `User`, with the following attributes: | ||
| - `userName` | ||
| - `password` | ||
| - `emails` | ||
| - `phoneNumbers` | ||
| - `displayName` | ||
| - `photos` (as a MXC URI) | ||
| - `active` | ||
|
|
||
| The other SCIM User attributes will be ignored. Other resource types such as `Group` are not implemented. | ||
|
|
||
| ### Endpoints | ||
|
|
||
| The implemented endpoints are: | ||
|
|
||
| - `/Users` (GET, POST) | ||
| - `/Users/<user_id>` (GET, PUT, DELETE) | ||
| - `/ServiceProviderConfig` (GET) | ||
| - `/Schemas` (GET) | ||
| - `/Schemas/<schema_id>` (GET) | ||
| - `/ResourceTypes` (GET) | ||
| - `/ResourceTypes/<resource_type_id>` | ||
|
|
||
| The following endpoints are not implemented: | ||
|
|
||
| - `/Users` (PATCH) | ||
| - [`/Me`](https://datatracker.ietf.org/doc/html/rfc7644#section-3.11) (GET, POST, PUT, PATCH, DELETE) | ||
| - `/Groups` (GET, POST, PUT, PATCH) | ||
| - [`/Bulk`](https://datatracker.ietf.org/doc/html/rfc7644#section-3.7) (POST) | ||
| - [`/.search`](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.3) (POST) | ||
|
|
||
| ### Features | ||
|
|
||
| The following features are implemented: | ||
| - [pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4) | ||
|
|
||
| The following features are not implemented: | ||
| - [filtering](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2) | ||
| - [sorting](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.3) | ||
| - [attributes selection](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.5) | ||
| - [ETags](https://datatracker.ietf.org/doc/html/rfc7644#section-3.14) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Given this functionality is in an unstable MSC, please can you:
experimental_featuresflag to the configuration for this feature. SCIM should only be enabled if it is turned onmsc3861_oauth_delegation_enabled), since in that scenario Synapse is not its own authority in charge of users?
We don't normally document experimental features however I am glad for the documentation this time. So, I'm happy to keep it, but it needs to be obvious to readers that it's experimental and not enabled by default.