Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Draft
wants to merge 15 commits into
base: main
Choose a base branch
from
+236 −0
Draft

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

Changes from 6 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
4521510
Matrix architecture change to delegate authentication via OIDC
hughns Aug 4, 2022
4550bbc
MSC3861
hughns Aug 4, 2022
00cd76d
typoe
ara4n Aug 9, 2022
b684b84
typoes
ara4n Aug 9, 2022
dd60163
typoes
ara4n Aug 9, 2022
9e58990
Add proposal for Matrix.org Foundation to become member of OpenID Fou…
hughns Aug 9, 2022
fb0dfe7
Update proposals/3861-delegated-oidc-architecture.md
hughns Jan 4, 2023
45c0b1c
Move images inline
hughns Feb 8, 2023
ba0c3dc
Use term OpenID Provider
hughns Feb 8, 2023
ef76bfa
Add note about extending UIA as alternative
hughns Feb 9, 2023
4bffdc9
Add reference to related MSCs
hughns Feb 28, 2023
46adfad
Rework the MSC to better explain the rationale for the change
sandhose Sep 11, 2024
ab746d5
Start writing the actual proposal
sandhose Sep 13, 2024
1f1ef22
Remove unused images
sandhose Sep 16, 2024
dc9d84b
Expand on 'why not just OIDC' and fix some typos
sandhose Sep 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 126 additions & 0 deletions proposals/3861-delegated-oidc-architecture.md
View file
Open in desktop
turt2live marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# MSC3861: Matrix architecture change to delegate authentication via OIDC
Copy link
Contributor

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?

Copy link
Member

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?


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:

![](https://i.imgur.com/wZfIzr5.png)
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:

![](https://i.imgur.com/JIM8cGA.png)

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.

![](https://i.imgur.com/NMqiFSl.png)

There are six proposed action points:

1. Accept the set of MSCs to enable delegation via OIDC.
1. The Matrix.org Foundation join the [OpenID Foundation](https://openid.net/foundation/) as a non-profit member to support their work to build a robust and audited ecosystem for open authentication.
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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.
Copy link
Contributor

@MTRNord MTRNord Feb 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## 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)