MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC #3861
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,125 @@ | ||
| # MSC3861: Matrix architecture change to delegate authentication via OIDC | ||
|
|
||
| This MSC proposes a change to the architecture of Matrix with respect to how authentication works. | ||
|
|
||
| ## Existing architecture | ||
|
|
||
| Currently Matrix uses a custom authentication protocol baked in to the Client-Server API. | ||
|
|
||
| In a overly simplified form it looks a bit like this: | ||
|
|
||
|  | ||
hughns marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| - Matrix Clients are required (and trusted) to show the UI for login and registration. | ||
| - Matrix Homeservers are responsible for authenticating users and issuing access tokens. | ||
|
|
||
| We've then added on things like: User-Interactive Auth which provides a standard for specifying an arbitrary sequence of steps including auth, T&C acceptance, CAPTCHA; password management; sessions management; and more. | ||
|
|
||
| The are issues with this current approach: | ||
|
|
||
| - 👎 Heavyweight for client and homeserver to implement and as a consequence many do not implement all capabilities | ||
| - e.g. Dendrite only does password auth | ||
| - 👎 Doesn't incorporate best security practices (particularly in case of SSO flow) | ||
| - 👎 Requires an MSC for every "new" auth capability such as 2FA and WebAuthn | ||
sandhose marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - 👎 We're training our users to enter their Matrix credentials in random web pages and native apps | ||
sandhose marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Matrix is not an authentication protocol | ||
|
|
||
| Quoting the [spec](https://spec.matrix.org/latest/#introduction-to-the-matrix-apis): | ||
|
|
||
| > Matrix is a set of open APIs for open-federated Instant Messaging (IM), Voice over IP (VoIP) and Internet of Things (IoT) communication, designed to create and support a new global real-time communication ecosystem. The intention is to provide an **open decentralised pubsub layer for the internet for securely persisting and publishing/subscribing JSON objects**. | ||
| So, fundamentally, Matrix does not set out to be a authentication protocol. | ||
|
|
||
| Yes, the ecosystem needs authentication to work, but it is not core to the mission. | ||
|
|
||
| ## Alternative architecture | ||
|
|
||
| The key concept of this proposal is the idea that the Matrix ecosystem would be better served by an architecture where authentication is decoupled from the Homeserver to some kind of authentication server. | ||
|
|
||
| That decoupling would be achieved by adopting an existing open authentication protocol rather than writing our own. | ||
|
|
||
| It would look something like this: | ||
|
|
||
|  | ||
|
|
||
| Some of the benefits of this are: | ||
|
|
||
| - 👍 Simpler for Homeservers and clients to implement | ||
sandhose marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - 👍 Benefits similar to SSO such as: | ||
| - logging into multiple clients on the same device without entering the credentials multiple times | ||
sandhose marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - having the credentials bound to the auth server domain instead of the client (for password managers and WebAuthn) | ||
sandhose marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - 👍 Benefit from larger existing community around a standard: | ||
| - Existing SDKs | ||
| - More battle testing and hardening | ||
| - 👍 Moves auth outside of the scope of Matrix spec | ||
| - ...allows the community to focus on what Matrix does best | ||
|
|
||
| It also allows the work of the Matrix community around auth to benefit other communities and users of the standard. | ||
|
|
||
| ## Adoption of OIDC as delegated protocol of choice | ||
|
|
||
| Specifically it is proposed that the OpenID Connect (OIDC) protocol is chosen to support the Matrix ecosystem. | ||
|
|
||
|  | ||
|
|
||
| There are five proposed action points: | ||
|
|
||
| 1. Accept the set of MSCs to enable delegation via OIDC. | ||
| 1. Deprecate non-OIDC auth related API endpoints or capabilities in existing Matrix APIs. | ||
| 1. Provide migration support to the ecosystem. | ||
| 1. Close all existing MSCs relating to non-OIDC as `obsolete`. | ||
|
There was a problem hiding this comment. Please make sure to check if those are actually solved by this when doing it. There might be some around that OIDC does not fix but actually complicates, like the Concealed login MSC. There was a problem hiding this comment. That is a good point. We should spend some time identifying those MSCs sooner than later, and see for each MSC if either:
There was a problem hiding this comment. Since now half a year went by: is there any update on which mscs are compatible and which aren't? There was a problem hiding this comment. |
||
| 1. Remove the deprecated API endpoints/capabilities from the spec at an appropriate point in future. | ||
|
|
||
| Due to the complexity of this proposal it has been broken down into a number of constituent sub-proposals: | ||
|
|
||
|
|
||
| | Ref | Purpose | | ||
| | - | - | | ||
| | [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) | Describes how homeservers can delegate auth to an OIDC Provider | | ||
| | [MSC2965](https://github.com/matrix-org/matrix-doc/pull/2965) | Describes how participants in the Matrix ecosystem can discover the available capabilities of OIDC-enabled Homeservers and OIDC Providers | | ||
| | [MSC2966](https://github.com/matrix-org/matrix-doc/pull/2966) | Describes how OAuth 2.0 Dynamic Client Registration can be used to facilitate interoperability and openness of clients whilst promoting trust | | ||
| | [MSC2967](https://github.com/matrix-org/matrix-doc/pull/2967) | Defines the namespace for a set of API scopes that can can expanded in future to allow for finer grained permissioning | | ||
| | [MSC3824](https://github.com/matrix-org/matrix-doc/pull/3824) | Proposes some minor changes to the C-S API to allow Matrix clients that are not fully OIDC-native to work best with an OIDC enabled homeserver that has is serving a compatibility layer | | ||
|
|
||
| ## Potential issues | ||
|
There was a problem hiding this comment. From reviewing the Synapse implementation it seems that this MSC is missing information on how application services would register users. matrix-org/synapse#15582 keeps the old This MSC needs to include some information IMO about how this interacts with application services. |
||
|
|
||
| This proposal requires changes to all Clients, Homeservers, Bridges etc. This will take some time. | ||
|
|
||
| Furthermore, during a migration period it will be necessary to support both existing "legacy" auth as well as OIDC. | ||
|
|
||
| For existing Homeserver deployments we will need to work out migration paths and provide tools to facilitate the transition. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| The primary alternative is to continue to build out the auth capabilities within the Client Server API. | ||
|
|
||
| Examples of existing proposals include: | ||
|
|
||
|
|
||
| | Proposals | Comments | | ||
| | - | - | | ||
| | [MSC1998: Two-Factor Authentication Providers](https://github.com/matrix-org/matrix-spec-proposals/pull/1998)<br>[MSC2271: TOTP 2FA login](https://github.com/matrix-org/matrix-spec-proposals/pull/2271) | OP is free to implement MFA and many do. The [Matrix OIDC Playground](https://github.com/vector-im/oidc-playground) contains a Keycloak configured to demonstrate this | | ||
| | [MSC2000: Server-side password policies](https://github.com/matrix-org/matrix-spec-proposals/pull/2000) | Because the UI is served by the OP it is free to implement whatever password policies it sees fit | | ||
| | [MSC3105: Previewing UIA flows](https://github.com/matrix-org/matrix-spec-proposals/pull/3105)<br>[MSC3741: Revealing the useful login flows to clients after a soft logout](https://github.com/matrix-org/matrix-spec-proposals/pull/3741) | These become unnecessary as the burdon to implement auth flows is moved away from the client to the OP | | ||
hughns marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | [MSC3262: aPAKE authentication](https://github.com/matrix-org/matrix-spec-proposals/pull/3262)<br>[MSC2957: Cryptographically Concealed Credentials](https://github.com/matrix-org/matrix-spec-proposals/pull/2957) | This is an interesting one as OIDC explicitly discourages a user from trusting their client with credentials. As such there is no existing flow for PAKEs. To achieve this in OIDC you would need to implement a custom grant in the Client and OP (perhaps an extension of the Resource Owner Password Credentials flow).| | ||
sandhose marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | [MSC3782: Matrix public key login spec](https://github.com/matrix-org/matrix-spec-proposals/pull/3782) | Similar to above | | ||
| | [MSC3744: Support for flexible authentication](https://github.com/matrix-org/matrix-spec-proposals/pull/3744) | OIDC would instead be used as the pluggable layer for auth in Matrix| | ||
|
|
||
| ## Security considerations | ||
|
|
||
| Please refer to individual proposals. | ||
|
There was a problem hiding this comment. I am not sure if there is a better place, but: How do we protect from ending up in the same situation as email, where big companies (like google/microsoft) end up using OIDC/OAuth2 purely to gatekeep the clients that are allowed to use? As far as I understand, matrix is supposed to be an open protocol where anyone is allowed to bring their own tools and software. So how do we make sure that this is still possible? I am aware of certain enterprise parts of matrix that want to restrict client usage, however imho this isn't something that should leak into spec. The reasoning behind is that the Matrix Manifesto ( https://matrix.org/foundation/ ) clearly defines that we do want to be an open communication network and people shall have full control over their communication. If we end up however in a situation where we give HS admins a (too) easy way to restrict the clients that are usable we would break the goals of that manifesto at it's core, since then it's not open anymore for the users and Singular community managers can decide what tools to use with 0 protection for the users. (edit: typos) There was a problem hiding this comment. For additional source of my email reference, see the comment made by a thunderbird dev in https://wiki.mozilla.org/Thunderbird:Autoconfiguration:ConfigFileFormat#OAuth2
I am aware of the dynamic registration MSC for OIDC, but that only somewhat solves this, since there a provider still is able to refuse your client at any given time without explanation. There was a problem hiding this comment. I'm not sure how to properly address this to be honest. MSC2966 outlines what the client must advertise, and what the homeserver should accept. If the HS doesn't accept a valid registration, I would argue that this HS is no longer Matrix-compliant on the C-S API side? This was always a possibility in the ecosystem: nothing prevented a homeserver to have an allow-list of valid redirect URLs for the m.login.sso flow. Note that the notes from Thunderbird are completely valid for email, but not for Matrix, as this 'many client, many homeservers' constraint means we have to have some sort of open client registration. Mastodon has something similar, Bluesky/ATProto as well… I'm not sure why it would not work for Matrix |
||
|
|
||
| ## Unstable prefix | ||
|
|
||
| Please refer to individual proposals. | ||
|
|
||
| ## Dependencies | ||
|
|
||
| The following MSCs are part of this proposal: | ||
|
|
||
| - [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) | ||
| - [MSC2965](https://github.com/matrix-org/matrix-doc/pull/2965) | ||
| - [MSC2966](https://github.com/matrix-org/matrix-doc/pull/2966) | ||
| - [MSC2967](https://github.com/matrix-org/matrix-doc/pull/2967) | ||
| - [MSC3824](https://github.com/matrix-org/matrix-doc/pull/3824) | ||
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.
I might be unable to find the right line in this huge amount of MSCs, but how does this new system translate users to mxids for events There needs to be some mapping right?
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.
I'm not sure I understand what you mean here. This proposal doesn't touch on events, and MXIDs are not really a concern throughout the flow. Could you clarify what you're asking here?