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

[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.

[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.

[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.

[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.

[tranquillity-codes]

Reposting as a review to create a thread and allow replies, to work around GitHub limitations. Original comment will be replaced with a link to the review.
Reposting a comment we made in #matrix-auth:matrix.org here for better visibility
A preliminary analysis of the security impact in various threat models:

Default Model (Untrusted Server)

Security

The OIDC uses an untrusted party to provide security against another untrusted party. This means that in the default model, by itself, it is a zero net gain or loss.
Second, the OIDC enforces the use of browsers, massively increasing the attack surface. This makes it result in a net negative in the default model.
Let's also analyze restricted clients and privileged clients. We are failing to find a usecase. Let's list 3 of the permissions in the demo, plus a 4th one moderation events, and a 5th one, destructive client actions:

Client actions

View your existing messages

This is managed by the E2EE. In the default threat model, this is like the wolf protecting the sheep from another wolf. The wolf simply should not have access to the sheep. This is already the case.

Send messages on your behalf

In the default threat model, this once again is a net zero because a malicious party (the homeserver) can still do exactly that. Instead, incorporating client keys in the auth DAG of a room would prevent this (and we are working on that, though waiting on the new stateres)

See your profile

Same thing as before, net zero, in order to make the profile data secure against malicious parties, you should encrypt any important data and share the keys. Sort of like 4S.

Moderation actions

Same thing as before, net zero, in order to secure it, moderation events should be authenticated with signing keys of the moderator (another thing that we are working on)

Destructive client actions

Protecting the client's account would once again be better served by having a client (or possibly a user-hosted service, though one which might not be contactable by the homeserver; We work on this in our to-be-drafted Tor proposal) save its state + using pubkeys instead of MXIDs, but roaming accounts is far, far away, so OIDC is an actually realistic solution for this in the short term, as far as we can see. Though for an actually good UX, a secure embedded browser or popup should be utilized, preferably a solution that involves more secure blobs ran in a trusted environment, instead of a full-on browser. Though since platforms lack this, it's more realistic to fall back on a browser, and have the more secure trusted environment stuff experimental.

Phishing

On the web, using a centralized HS-controlled domain for the HS is more resistant to phishing of the actual credentials. This is good, since malicious phishing clients are much, MUCH easier to operate than malicious homeservers or malicious native apps.
For native apps, if you install a native app it can already hook itself into the system and keylog you. But it's more likely to be vetted, so, for native apps, this doesn't really do anything (we think eg. Flatpak)

UX

For browser clients, the argument with the password manager scoping is good. We agree, the UX on the web there is superior.
For native clients, it feels incredibly wonky to manage two windows for one application. Thus, an embedded secure surface that's reparented into the surface is necessary (on Wayland). On Android, this is trickier, as they offer no such thing as we can tell.

Selfhosted model (Trusted server)

It's pretty clearly a huge improvement. Unfortunately most users don't selfhost, and many of those that do are likely to vet their clients (we do that, so we don't have a use). Though there are certainly HS admins out there that would benefit from this for their instances that are trusted (take, a friend group or a corporate environment)

---

We'll analyze the rest later, gonna just leave this here for now.

[programmerjake]

one part you haven't considered is unencrypted public channels e.g. because they're bridged to IRC or similar, there trusting the server is required, so you can't just say everything depends on end-to-end encryption and ignore any other attack vectors.

[tranquillity-codes]

one part you haven't considered is unencrypted public channels e.g. because they're bridged to IRC or similar, there trusting the server is required, so you can't just say everything depends on end-to-end encryption and ignore any other attack vectors.

In what manner have we not considered them ? Exactly what changes ?

If you have any concerns with our assessment write them down, please.

[programmerjake]

I guess that basically there should be a different threat model for public unencrypted rooms with an IRC bridge where the server is trusted to not post stuff you didn't actually say (since IRC has a trusted server model afaik).

[tranquillity-codes]

The authenticity of bridged users is a responsibility of the given bridge.

Public unencrypted rooms should still offer ways of ensuring message integrity (such as integrating client-managed keys into the room DAG for events that have to be intact), though it shouldn't be necessary to not compromise deniability even more than it already is.

Public unencrypted rooms are not impacted by the ability to read messages because anything can read messages already. As for writing messages, this can be handled by introducing an event type a client can send to require the usage of client keys for sending events in a room, this cryptographically prevents unauthenticated clients from writing into the room without permission (possibly with the ability to sign an event that retracts the requirement)