Proposal to use the SCIM protocol for provisioning

Signed-off-by: Éloi Rivard <eloi@yaal.coop>

proposals/4098-provisioning-with-scim.md

@@ -0,0 +1,196 @@
+# MSC4098: User account provisioning using SCIM
+
+This proposal suggests to use the SCIM protocol as a standard way to achieve
+user account [provisioning](https://en.wikipedia.org/wiki/Account_provisioning), fix several use cases uncovered
+by the specification, and in the end help reduce friction for system administrators managing Matrix servers.
+
+## Proposal
+
+System for Cross-domain Identity Management, or SCIM, is a protocol that normalizes users and groups provisioning.
+In short, *provisioning* is a way for different services to exchange information about users and groups.
+The [SCIM IETF working group](https://datatracker.ietf.org/wg/scim/about/) wrote
+[RFC7642](https://www.rfc-editor.org/rfc/rfc7642), [RFC7643](https://www.rfc-editor.org/rfc/rfc7643) and
+[RFC7644](https://www.rfc-editor.org/rfc/rfc7644) which details the protocol.
+
+A SCIM implementation basically consists in a set of HTTP endpoints used to read or edit objects such as *Users* and
+*Groups*, plus a few metadata endpoints. The different standard HTTP methods (GET, POST, PUT, PATCH, DELETE) are used
+depending on the intended actions on the objects.
+
+SCIM is to *provisioning* what OpenID Connect (OIDC) is to *authentication*, and is generally implemented in Identity
+and Authorization Management (IAM) software.
+
+### Use cases
+
+Using SCIM as a provisioning protocol would help with some use cases.
+A lot of scenarios where SCIM is pertinent are available on [RFC7642](https://www.rfc-editor.org/rfc/rfc7642).
+
+Organizations often rely on IAM software to centralize information about their users. This
+allows for unique authentication with protocols like OIDC. A common practice is to dynamically
+create users on services when they first log-in with OIDC, based on the data provided by the [authentication
+tokens](https://tools.ietf.org/html/rfc9068) or a dedicated [endpoint at the
+IAM](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). However this does not fit all use cases.
+For instance, a new employee joins a company. The team with which the employee will work wants to prepare
+their collaboration tools, so everything is set up for the employee's first day of work. The team
+reaches the company system administrators who create a user profile in the IAM software.
+- Without a provisioning protocol, the new employee's profile will only be created on the collaboration tools at the
+employee first log-in, preventing the team to share files, send welcome emails etc. or in case of a Matrix server,
+invite them in a discussion or a space. This is unless system administrators manually perform the user creation on
+all the services.
+- With a provisioning protocol,
+the IAM can reach the different services to push the new employee profile, so their team can share
+anything they need before the new employee has ever logged in.
+
+Similarly, when an employee leaves the company, the system administrators will remove or de-activate
+the user profile from the IAM, that will immediately prevent the leaving employee to log-in at any service.
+However the employee may still have data left on all those services (such as files, emails, personal
+profile information etc.), that sooner or later will be needed
+to remove, either because of disk usage or privacy reasons.
+- Without a provisioning protocol, the system administrators
+needs manually perform the account removal operation on all the services the employee have been using. This can
+be cumbersome depending on the quantity of users and services.
+- With a provisioning protocol, the modifications on the user profile
+are automacally repercuted on all the services, so the system administrators only need to do the once on
+the IAM.
+
+As an illustration, synapse implements its own provisioning protocol with its
+[Users admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html).
+While this is useful from the point of view of the synapse ecosystem, this has limitations from an IAM - or system
+administrator - perspective.
+Indeed, in cases an IAM software is connected to a multiple services,
+it implies that it implements the custom provisioning protocol for each one of those services, multiplicating the
+maintenance burden and the room for bugs.
+
+To paraphrase
+[MSC1779](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/1779-open-governance.md),
+*"interoperability is better than fragmentation*". This is why this proposal advises to use SCIM as
+a standard provisioning protocol for Matrix.
+
+From a larger perspective, the SCIM implementation would help Matrix integration in software suites, by reducing the
+friction for system administrators.
+
+### Real world implementations
+
+While being almost 10 years old, SCIM suffers from not being very popular yet (at least, not as much as protocols like
+OIDC).
+It is facing a chicken and egg issue, where services are waiting for IAMs to implement SCIM before they find useful to
+implement it in return, and vice-versa. However, SCIM seems to gain in popularity lately.
+Here is a quick state of the art of the current SCIM implementations in famous IAMs.
+
+- [Auth0](https://auth0.com/docs/authenticate/protocols/scim) ✅
+- Authelia ❌
+- [Authentik](https://goauthentik.io/docs/providers/scim/) ✅
+- [Authentic2](https://dev.entrouvert.org/issues/70751) ❌
+- [Canaille](https://canaille.readthedocs.io/en/latest/specifications.html#scim) ❌
+- [CAS](https://apereo.github.io/cas/7.0.x/integration/SCIM-Provisioning.html) ✅
+- Connect2id ❌
+- [Gluu](https://gluu.org/docs/gluu-server/4.0/api-guide/scim-api/) ✅
+- [Hydra](https://github.com/ory/hydra/issues/235) ❌
+- Keycloak, via plugins [scim-for-keycloak](https://scim-for-keycloak.de/)
+  or [keycloak-scim](https://lab.libreho.st/libre.sh/scim/keycloak-scim) ✅
+- LemonLDAP ❌
+- [Okta](https://developer.okta.com/docs/reference/scim/scim-20/) ✅
+
+### Detailed implementation proposal
+
+#### Endpoints
+
+[RFC7644](https://www.rfc-editor.org/rfc/rfc7644) defines different endpoints.
+This proposal is to implement the following endpoints:
+
+- [User](https://www.rfc-editor.org/rfc/rfc7643#section-4.1) endpoint, which are used to manage users.
+  - creation with [POST](https://www.rfc-editor.org/rfc/rfc7644#section-3.3)
+  - retrieval with [GET](https://www.rfc-editor.org/rfc/rfc7644#section-3.4)
+  - replacement with [PUT](https://www.rfc-editor.org/rfc/rfc7644#section-3.5.1)
+  - deletion with [DELETE](https://www.rfc-editor.org/rfc/rfc7644#section-3.6)
+- [Service Provider Configuration endpoints](https://www.rfc-editor.org/rfc/rfc7644#section-4), which display metadata
+  about the SCIM implementation.
+  - `/ServiceProviderConfig`
+  - `/Schemas`
+  - `/ResourceTypes`
+
+Other endpoints such as [Bulk operations](https://www.rfc-editor.org/rfc/rfc7644#section-3.7)
+or [Search](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.3), or methods like
+[PATCH](https://www.rfc-editor.org/rfc/rfc7644#section-3.5.2), are considered optional.
+
+#### User attributes matching
+
+The SCIM User attributes are detailed on [RFC7643](https://www.rfc-editor.org/rfc/rfc7643#section-4.1).
+Some attributes easily fits between the SCIM and the Matrix specifications:
+
+| SCIM         | Matrix        |
+| ------------ | ------------- |
+| userName     | username      |
+| password     | [password](https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3accountpassword) |
+| emails       | 3pid email    |
+| phoneNumbers | 3pid msisdn   |
+| displayName  | display name  |
+| photos       | avatar_url    |
+| active       | [deactivate](https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3accountdeactivate) |
+
+*Note that the Matrix attributes edition availability should reflect
+[Change password](https://spec.matrix.org/v1.9/client-server-api/#mchange_password-capability),
+[Set displayname](https://spec.matrix.org/v1.9/client-server-api/#mset_displayname-capability)
+and [Set avatar](https://spec.matrix.org/v1.9/client-server-api/#mset_avatar_url-capability) capabilities.*
+
+The [Matrix specification on profiles](https://spec.matrix.org/latest/#profiles) indicates that
+*Users may publish arbitrary key/value data associated with their account*, and on its own side, SCIM is very feature
+complete and leaves room for additional attributes with its [extension
+model](https://www.rfc-editor.org/rfc/rfc7643#section-3.3).
+
+In the end, the exact attribute matching implementation should be left to the Matrix server, in a similar fashion
+than synapse achieves [mapping from attributes from SSO
+providers](https://matrix-org.github.io/synapse/latest/sso_mapping_providers.html).
+
+#### Authentication
+
+The SCIM protocol [supports all the common HTTP authentication
+methods](https://www.rfc-editor.org/rfc/rfc7644#section-2), so the provisioning endpoints should use the same user
+[authentication methods](https://spec.matrix.org/v1.9/client-server-api/#client-authentication) than the rest of the
+Matrix server.
+
+As indicated in the [Server Administration](https://spec.matrix.org/v1.9/client-server-api/#server-administration)
+paragraph, *Server-local administrator privileges are not specified in this document.* It could rely on a
+local *administrator flags*, or a SCIM [entitlements](https://www.rfc-editor.org/rfc/rfc7643#section-4.1) attribute
+values for instance.
+
+## Potential issues
+
+The scope of the SCIM User model and the Matrix User model might not perfectly match, however the SCIM [extension
+model](https://www.rfc-editor.org/rfc/rfc7643#section-3.3) can be used in the future to standardize more attributes of
+the User model in the Matrix specification.
+
+## Alternatives
+
+SCIM appears to be the only existing relevant user account provisioning protocol.
+
+An alternative could be for Matrix to define its own provisioning protocol. This would bring standardization between
+Matrix servers, but would not be as useful for IAMs attached to a large number of services, since they would still need
+to implement the Matrix provisioning protocol.
+
+## Security considerations
+
+SCIM security considerations are related in [a dedicated paragraph](https://www.rfc-editor.org/rfc/rfc7644#section-7) in
+RFC7644.
+
+## Unstable prefix
+
+The unstable prefix to use for the root SCIM endpoint is `/_matrix/client/unstable/coop.yaal/scim/`.
+
+## Dependencies
+
+This MSC has no dependency.
+
+It would solve [matrix-spec#23](https://github.com/matrix-org/matrix-spec/issues/23) and
+[matrix-spec#228](https://github.com/matrix-org/matrix-spec/issues/228).
+
+This MSC would play along well with
+[MSC3861](https://github.com/matrix-org/matrix-spec-proposals/blob/hughns/delegated-oidc-architecture/proposals/3861-delegated-oidc-architecture.md)
+by delegating another aspect of user management to a standard protocol. It might call for a SCIM implementation in
+[matrix-authentication-service](https://github.com/matrix-org/matrix-authentication-service).
+
+## Notes
+
+[Indiehosters](https://indiehosters.net/) has [obtained a
+grant](https://forum.indiehosters.net/t/candidature-ngi-nlnet-privacy-trust-enhancing-technologies/4715) from the
+[NLNet foundation](https://nlnet.nl/) for the realisation of several things around SCIM. My employer
+[Yaal Coop](https://yaal.coop/) has been hired to work on the possible Matrix specification and synapse implementation.