archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge fa84732554 into d6edcbd946

Browse Source
Éloi Rivard 2 weeks ago committed by GitHub
parent d6edcbd946 fa84732554
commit 26009f9689
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 231 additions and 0 deletions
Show Stats Download Patch File Download Diff File

231
proposals/4098-provisioning-with-scim.md
Unescape Escape View File

@ -0,0 +1,231 @@
# 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.
## Provisioning
In short, *provisioning* is a way for different services to exchange information about users and groups.
Organizations often rely on IAM software to centralize information about their users.
IAM servers often implement protocols to communicate with services, such as OpenID Connect (OIDC) to provide unique
authentication with protocols like OpenID Connect (OIDC).
### Use cases
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 usage has limitations.
Several real-world Matrix use cases would benefit having a provisioning protocol implemented,
so IAM software and Matrix servers could communicate together and reduce friction for end users and system
administrators.
#### Centralized user creation
A new employee joins an organization.
The team the employee will join wants to prepare their collaboration tools,
so everything is set up for the employee's first day of work.
The team reaches the organization 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. Until then, the team cannot 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, when the employee account is created on the IAM server,
it reaches the different services to push the new employee profile. The team can share
anything they need before the new employee has ever logged in.
#### Centralized user update
An employee wishes to update their display name on their organization IAM server.
- Without a provisioning protocol, they will need to log-out and log-in again so the new display name is read from their
authentication token.
- With a provisioning protocol, the IAM server instantly communicate the new display name to every services.
#### Centralized user deletion
An employee leaves the organization, 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.
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
need to 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 removal once on
the IAM server.
### A provisioning protocol
To paraphrase [MSC1779](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/1779-open-governance.md),
*"interoperability is better than fragmentation*".
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.
#### A common protocol for the Matrix ecosystem
Without standard protocol, when an IAM software is connected to multiple services,
it implies that it implements a custom provisioning protocol for each one of those services,
multiplicating the maintenance burden and the room for bugs.
Having a common provisioning protocol defined in the Matrix specification would at least reduce the effort for making
IAM servers provisioning Matrix servers, since the protocol would need to be implemented once for all the Matrix
servers.
In addition, this would ensure some interoperability for other user management tools.
For instance, tools of the kind of [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) could be used
to manage users for any Matrix servers not plugged to an IAM server.
#### A standard protocol for the Matrix ecosystem
Adopting an existing standard provisioning protocol would allow IAM software to not implement dedicated connectors to be able to
manage Matrix server users. Possibly, provisioning would come for free in IAM software already implementing those
protocols.
In the end, that would reduce the friction for system administrators.
Plus, choosing a battle tested standard will save design time and avoid reinventing the wheel.
### The SCIM protocol
System for Cross-domain Identity Management, or SCIM, is a protocol that normalizes users and groups provisioning.
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.
The WG is alive and there are [several drafts currently being worked](https://datatracker.ietf.org/wg/scim/documents/).
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.
A lot of scenarios where SCIM is pertinent are available on [RFC7642](https://www.rfc-editor.org/rfc/rfc7642).
#### Real world SCIM 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/) ✅
## 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) |
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/`.
The stable prefix to use for the root SCIM endpoint is `/_scim/`.
[RFC7644 §3.13](https://www.rfc-editor.org/rfc/rfc7644#section-3.13) indicates that endpoint versioning is optional.
## 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.
Write Preview
Loading…
Cancel
Save