_ _ _ ___ __ _ _ __ ___ __ _____ ___ (_) __| | ___ _ _ ___| |_/ _ \ / _` | '__/ _ \ \ \ /\ / / _ \ / _ \| |/ _` |/ __| | | | |/ _ \ __\// / | (_| | | | __/ \ V V / __/ | (_) | | (_| | (__ | |_| | __/ |_ \/ \__,_|_| \___| \_/\_/ \___| \___/|_|\__,_|\___| \__, |\___|\__| () |___/
We have also set up the Matrix OIDC Playground which contains Homeservers, OIDC Providers and Clients for you to try out.
There are also some videos below showing some of the use cases in action.
For detailed background on the rationale to this project please see MSC3861.
TL;DR Currently Matrix uses a custom authentication protocol baked in to the Matrix spec. This poses a number of drawbacks. To overcome these drawbacks we are working to migrate to use the industry standard authentication protocol Open ID Connect (OIDC) instead.
Good question. There are a number of moving parts to this project which are outlined below.
|MSC3861: Matrix architecture change to delegate authentication via OIDC||✅ Draft but ready for review once dependencies are also ready||n/a|
|MSC2964: Delegation of auth from homeserver to OIDC Provider||🚧 Draft||🚧 Partial implementations in the Playground|
|MSC2965: OIDC Provider discovery||✅ Feature complete||✅ Available in the Playground|
|MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix||🚧 Draft||✅ Available in the Playground|
|MSC2967: API scopes||🚧 Not yet feature complete||🚧 Partially implemented|
|MSC3824: OIDC-aware clients||✅ Feature complete||✅ Available in the Playground|
Outstanding key decision points:
- How will UIA protected endpoints work?
|Specify OP to be used in /.well-known/matrix/client||MSC2965||REQUIRED||✅||❌|
|Token verification and introspection||RFC7662||REQUIRED||✅ using RFC7662 Token Introspection but probably want to also support plain short lived JWT||❌|
|Auto-provisioning of Matrix device||MSC2964||REQUIRED||✅||❌|
|Auto-provision Matrix user based on token introspection||REQUIRED||✅||❌|
|Enforce base user scope||MSC2967||REQUIRED||🚧 PR||❌|
|Handling of guest scope||MSC2967||REQUIRED||🚧 PR||❌|
|Handling of UIA scope||MSC2967||REQUIRED||🚧 PR||❌|
|Receive and process sign out notifications from OP||🚧||REQUIRED||✅ Using admin API||❌|
|Receive and process account deletion from OP||🚧||REQUIRED||✅ Using admin API||❌|
|Specify OP web UI in .well-known as account||RECOMMENDED||✅||❌|
|GET /_matrix/client/v3/capabilities should include
||REQUIRED||✅ by ensuring password auth is off||❌|
n.b. this is currently all in a branch of Synapse rather than in mainline.
MSC3824 proposes four types of Matrix client:
- OIDC native client - This is a client that fully uses OIDC when talking to an OIDC enabled homeserver.
- OIDC aware client - This is a client that is aware of OIDC but will still use existing auth types (e.g.
m.login.sso) to auth with an OIDC enabled homeserver.
- Legacy client with SSO support - This is a client that is not aware of OIDC but does support
m.login.ssoflow. e.g. Element Web, iOS, Android, FluffyChat, Nheko, Cinny
- Legacy client without SSO support - This is a client that is not aware of OIDC at all and nor does it support
m.login.ssoflow. Typically auth is done via
m.login.passwordonly. e.g. Fractal
OIDC Native clients
|Requirement||Relevant spec(s)||Hydrogen||Files SDK Demo||Element Web||Element iOS||Element Android||Element X iOS|
|Discovery of OP in /.well-known/matrix/client||REQUIRED||MSC2965||✅||✅||❌||❌||❌||✅|
|Discovery of OP web UI in /.well-known/matrix/client and outbound linking to it||RECOMMENDED||MSC2965||✅||✅||❌||❌||❌||❌|
|Dynamic client registration||REQUIRED||MSC2966 and RFC7591 OAuth 2.0 Dynamic Client Registration Protocol||✅||✅||❌||❌||❌||✅|
|Signup flow - prompt=create||REQUIRED||✅||✅||❌||❌||❌||❌|
|Login flow - no prompt param||REQUIRED||✅||✅||❌||❌||❌||❌|
|Refresh token handling||REQUIRED||OpenID Connect Core 1.0||✅||✅||❌||❌||❌||❌|
|Sign out - Token revocation||REQUIRED||RFC7009 Token Revocation||✅||✅||❌||❌||❌||❌|
|Re-auth for sensitive actions||REQUIRED||🚧 The spec for this is not yet complete||❌||❌||❌||❌||❌||❌|
OIDC Aware clients
These are the requirements for a client to be OIDC-aware from MSC3824:
|Requirement||Relevant spec(s)||Element Web||Element iOS||Element Android|
|Sign post and link users to manage their account at the OP web UI given by MSC2965||RECOMMENDED||MSC2965 and MSC3824||🎓PR||❌||🎓PR|
|Label the SSO button as “Continue”||RECOMMENDED||MSC3824||🎓PR||❌||🎓PR|
|Requirement||Purpose||Matrix Auth Service||Keycloak||Okta||ZITADEL||Auth0|
|Support for OpenID Connect Core 1.0||REQUIRED||✅||✅||✅||✅||✅|
|Support for OpenID Connect Discovery 1.0 without auth||To allow Matrix client and HS to know how to interact with OP MSC2965||REQUIRED||✅||✅||✅||✅||✅|
|OP => HS notification of sign out||Session/device management||REQUIRED||❌Planned||❌ Would need a keycloak event listener that then made outbound HTTP requests in some format supported by the HS||TODO: look at extension points in Okta||🚧 Requires a post-logout trigger for Actions||Use https://auth0.com/docs/customize/log-streams/custom-log-streams to push events to HS|
|OP => HS notification of deactivation||REQUIRED||❌Planned||✅ Via event listener||❌ TODO: look at extension points in Okta||🚧 Requires a deactivation trigger for Actions||❌ Usehttps://auth0.com/docs/customize/log-streams/custom-log-streams to push events to HS|
|RFC7009 Token Revocation||Allow Matrix client to logout their own session||REQUIRED||✅Planned||✅||✅||✅||✅But, refresh tokens only|
|RFC7662 OAuth Token Introspection or Short lived JWT Or some other agreed scheme||Allow HS to check validity and capabilities of access token with OP||REQUIRED||✅ RFC7662||✅ RFC7662||✅ RFC7662||✅ RFC7662||🚧 JWT - which currently isn’t supported by Synapse|
|RFC7636 OAuth PKCE||Protection against authorization code interception attack||REQUIRED||✅||✅||✅||✅||✅|
|Web UI for managing sessions||Can optionally use an id_token_hint param as detailed inMSC2965||RECOMMENDED||🚧 In progress||✅ User Account Service||✅||✅||❌|
||Basic API permissioning||REQUIRED||✅||✅||✅||🚧 Requires scope/claim manipulation action||✅|
|🚧 Support for
||Permissioning for UIA endpoints||REQUIRED||🚧||🚧||🚧||🚧 Requires scope/claim manipulation action||🚧|
|Handle device ID custom scope
||Session/device management||REQUIRED||✅||✅Using dynamic-scopes feature||❌ it is unclear if this is possible||🚧 Requires scope/claim manipulation action||❌ it is unclear if this is possible|
||Basic API permissioning||REQUIRED||✅||✅||✅||🚧 Requires scope/claim manipulation action||✅|
|Prevent reuse of user ID after account deletion||Requirement of Homeserver||REQUIRED||❌ Planned||❌ Needs custom user profile SPI||?||?||?|
|OpenID Connect Dynamic Client Registration in conformance with MSC2966||Allow a HS to accept logins from any Matrix client||OPTIONAL||🚧In progress||✅ But, request is blocked by CORS on web||❌An API token is required to call the registration endpoint||❌||✅Yes|
|T&C opt-in for registration||Where HS admin wants it||OPTIONAL||❌Planned||✅Yes||❌ No||✅||❌Unclear|
|reCAPTCHA for registration||Where HS admin wants it||OPTIONAL||❌Planned||✅Yes||✅Yes||✅ reCaptcha Enterprise||✅Yes|
|Support for upstream OIDC Provider||Single Sign On/social login||OPTIONAL||❌Planned||✅||✅||✅||✅|
|Support for upstream SAML provider||Single Sign On||OPTIONAL||❌Planned||✅||✅||✅||✅|
|Support for upstream CAS provider||Single Sign On||OPTIONAL||❌Planned||?||?||❌||?|
|Allow user to add multiple email addresses and verify them||Allow HS to use email as target for notifications. Also used for Identity Server?||OPTIONAL||✅||❌ Would need extension||❌Only one additional email + no verification(?)||✅ Yes, through Metadata||❌Additional custom fields but no verification|
|Allow user to add phone numbers and verify them||?||OPTIONAL||❌||✅ Yes, if a Twillio account is configured||❌|
|Those email address and phone number exposed via ID token and or user info endpoint||✅ Yes, claims can be asserted to the ID Token|
|Compatibility layer so that non-OIDC native clients can connect to OIDC enabled Homeserver||🚧 In progress via Matrix Auth Service||❌ Not required?|
|Ability for auth server to run embedded within process||❌ Planned via Matrix Auth Service||❌ Not required?|
|Ability to migrate existing password user into Matrix Auth Service||❌ Planned||❌ Desirable?|
|Ability to migrate existing SSO users into Matrix Auth Service||❌ Planned||Not required - no SSO support at present|
|Ability to migrate existing access tokens into Matrix Auth Service||❌ Planned - requires client to support refresh tokens?||?|
Are we going to migrate existing accounts over?
That will depend on the homeserver administrator. In the case of the matrix.org homeserver we will.
We are planning to implement a number of migration capabilities outlined above.
Will I lose my old-style login/password?
Assuming that your homeserver migrates you to an OIDC Provider that supports username/password login then you will still be able to use that to sign in.
However, you will be entering your username/password into a UI controlled by the OIDC Provider, not the client.
How do I do social login with this?
Similar to how the homeserver achieves this today, the OIDC Provider can act as an identity broker and support login via upstream social (and other) identity providers.
How will this look in native mobile apps?
We’ve built proof of concept apps to explore this and show how it can behave:
In both cases it is a lightweight app built using the AppAuth SDK. The OIDC Provider used here is the matrix-authentication-service.
The plan is to build these out a bit further to explore some more of the handover points between the app and OIDC Provider (e.g. for account management).
How does this work with QR code login?
The RFC8628 OIDC device authorization grant (aka “device flow”) can be used to allow login on a device using a second device.
An implementation of this is available to try in the OIDC Playground.
It can work a bit like this:
What do I do for my device which doesn’t have a web browser?
OIDC provides at least two flows that could help with this:
- Use the Device Authorization Grant (a.k.a. “device flow”) to complete the login on a secondary device that does have a web browser. On the QR flow demo above you can see an example URL and code that would be used on the second device.
- Use a Resource Owner Password Credentials Grant (a.k.a. “password grant” or “direct grant”) where the username and password are entered into the client (i.e. the 3DS) and the client then sends the username and password to the OIDC Provider to get an access token.
It is important to note that the second option (Resource Owner Password Credentials Grant) is considered insecure by the OAuth 2.0 Security Best Current Practice guide. As such, it is expected that the presence of this capability in an OIDC Provider can not be relied on. For example, we don’t expect that matrix.org will support this flow.
How will this work with E2EE?
It works in the same way that the current password login works: login is separate from E2EE setup.
That said, there are some scenarios that OIDC can help with. For example, when signing in to a new device you can use the OIDC device flow on an existing login to both authorise the sign in and also verify the new device for E2EE.
Does this mean I can’t combine E2EE & account password?
In short, yes. However, in a world that is (gradually) moving away from passwords, this isn’t necessarily a bad thing.
Today there are also many cases where users don’t have a password: SSO, social login, web passkeys etc.
The reason that this doesn’t work well in OIDC is that there isn’t a standard OIDC/OAuth grant that allows for a trusted client to authenticate using a PAKE mechanism meaning that the password can remain in the client.
If the client was to just sent the password to the OIDC Provider like it does today then the E2EE could be broken by the OIDC Provider/homeserver operator.
Part of the reason why there isn’t a grant for this use case is that the OIDC model is predicated on the idea that the client is considered low on the trust ladder and so shouldn’t be trusted with the credentials.
However, with our use case for E2EE the client is high on the trust ladder as it is necessarily responsible for the E2EE integrity.
So, arguably a custom grant using PAKE could be used and not break the trust model in Matrix.
What’s this matrix-authentication-service that I’ve heard about?
It is designed to be lightweight enough (using Rust) that it can be embedded within a homeserver process (such as a Synapse).
At this stage you could think of it as a bit like SQLite vs PostgreSQL support in Synapse: Synapse ships with SQLite built-in for quickstart, but you can easily scale out to PostgreSQL where you need to - similarly Synapse will ship with Matrix-Authentication-Service by default, but can scale out to KeyCloak or another provider for additional authentication capabilities.
Are you really rebuilding all of Keycloak in matrix-authentication-service?!
Hopefully not! In the same way that Matrix is not an authentication protocol, it also doesn’t make sense to completely reinvent the OIDC Provider “wheel”.
As to how far we will get… it will most likely depend on what we need for migration support.
Will clients need to support both old-style and new-style auth?
For a period of time, yes.
Similarly, some homeservers (depending on how they are being used) will need to support both old-style (non-OIDC) and new-style (OIDC) client auth for a period of time.
How do I migrate from my existing SSO to new-style OIDC?
You could either get your existing clients to re-login via OIDC or we are planning for being able to migrate existing SSO logins and access tokens over to the matrix-authentication-service OP.
Does this mean that the login page/screen’s branding won’t match the branding of my app any more?
Assuming that you are following best practise and not using the Resource Owner Password Credentials Grant, then: yes, the branding on the login form is under the control of the homeserver administrator not the client.
That said, if you are operating your own client and homeserver then you can brand and customise both as you wish.
The openness of the Matrix ecosystem is a defining feature. That a user can choose which client and homeserver to use is a key part of that.
We believe that, by adopting the OIDC model and making the division between the client and homeserver more explicit, we can better build trust in the open ecosystem and allow it to continue to grow and flourish.
The branding trade-off is an interesting aspect of this: yes, as a client implementor you may lose some control over the branding of the login page. However, you gain from where the user has already signed in on their device - the user does not need to reauthenticate to use your client.
Hang on, isn’t this just an MSC? It all sounds very final?
Correct, it is a proposal at this stage. However, we need to prove it first - MSCs require proof in a working implementation before they can be approved.
We’ve outlined the plan here that assumes that the MSC will be successful.