matrix-org / matrix-authentication-service

OAuth2.0 + OpenID Provider for Matrix Homeservers

OAuth2.0 + OpenID Connect Provider for Matrix Homeservers

MAS (Matrix Authentication Service) is an OAuth 2.0 and OpenID Provider server for Matrix.

It has been created to support the migration of Matrix to an OpenID Connect (OIDC) based authentication layer as per MSC3861.

See the Documentation for information on installation and use.

You can learn more about Matrix and OIDC at areweoidcyet.com.

Features

• Supported homeservers
  • ✅ Synapse
• Authentication methods:
  • ✅ Upstream OIDC
  • 🚧 Local password
  • ‼️ Application Services login (Encrypted bridges)
• Migration support
  • ✅ Compatibility layer for legacy Matrix authentication
  • ✅ Advisor on migration readiness
  • ✅ Import users from Synapse
  • ✅ Import password hashes from Synapse
  • ✅ Import of external subject IDs for upstream identity providers from Synapse

Upstream Identity Providers

MAS is known to work with the following upstream IdPs via OIDC:

• Keycloak
• Dex
• Google

matrix-authentication-service's Issues

Consent flow

When a user uses a client with some scope it should have an explicit consent screen for it.

There are a lot of informations we can display on this screen, including a bunch of metadata about the client, the list of already granted scopes, the list of about-to-be-granted scopes, etc.

The scopes themselves are not defined yet

Consider Open Policy Agent for defining policies

We have a bunch of places where we would have to evaluate instance-specific policies. This includes:

• on registration (is this user allowed to register?)
• on login (is this user/browser allowed to login? should it enforce 2FA? email verification?)
• on compat SSO login (only allow for a subset of users, or based on a user pref)
• on client registration (enforce certain features like DPoP)
• on authz granting (allow certain scope depending on the user & client)

I would rather stay away from having a bazillion knobs for all of those policies, but rather have an extensible system.

In combination with #216, I think leveraging Open Policy Agent for policy evaluation could be the way to go.

With it, we could either:

• have policies deployed, evaluated and logged in a central place if we leverage the OPA server and REST API
• have policies executed locally in a WASM VM

Downside of this approach is probably its complexity for end users. We could mitigate that by shipping sane default policies with a bunch of config knobs

Send SMS to users

Similar to #16, but for MSISDNs.

This could allow SMS-based:

• 2FA
• password-less logins
• account recovery

For the SMS OTP codes, format should follow this spec to allow autofill: https://wicg.github.io/sms-one-time-codes/

Backends to consider:

• Twilio
• AWS SNS
• Whatever we're currently using on vector.im?

login failures cause 500 errors

If login fails, either because the CSRF token is invalid, or because of an invalid username/password, a 500 error is returned. It should probably be a 40x.

CAPTCHA support

During registration, and optionally other operations. To replace the HS capability such as https://github.com/matrix-org/synapse/blob/develop/docs/CAPTCHA_SETUP.md

Open questions:

• Which CAPTCHA provider should we support? With #2759, we will support all of:
  • reCAPTCHA is what we already support in Synapse
  • hCaptcha for a non-Google alternative, highly requested in Synapse by the community
  • Cloudflare Turnstile might be the most user-friendly?
• What operations should be protected? Obvious candidates are:
  • Password-based login
  • Password-based registration
  • Password change
  • When adding an email address
• Where does it fit in the login/registration forms? -> Design suggestion in #2759
• What configuration knob do we give to administrators?

Relevant spec issue: matrix-org/matrix-spec#295

SSO - Upstream CAS provider support

Originally part of #19

SSO - Upstream OIDC provider support

We should support login via OIDC the same way Synapse does. Hopefully we can skip SAML and CAS for now though

Legacy login via m.login.sso

The server already supports m.login.password (#21) for /login. We should also support logging in via m.login.sso to avoid having plain text passwords in the client.

OP => HS notification of sign out

Documentation for config settings

At some point in the not too distant future, we could do with documentation for the available settings in config.yaml.

Having to go through the exercise of writing the documentation can be quite helpful in making sure that the settings make sense from a user's point of view.

Alternative file-based storage backend

Synapse supports both SQLite and PostgreSQL. We currently support PostgreSQL only, but should have an alternative storage backend to accommodate those deployments

AS => HS notification of sessions being logged out

So that it can remove the matrix device and do any clean up.

User profiles

There are many standard claims and scopes in OIDC we could support. This includes

• email
• phone number
• postal address
• full name

We need to decide which information is relevant to add to user profiles and how to store them

Email address verification

When a user adds an email address to their account, they should get an email with a link to verify it

Support dynamic client registration

Support for RFC7591.
See MSC2966.

This is the step where client register themselves and provide metadata about them.

What needs to be supported according to the OIDC conformance profile:
https://openid.net/wordpress-content/uploads/2018/06/OpenID-Connect-Conformance-Profiles.pdf

• ID Token
  • Asymmetric ID Token signature with RS256
• UserInfo Endpoint
  • Can provide signed UserInfo response with RS256
• redirect_uri
  • Reject request without redirect_uri when multiple registered
  • Preserves query parameter in redirect_uri
  • Preserves query parameter in registered redirect_uris
  • Reject redirect_uri when query parameter does not match
  • Reject redirect_uri when query parameter added
  • Reject registration of redirect_uris with fragment
• Discovery
  • Publishes openid-configuration discovery information
  • Config has issuer
  • Discovered issuer matches openid-configuration path prefix
  • Discovered issuer matches ID Token iss value
  • Config has authorization_endpoint
  • Config has token_endpoint
  • Config has userinfo_endpoint
  • Config has jwks_uri
  • Keys in OP JWKs well formed
  • Config has scopes_supported
  • Config has response_types_supported
  • Config has subject_types_supported
  • Config has id_token_signing_alg_values_sup ported
  • Config has claims_supported
  • All OP endpoints use https
  • Can Discover Identifiers using E- Mail Syntax
  • Support WebFinger discovery
• Dynamic Client Registration
  • Config has registration_endpoint
  • Enables dynamic registration
  • Support using Sector Identifier for pairwise sub values
  • Displays logo_uri in login page
  • Displays policy_uri in login page
  • Displays tos_uri in login page
  • Uses keys registered with jwks value
  • Uses keys registered with jwks_uri value
  • Reject Sector Identifier not containing registered redirect_uri values
• Key Rotation
  • Can rotate OP signing key
  • Support RP signing key rotation
• request_uri Request Parameter
  • Support request_uri request parameter
  • Support request_uri request parameter with unsecured request
  • Support request_uri request parameter with signed request

How should Client-Service API endpoints that require auth param be handled?

e.g. https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3keysdevice_signingupload

Tool to import Synapse user DB

At some point we should import the existing users from Synapse's database. It means we need to support Synapse's existing password hashing scheme

i18n/l10n in templates

We need to be able to translate all views. This includes HTML templates as well as emails.

Ideally, we'd use something that is well-supported by Weblate and has nice Rust crates for it. We need to be able to embed translations within the binary (like we're doing for static files and templates) as well as loading new ones at runtime to allow customization of templates without recompiling.

Support alternative credentials (2FA, passwordless, webauthn)

There are a bunch of fun alternative credentials we should explore. That includes:

• 2FA via OTP or WebAuthn
• main credential via WebAuthn only
• passwordless login (send email, click link)

Login and registration flow

Umbrella issue to group everything related to the login and registration flow. This includes:

• #12
• #16
• Agreeing to #22
• #18
• #19
• #30

Audit logs (password changes, consent changes, logins)

We should have a view where users can see what happened to their account. This includes:

• login/logout events
• password changes
• new consent granted

Allow Matrix client to logout using RFC7009 Token Revocation

SSO - Upstream SAML provider support

Originally in #19

Support the device authorization grant

Support for RFC8628. The device authorization grant helps logging in on devices with constrained inputs. This is heavily used in CLI tools, TV/cars, and in general to log in to a device from another one.

Have a public playground with Synapse, Hydrogen and the auth service

OpenID Connect project sandbox/playground environment

We have created a sandbox environment for you to try out the latest developments in the OIDC project.

As a recap, a key goal of the project is to allow Homeservers to delegate auth to a separate server (using the OIDC standard) which would replace the current auth system built into the Homeserver.

This means that rather than registering a user directly on a Homeserver instead you do the registration on an Auth Server.

Clients/Applications to try

You can use one of these to register and login:

• Hydrogen
• Files SDK Demo

Auth Server

Currently you can only register with a username/password (SSO and others are to come).

• Account management

Homeserver

The sandbox is running a customised synapse instance that delegates to OIDC. It isn't federated so you can't access your regular Matrix rooms.

We may also need to reset the sandbox in future so don't use it for anything important!

SSL support

For people running a standalone instance it would be helpful to be able to have an HTTPS listener instead of just HTTP.

Account management screens

A big user-facing part of the app relates to account management. This includes UI for:

• #13
• #27
• #14
• #15
• #9
• #29

A few examples of this kind of screens in the wild:

• Google Account
• Microsoft Account
• Apple ID

Notify Homeserver of password reset

After doing #13 the HS needs to be notified of the reset.

Password change

Users should be able to change their own password

docs for intialising the database

It'd be good to include instructions about how to set up the database in the README. I did:

sudo -u postgres bash
createuser --pwprompt matrix-authentication-service
createdb --encoding=UTF8 --locale=C --template=template0 --owner=matrix-authentication-service matrix-authentication-service

... and then set database.uri to: "postgresql://matrix-authentication-service:<password>@localhost/matrix-authentication-service"

Support DPoP

DPoP is awesome. We should support it.

Extensible metadata on users

We should have a way for storing custom metadata on users. This could include stuff like roles, general profile attributes, etc.

Those metadata could be used for preferences (e.g. "do I allow legacy clients login") or coming from upstream systems (LDAP/upstream IdP). They could then be exposed in templates and used for policy decisions.

HTTP 500 Error with invalid redirect_uri on /authorize

Example URL:

https://auth-oidc.lab.element.dev/oauth2/authorize?client_id=qtcGw06ClL&redirect_uri=http%3A%2F%2Flocalhost%3A5001%2F%23%21%2Fsignin&response_type=code&scope=openid&state=d850ff3d51a34b1a9f83af98236d30a0&code_challenge=0Z51xLUIZcQC3QdXqi-fFJEcRWIveP8UtikrwiVsVn8&code_challenge_method=S256&response_mode=query&prompt=login

The redirect_uri is probably invalid, but the server is only returning a 500 as opposed to 40x.

Save clients in the database

Right now clients are statically defined in the config. We definitely need those to move in the database to support client dynamic registration, and to make reference to clients (foreign keys) easier in the database

Validation of username at point of registration

I noticed that you can register the empty username, " and @.

I don't know what the spec allows, but I suspect the server admin probably wants this to be configurable and compliant.

Make "capabilities URLs" non-guessable

Right now we have a bunch of URLs which rely on a row ID, which are sequential, and since they are not linked to a browser session, anyone can access them.

This currently includes /consent/{id} and post auth actions (e.g. /login?next=continue_authorization_grant&data={id}).

Some guidance on those guidance on those: https://www.w3.org/TR/capability-urls/

Password recovery

Users should be able to recover their account via email.

Potential flows:

1. Start the recovery, you get a code by email, you enter that code, you can set a new password
2. Start the recovery, you get a link by email, you follow that link, you can set a new password

The first flow feels better at not disrupting the current action. If you're in the middle of a client login, it's easier to resume that login after that.

The second flow feels better at preventing social engineering attacks, as we would require the person to click a link and change the password on the same device they are checking their emails, whereas in the option 1., the attacker could just ask "can you give me the code you just got by email" and the user could overlook that it's for a password change?

Open questions:

• Option 1. or 2. -> 2
• What's the input for resetting the account? The Matrix ID or the email address? -> email only
• Email design and wording
• Do we automatically login after password reset? -> no
• Do we send a password change email notification after that? -> ideally
• Do we log off existing sessions when you recover your account that way? -> no
• Do we only use the primary email address, or do we allow any email address on the account? -> all emails, but add email notification if we do so

Relevant design screens:

• Forgot password flow

Instance terms of services and privacy policy

The user should agree to some terms of services before using the auth service. This aims to replace the existing (broken) m.login.terms

Use device code login to do login + cross signing at the same time

There is an opportunity to use the device code login flow in a QR code to combine login and cross-signing the session in a single shot.

One lead would be to embed the (DPoP?) key fingerprint in the QR code

Tagging @BillCarsonFr on this

Depends on #26

Save encrypted fields in the database

At some point it could be useful to save encrypted stuff in the database. This includes client secrets, password hashes, etc.

Active sessions management

A user should be able to see their current active sessions, including;

• the browser agent used
• the clients logged in with that session
• when it started
• when it was last used

They should be able to terminate a particular session

Legacy login support via m.login.password

The auth service will need to handle the existing /login, /logout and /refresh APIs via the m.login.password login type.

More intelligent password strength

There is a basic password policy in place, which can set a minimum password length, require uppercase, lowercase and/or numeric symbols.

This is very basic and lacks direct feedback to the user.
We should instead use a real password strength estimation like zxcvbn and enforce it.
This would also need live feedback to the user whether their password is strong enough or not.

Open questions:

• Is the "interactive feedback as you type" important? If so, this would need design input
• Should this be only a suggestion or enforced? Should we have a default?
• If the minimum strength is configurable, it would be of an opaque number: zxcvbn gives a score out of 4
• Should we keep in parallel the current policy knobs?

Relevant design screens:

• Password entry on account creation
• New password when recovering the account

Send emails to users

There are many reasons why we need to send emails. This includes email confirmations, password recovery, and various other audit events (e.g. when a password change occurs).

Prerequisites:

• have the user emails
• being able to send emails via multiple backends (SMTP, sendmail, Mailgun, AWS SQS, etc.)
• basic template for emails
• send emails for many things

Make the access token TTL configurable

Currently it is hardcoded at 5 minutes but an admin might want to change this.

AS => HS notification of deactivation

Improvement to incorrect password handling

Scope and claims handling

Right now, nothing is done with scopes. The following behaviour need to be implemented:

• only allow /userinfo requests to tokens with the openid scope
• only generate id_tokens when requesting the openid scope
• generate an id_token for hybrid & implicit flows if asked
• advertise the supported scope in the OP metadata
• generate claims and /userinfo infos depending on the scopes
• show a consent screen

Client management

User should be able to know what client they are using and what access they were granted.

Soft-dependency on #1943

This is how it looks like on myaccount.google.com:

Big unordered list of things to do

Features, kinda in order of importance

• Choosing a real name
• Basic session management
  • Logging in
  • Logging out
• Proper form management
  • Proper validation
  • Handling errors gracefully
  • CSRF protection
• OAuth2
  • Simple code authorization flow
  • PKCE
  • Only public clients for now
  • Confidential client authentication
  • Refresh token grant
  • Token introspection
  • Proper error handling
• OIDC
  • Metadata discovery endpoint
  • Implementing the userinfo endpoint
  • Generating an id_token
  • Client dynamic registration
  • Front-channel logouts
• Matrix specific features
  • Device management
  • Client dynamic registration rules
• Account management
  • Registration
  • Deactivation
  • Sending emails (lettre)
  • Password change
  • Password recovery
  • Notification to Synapse via RISC events?
  • Active sessions
  • Client management

Technical stuff, with no particular order

• Clippy lints
• Configuration management (figment)
  • From env
  • From config file
  • Generate a config file with random secrets (ugly)
  • Same, but prettier with nice comments about each field
• Real storage layer
  • Setup sqlx with PG/SQLite database
  • Proper migrations
• Logging/Tracing/Metrics (tracing + opentelemetry)
• i18n (Fluent?)
• Run the OIDC conformance suite
• Docker image
• CI