MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC

[hughns]

Rendered

Dependencies/sub-proposals:

• MSC2964: Usage of OAuth 2.0 authorization code grant and refresh token grant #2964
• MSC2965: OIDC Provider discovery #2965
• MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix #2966
• MSC2967: API scopes #2967
• MSC3824: OIDC aware clients #3824
• MSC4108: Mechanism to allow OIDC sign in and E2EE set up via QR code #4108
• MSC4190: Device management for application services #4190
• MSC4191: Account management deep-linking #4191

[MTRNord]

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.

[sandhose]

That is a good point. We should spend some time identifying those MSCs sooner than later, and see for each MSC if either:

• it solves the problem solved by the MSC
• the tradeoffs are acceptable if it is conceptually orthogonal

[MTRNord]

Since now half a year went by: is there any update on which mscs are compatible and which aren't?

[hughns]

@MTRNord there is a start of a list at https://github.com/matrix-org/matrix-spec-proposals/blob/hughns/delegated-oidc-architecture/proposals/3861-delegated-oidc-architecture.md#alternatives

[turt2live]

just a mid-read review. Submitting before I forget about it

[MTRNord]

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)

[MTRNord]

For additional source of my email reference, see the comment made by a thunderbird dev in https://wiki.mozilla.org/Thunderbird:Autoconfiguration:ConfigFileFormat#OAuth2

Due to a defficiency in the OAuth2 spec, the client is usually required to send a client credential key, which in turn requires the client to be registered and approved by the email provider. Unfortunately, this not only allows email providers to block specific email clients (which is contrary to the idea of Open-Source), but also makes it impossible to support arbitrary OAuth2 servers. That's why Thunderbird is forced to hardcode the servers that it supports and the respecive client keys. That means that you cannot use OAuth2 for your own server. Only the servers listed on OAuth2Providers.jsm will work.

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.

[sandhose]

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.
What this proposal change, is that the homeserver has more metadata on the client than before to work with, which is a good thing for giving homeserver admins and users a better idea of what is happening with their account, who has access to it.

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

[turt2live]

I think it'd be fine to acknowledge the concern in the MSC, but I don't forsee a way to fix it. Homeservers can (and do) already gatekeep their registration and login APIs to particular clients/domains for a variety of reasons, including user safety and security - they might relax these conditions if given a proper authentication interface to use.

[hughns]

I've added references to the following MSCs that this proposal assumes are generally accepted:

• MSC3967: Do not require UIA when first uploading cross signing keys #3967
• MSC3970: Scope transaction IDs to devices #3970

[clokep]

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 /register endpoint active for the m.login.application_service login type only.

This MSC needs to include some information IMO about how this interacts with application services.

[XxSNiPxX]

Hello guys,

My current project requires me to authenticate a user on my synapse instance via a signed message from a keplr crypto wallet . I have a wallet signed message used as the password. How would i approach the authentication on matrix? Would i use another server that is openid compatible, whose license is often not gplv3 or would i use the architecture before by contacting the synapse instance directly? Can someone please share and end to end example of setting up a IAM server between the client and synapse?

Thanks

[Xiretza]

The first three of these points may be relevant for large, open-registration servers like matrix.org, but I'm gonna go out on a limb and say that most servers out there are not that. In general, there needs to be extremely solid justification for forcing this increase in complexity onto all the servers that have nothing or very little to gain from it.

[sandhose]

This section talks about one particular example, which is also the homeserver where a lot of users will first experience this flow.

I'm not sure I understand the second part of your comment, how is this section talking about increasing the complexity onto all servers?

[Xiretza]

I'm not sure I understand the second part of your comment, how is this section talking about increasing the complexity onto all servers?

It's not about that section, which is why I wrote "in general" - the rewritten MSC later mentions:

The long-term goal is to deprecate the existing UIA APIs and replace them with the new OAuth 2.0/OIDC-based APIs.

This means that in the long term, all homeserver operators have to set up an entire OAuth/OIDC infrastructure, which is significantly more complex than the built-in username+password auth that is entirely sufficient for what I claim to be the vast majority of homeservers out there. Or am I misunderstanding something?

[sandhose]

The change is relatively transparent for server operators, it is an API change, not an architecture change.

It happens that the current implementation with matrix-authentication-service and Synapse is a separate service, but the long term goal is to be integrated just within synapse, so the change will be fairly transparent for server operators

Does that answer your concern?

[Xiretza]

the long term goal is to be integrated just within synapse, so the change will be fairly transparent for server operators

Synapse operators. What about other homeservers?

Actually, putting on my homeserver developer hat, this really only shifts the problem from operators to developers. Right now, a homeserver implementation that can cover most usecases (i.e. except for the "large, open-registration" niche) using a very simple, almost stub-like UIA implementation. I admit I haven't actually looked into it properly yet, but I suspect that OIDC will make even a minimal implementation much more complex.

[sandhose]

I suggest reading the rest of the proposal, as this is not about imposing stuff like email verification, CAPTCHA support, etc. on homeservers.

A very lightweight implementation of this can be done only supporting simple login and password. At a very high level, the new API look like this:

• the client sends its metadata (name, redirect URL, etc.) to the homeserver, gets back a client identifier
• the client redirects the user to a web page hosted by the homeserver
• the homeserver does whatever it needs on that homepage to authenticate the user, this can be a very simple HTML form
• once completed, the homeserver redirect backs to the client with single-use code
• the client exchanges this code to get back an access token

How does that feel in terms of complexity? I understand that it is substantially higher than just sending 'username and password' to an API and get back an access token, but the bar doesn't seem too high for new implementation, especially considering there are plenty of OAuth/OIDC related libraries in many ecosystems to help implement some of this.

[Xiretza]

One use case I have somewhat frequently is setting up bots. Currently, you can just type in username+password, it does the authentication and stores the access token somewhere. With OIDC, I'd already be stuck at the first step: what is the "redirect URL" for a bot running on a headless server somewhere? Step 2, "redirecting" the user to a login page, is still possible by making them click on a link, but this is then opened on the user's machine, which is totally separate from the machine running the bot. There would need to be a third service somewhere that displays the single-use code, which then needs to be copy-pasted back into the bot. Not only is this more annoying to implement, it's also much more complicated to use.

So no, I'm not on board with removing username+password auth, but how about this as a long term plan:

• Strip down UIA to a bare minimum username+password (this removes most of the complexity there and still covers most use cases),
• Optionally let servers force the use of OIDC, which can then include all the captcha/email/whathaveyou bells and whistles for complex installations without having to cover these complexities in the Matrix spec.

[turt2live]

Homeservers which implement the minimum interface can also create exceptions for bots as needed. It's a common practice for API tokens to expire and need rotation, and it's equally common that service providers have a way to mint tokens independent of UI flows. Take for example GitHub, which supports OAuth2/OIDC for applications to log in as the user and a healthy ecosystem of integrations which run headless - the integrations get a dedicated API token, which may expire, and is created within an OIDC-authenticated client. Something similar would likely be possible for homeserver admins (and from discussions I've seen, very much in the plan for consideration when speaking towards removal of UIA from the spec - bots would be a blocker before we remove UIA).

It's also considered bad common practice to store passwords on bots for the purposes of authentication, and we already see bots which implement this behaviour poorly. For example, logging in every time they need to make a request. With a specific minted token, they aren't placing burden on their homeservers/federation, and have a higher default security profile. This does add some code to bots/clients though, but may be able to be packaged away into a library or their underlying Matrix SDK of choice. It'd be the specification's role to (if needed) define a standard way to perform that authentication so those Matrix SDKs can consistently implement it.

Overall, OIDC retains the ability for the homeserver admin to choose what authentication mechanisms they want to support, while also giving them even more options. Matrix is naturally slower at adding things like 2FA, Passkeys, API tokens, scoped tokens, etc and we're not experts in it - this MSC acknowledges this gap and suggests we adopt a protocol which specializes in this. Homeserver developers can choose to bundle in a full-blown OIDC server in their install if they like, or they could implement more usecase-specific APIs, or somewhere inbetween. Synapse appears to be going a route closer to a full-blown OIDC server, largely because of the wide variety of usecases they need to support.

[sandhose]

The long-awaited big rewrite is here!

I've been working on making this series of MSCs a lot better, and I think I addressed a lot of concerns made on it. I commented on most open threads how I believe they are now addressed and closed them. If you believe those concerns are still not addressed, please reopen them or open new threads on the new MSC text

Happy reading!

[sandhose]

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.
What this proposal change, is that the homeserver has more metadata on the client than before to work with, which is a good thing for giving homeserver admins and users a better idea of what is happening with their account, who has access to it.

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

[sandhose]

This section talks about one particular example, which is also the homeserver where a lot of users will first experience this flow.

I'm not sure I understand the second part of your comment, how is this section talking about increasing the complexity onto all servers?

[Tynach]

The long-awaited big rewrite is here!

Shouldn't a big rewrite be a separate pull request/proposal? That way it's easier to distinguish between discussion about the old one, and discussion about the new one?

Edit: Though, I suppose doing that would require updating links everywhere that link to this proposal, and it would have potentially been less discoverable. Wish I'd have thought of that a few minutes earlier than I did.

[marmarek]

This whole point (and earlier to some degree too) feels like it got the trust levels backwards. In the E2EE scenario it's the client that is the trusted part, and the homeserver is less trusted. After all, it's the client who sees clear text messages, it's the client who can impersonate the user etc. This proposal does not change (nor should change!) any of this. And thus, saying that credentials are now isolated from the client doesn't matter much from the trust perspective - it can still access/decrypt your messages etc.

I realize there is some logic in this reasoning if you consider web client only - in that scenario indeed having user authentication on a separate homeserver-controlled page can isolate the client a bit from (potentially compromised!) homeserver by moving that workflow to another domain. And in the web scenario, also attaching credentials to the homeserver domain makes sense. But in the E2EE scenario, the web client is inherently less secure option anyway - the web client provider can stealthy insert any backdoor into your client and steal all the keys. With this change it may not be able to steal your account credentials anymore (at least as long as the user actually verifies the login is performed on a correct domain - which live shows users are really bad at...), but that's only a little consolation at this point.

But if you care more about your communication security, a much better choice is a local client (be it desktop, mobile etc), where the client code cannot change without your knowledge. In this scenario, requiring full blown web browser to open a homeserver-controlled page is a significant regression in terms of security. Now, not only you have extra attack surface (web browser with all its APIs - the fact that usually login page would be simple doesn't mean a compromised homeserver couldn't serve a login page using all kind of APIs), you now need to expose your credentials to an external application (so, you need to trust not only your local client, but also your web browser). And it gets even worse with containerized applications (flatpak, snap etc), where you either may need a full browser inside the container (wasteful) or you need to share your credentials with something outside of that container. And finally, in the native client case, the extra isolation that OIDC supposedly provide does not apply, as the client (in practice) controls what browser is used for providing credentials - so, if you have a malicious client, it can also give you fake browser that will intercept the credentials anyway.

So, I think at the very least this section needs adjustment to explain the impact on the non-web clients. But also, I would recommend to not only acknowledge it, but also mitigate it in the MSC - for example by still providing (not only in transitional period) a login workflow that doesn't require visiting an arbitrary website from your client (or other device). From a practical standpoint, it's only about logging into an account (and maybe invalidation of other sessions?). All other stuff like registration, deletion etc. can be handled via web interface - there is indeed very little point in requiring all of that to have complex and flexible UI in every client out there.

[turt2live]

I'm not sure I'm following the trust model being backwards: in Matrix we always consider the client 'trusted' to decrypt/receive messages, but we also put things in place to limit that - the MSC doesn't read (to me) as conflicting with that. There's a note about not changing the E2EE model, which I think is here primarily to reduce confusion from the external audience.

What this MSC does change is the client's ability to make account-level changes on its own. UIA is something which can be driven almost entirely by code, and an infected client (either directly or indirectly) could trick the user into making their account inaccessible. For example, injecting code which says "please enter your password to confirm your account", which actually causes a password change in the background - for local clients, this could be injected by a virus on the user's machine, and for web clients it'd potentially be in the build pipeline. By having the authentication moved out of the client's implementation, users are significantly less likely to accidentally change their password without their knowledge.

Of course, the OIDC server could also be compromised and trick the user into changing their password, but the OIDC server will naturally have a higher sense of security given the threat vector.

[marmarek]

For web client this separation makes some sense. I don't fully agree with the practical security benefit, mostly because I don't believe users indeed not giving password if the client asks for it, just because it's on the client's domain not a separate OIDC domain. And while this is more of a human issue than technical issue, I don't think it should be dismissed - it doesn't really matter from the user point of view how their account got compromised...
But for native clients (which normally provide much stronger E2EE properties, due to not trusting some remote system serving the client code) the situation gets significantly worse. Before, you needed to trust your client integrity (including OS running it) to protect your credentials and encryption keys. With this change, you still need to trust your client for credentials and encryption keys, but you also need to trust some random code fetched from the internet (from the client point of view) and executed on your system to not only handle your account credentials correctly (1), but also to not try to escape browser sandbox and steal your encryption keys (2).
You can argue that (1) is not much of a change since that "random code" is provided by the same service that will receive credentials anyway, but depending on the OIDC server implementation that may not be really true (and indeed it's common to serve static files, including js, separately, sometimes via 3rd-party CDNs). But (2) is a significant attack surface increase for the non-web client case.

[turt2live]

I'm still struggling to follow the concern here, sorry. Using a web browser to "activate" a non-web browser client, even with a busted sandbox, should be no more risk than everyday use of the machine?

[marmarek]

Ah, I see the missing step. Sometimes yes, sometimes no. You may have your client and/or your browser running in additional sandbox / container like Flatpak/Snap/AppImage - in which case you either need to start that browser for login in the same container, or punch some holes in the sandboxes. I believe similar concern applies to Android (and maybe other mobile?) where the client will need to add WebView that runs a code fetched from the OIDC server, in the same sandbox as the client itself.
But you can go further - in Qubes OS it's trivial to have a VM with just your client running and no browser at all. And there is an API for opening links in a different VM (can be even a disposable one), where by design such browser cannot communicate back to the VM with your client (otherwise that extra separation would be useless...). In this scenario, this MSC reduces benefits from this separation, as you'll need to allow running a browser in the same VM, at least for the login time.

[turt2live]

I don't think the client needs to talk to the exact same web browser with OIDC to work. There are tons of headless and near-headless applications which poll the server to wait for credentials to appear, after authentication is done elsewhere. For example, logging in on your phone/TV might say "go to login.example.org to complete this login". A similar thing is achieved with the Vault command line if you have SSO set up: it'll poll the server until it gets credentials, having waited for the user to finish clicking buttons elsewhere.

Web clients, or clients in containers, can leverage this same step. The security model remains unchanged.

[marmarek]

Okay, if this indeed will be implemented this way, then it should be fine, thanks for clarification.

[turt2live]

Implementation is very much up to the server and client authors. At the protocol level, all we can do is make room for that to happen ;) (we are)

[olivia-fl]

An alternative that I think is worth discussing in the "alternatives" section is implementing OIDC while deprecating/removing all the existing auth types except m.login.password, m.login.dummy, and m.login.registration_token. The decision to remove m.login.password is very consequential, but the current text doesn't discuss the motivation, tradeoffs, or consequences of that decision.

(I want to be very explicit that I am talking about the decision to remove password auth, not the decision to implement OIDC or the decision to remove m.login.sso. I believe the latter two are well-covered by this MSC.)

If the intention is not to commit to remove existing UIA APIs here, then this sentence should possibly be removed or reworded.

[turt2live]

This MSC does not remove anything from the spec. The SCT expects that the existing UIA flows won't go anywhere anytime soon, and that servers will follow suit - the proposal to use OIDC is to facilitate transition away from UIA, not replace it day 1.

As the SCT, we'll block attempts to remove UIA too quickly from the spec (and therefore implementations).

[olivia-fl]

I guess the thing I want to understand is whether this MSC is a commitment to removing all existing UIA mechanisms at some point in the future, or whether it's just saying "we plan to do that, but might never do it if it turns out to be a bad decision". You say you'll block attempts to remove UIA too quickly, but is it also a possibility you will also block attempts to remove UIA at all or are you closing off that possibility by merging this MSC? If this statement isn't a commitment to do anything specific, then I don't care nearly as much.

[turt2live]

How I read the current phrasing in the MSC is it's suggesting deprecation, which triggers a process for eventual consideration for removal. A different MSC would be required to both make the case for moving from deprecated to removal, and would be reviewed in that context (including counterarguments to say removal is inappropriate).

or in other words, any implied removal in this MSC is non-normative, meaning we're not bound to it.

[olivia-fl]

Cool, I'm gonna not worry about it until then. Thanks for clarifying :)

[olivia-fl]

The specification also currently states that:

The principles that Matrix attempts to follow are:
...

• Keep It Simple & Stupid
  • provide a simple architecture with minimal third-party dependencies.

And that

The functionality that Matrix provides includes:
...

• Managing user accounts (registration, login, logout)

OAuth2/OIDC is a complex third party dependency. Synapse+MAS is an substantial increase in architectural complexity over the current state. Bundling an OIDC server with non-synapse server implementations would be a similar increase in architectural complexity.

My understanding is that this MSC takes the position that managing user accounts should not be part of the functionality that matrix provides, and that it is worth introducing significant third party dependencies and architectural complexity to make that happen. It's inevitable that the documented principles will sometimes come into conflict, and changes may be made that violate some of them because the tradeoffs are worth it. If this is the intention, I would prefer that the decision to depart from the existing documented principles and core functionality was more explicit in the MSC text.

[turt2live]

The dependency can be of varied complexity depending on what the implementation wants to achieve. Discussed in another thread, it's possible for a server implementation to expose a pretty small minimal interface and retain the same functionality as today's login flows, though servers like Synapse are intending to elect for higher complexity at the moment.

From a protocol design perspective, we're just not experts in authentication and would really like to outsource that to another protocol, taking on the dependency. Whether that dependency is OIDC or another authentication protocol is an open question though, and thoughts are welcome on that point. Currently, OIDC appears the most viable due to its widespread use, optional heavy complexity, and relative simplicity on the client side. There is different work for server developers to support it, but at its core it is capable of being added to a homeserver at the same complexity as today's UIA.

Ideally, there would be an implementation of that minimal interface somewhere to either prove it's possible, or prove I'm talking nonsense :p - this is not something the current team driving this proposal will be able to take on, but should hopefully be narrow-scoped enough for a third party implementation to happen, time permitting of course.

[olivia-fl]

There is different work for server developers to support it, but at its core it is capable of being added to a homeserver at the same complexity as today's UIA.

That seems... rather unlikely to me. m.login.password UIA takes maybe 30m reading the spec to understand how to write an implementation. I've done a bit of server-side oauth2 work before and it was a lot more than 30m to learn how things work. I don't really have time or interest in trying to write a minimal implementation myself right now, and think I would be unlikely to persuade anybody by doing so (or by continuing to talk to spec people about it).

time permitting of course.

Again, unlikely I would attempt this, but out of curiosity what is the time requirement?

---

Mainly what I want is for this reasoning to end up in the actual MSC text, to benefit future readers that don't go reading through all the github comments.