feat: SCIM implementation

Implementation of a subset of SCIM endpoint and capabilities as described in MSC4098. Signed-off-by: Éloi Rivard <[email protected]>
element-hq · Aug 13, 2024 · f0aa456 · f0aa456
1 parent e1f5f0f
commit f0aa456
Show file tree

Hide file tree

Showing 9 changed files with 1,475 additions and 4 deletions.
diff --git a/changelog.d/17144.feature b/changelog.d/17144.feature
@@ -0,0 +1 @@
+Add support for MSC4098 (SCIM provisioning protocol).
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -70,6 +70,7 @@
       - [Users](admin_api/user_admin_api.md)
       - [Server Version](admin_api/version_api.md)
       - [Federation](usage/administration/admin_api/federation.md)
+      - [SCIM provisioning](usage/administration/admin_api/scim_api.md)
     - [Manhole](manhole.md)
     - [Monitoring](metrics-howto.md)
       - [Reporting Homeserver Usage Statistics](usage/administration/monitoring/reporting_homeserver_usage_statistics.md)

diff --git a/docs/usage/administration/admin_api/scim_api.md b/docs/usage/administration/admin_api/scim_api.md
@@ -0,0 +1,257 @@
+# SCIM API
+
+Synapse implement 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 `/_matrix/client/unstable/coop.yaal/scim`.
+
+## Installation
+
+SCIM support for Synapse requires python 3.9+. The `matrix-synapse` package should be installed with the `scim` extra.
+
+## Examples
+
+### Create user
+
+#### Request
+
+```
+POST /_matrix/client/unstable/coop.yaal/scim/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/_matrix/client/unstable/coop.yaal/scim/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 /_matrix/client/unstable/coop.yaal/scim/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/_matrix/client/unstable/coop.yaal/scim/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 /_matrix/client/unstable/coop.yaal/scim/Users?startIndex=10&count=1
+```
+
+#### 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/_matrix/client/unstable/coop.yaal/scim/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 /_matrix/client/unstable/coop.yaal/scim/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/_matrix/client/unstable/coop.yaal/scim/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
+
+#### Request
+
+```
+DELETE /_matrix/client/unstable/coop.yaal/scim/Users/@bjensen:test
+```
+
+## 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)