From 3105ab8e934298013df4944c33f3b85d9c94f1ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89loi=20Rivard?= Date: Mon, 5 Feb 2024 14:48:09 +0100 Subject: [PATCH] Proposal to use the SCIM protocol for provisioning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Éloi Rivard --- proposals/4098-provisioning-with-scim.md | 196 +++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 proposals/4098-provisioning-with-scim.md diff --git a/proposals/4098-provisioning-with-scim.md b/proposals/4098-provisioning-with-scim.md new file mode 100644 index 00000000000..c43bca2c7a9 --- /dev/null +++ b/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) server. 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 server 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 server, 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 server. + +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 server - 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 IAM servers 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 IAM servers. + +- [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 IAM servers 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.