Token Authenticated Registration for Matrix

Introduction

Sat, 22 May 2021 18:36:00 +0100

This post will pretty much be a copy of the proposal from my GSoC application. Hopefully it will give you a bit of an idea of what I'm going to be doing.

I run a small Matrix homeserver for family and friends with registrationdisabled. Like some others who run small servers I do not have the resources toprovide a public service, and do not want strangers to be partly reliant on mefor their communications.

Therefore, if someone would like an account I have to register it myself,which involves setting the username and password, and then provide themwith the required login information. This means: extra interaction is requiredto set-up an account, some people will forget to (or not be bothered to) changetheir password, and the existing registration flows integrated into clientscannot be used.

It would be useful for server admins to have a method of controllingregistrations which requires minimal setup and lets people register throughexisting clients. This functionality may also be useful to organisations whichdo not have a single sign-on system.The simplest solution is to authenticate registering users bya token which the admin provides. This would require a small addition to thespecification in the form of a new authentication type for the User-Interactive Authentication API.

Existing projects, such as ZerataX's matrix-registration partially solve the problem of token authenticated registration, but requireadditional effort on the part of admins and are disconnected from Matrixclients.

The minimum I would like to achieve for GSoC would be to write an MSC for anew user-interactive authentication type and implement the server side inSynapse, including an admin API for managing tokens. I would also aim toimplement the client side in Nheko, and, in the event that everything turns outto be easier than expected, it would be nice to support registrationtokens in matrix URIs.

Week	Planned Activities
1-2	Draft an MSC. Write a new UserInteractiveAuthChecker for Synapse using a hard-coded list of allowed tokens for testing purposes. Add a configuration option to Synapse which adds the new checker to the authentication flows for registration.
3-4	Remove the hard-coded tokens and instead check against tokens stored in a database.
5-6	Write an admin API for managing tokens.
7	Add a fallback for clients that don't support the new auth type.
8-9	Add support for the new auth type in Nheko.
10	Buffer for finishing things off.

Possible challenges:

Limiting the new UIA type to only the /register endpoint, or make it sufficiently broad that it can be used for any UIA protected endpoint
Getting the database parts right
Deleting single-use tokens after use

Example

The details will likely change, but this should give an idea of how it willlook.

Alice administers a Synapse homeserver (example.net) and wants to allow Bob tocreate account on it.

Alice uses the Synapse admin API to generate a new token:

POST /_synapse/admin/v2/registration-tokens/new{	"uses": 1}

The server replies with the generated token:

HTTP/1.1 200 OK{	"token": "fBVFdqVE"}

Alice gives the token to Bob. When Bob goes to the registration page of hisclient and enters the homeserver, username, and password, the client attemptsto register the account:

POST /_matrix/client/r0/register{	"device_id": "ABC",	"initial_device_display_name": "Some Client",	"password": "badpassword",	"username": "bob"}

However, the homeserver requires a registration token to authenticate therequest:

HTTP/1.1 401 Unauthorized{	"flows": [		{			"stages": [ "m.registration.token" ]		}	],	"params": {},	"session": "xxxxx"}

The client then asks Bob to enter his registration token and sends a newrequest with an auth parameter:

POST /_matrix/client/r0/register{	"auth": {		"type": "m.registration.token",		"token": "fBVFdqVE",		"session": "xxxxx"	}	"device_id": "ABC",	"initial_device_display_name": "Some Client",	"password": "badpassword",	"username": "bob"}

The server registers the account and deletes the token because Alice specifiedit could only be used once. It then responds with success:

HTTP/1.1 200 OK{  "access_token": "abc123",  "device_id": "ABC",  "user_id": "@bob:example.net"}

The client proceeds to it's main interface where Bob can send a message toAlice.

MSC3231

Fri, 04 Jun 2021 20:11:00 +0100

I have written an MSC for token authenticated registration! Take a look at MSC3231 and let me know what you think.

Synapse implementation with hard-coded tokens

Tue, 08 Jun 2021 14:27:00 +0100

I've got token authenticated registration working in Synapse with a hard-coded list of permissible tokens!

This involved:

Adding a configuration option which prepends the registration token UIA type to the flows for registration
Writing a new UserInteractiveAuthChecker which validates a token or raises an error
Writing a couple of unit tests

The next thing to do will be storing the tokens in the database.

Tokens in the database

Fri, 18 Jun 2021 14:50:00 +0100

My WIP Synapse implementationnow checks against tokens stored in a database table.The tokens can have an expiry time and/or a limited number of uses.The table could look a bit like this:

token	allowed_uses	pending	completed	expiry_time
abcd	NULL	0	3	NULL
limited	1	1	0	NULL
expires	5	0	1	1625102880000

The token abcd can be used an unlimited number of times, does not expire and has been used to successfully register three people.
There is once person who has passed UIA using the token limited, but not completed registration yet. That token can only be used once, so while it has a pending use it is invalid for anyone else.
The token expires has four uses left, and will be invalid after 01:28 UTC on July 1st 2021 (expiry_time is given in milliseconds since the Unix epoch).

This involved: creating a table; writing functions to check token validity, seta pending use, and complete a use; and storing the token in the UIA session sothat the token is only used once registration is complete. There are still a few things to smooth out, but it works pretty well.Next I'll implement the validity checking endpoint, and then probably thefallback too, before getting on to the admin API for managing tokens.

Validity Checking and Fallback

Wed, 30 Jun 2021 17:26:00 +0100

Another short update about my progress on the Synapse implementation.

I added:

The endpoint for checking the validity of a token.
A fallback webpage which can be used by clients which don't know about the registration token auth type. This still has some problems with invalid tokens not being rejected gracefully, but that should be sorted at some point.

Both those things turned out to be pretty simple to implement. The exciting thing is that, with the fallback, you can now use a Matrix client to register with a token! The UX of fallbacks is a bit clunky though.

Now, the two big things left for this project are the Synapse admin API, and the client implementation in Nheko.

Admin API

Fri, 16 Jul 2021 14:06:00 +0100

The Synapse implementationnow has an admin API that lets you create, update, delete, and list tokens.This involved writing some new store functions that manipulate the registration_tokens table, adding the new endpoints, and a fair few unit tests.Take a look at the documentation for more detail about how it's used.

There are a few admin API related bits that I'd like to do before the end of GSoC:

A human friendly format for expiry_time (currently you have to give it as milliseconds since the start of the unix epoch).
Pagination when listing tokens.
Saying whether a token is valid or not when returning it.
Maybe adding support for it in synadm, which I found out about recently and haven't yet used.

Apart from a couple issues with expiring sessions and the fallback, the Synapsepart of this project is now pretty much done!Next week I'll be starting on the Nheko implementation :-)

mtxclient and nheko

Thu, 12 Aug 2021 18:12:00 +0100

There is now a working client implementation of token authenticated registration!I added the registration token UIA type to mtxclient and used that in nheko.Those additions come to a grand total of 38 lines of code :D(although I did also reorganise nheko's registration page).

At the moment, nheko asks for the registration token using a dialog after theuser has filled in the registration form.

It could be nice to have the registration token field as part of the form,but the spec is a bit unclear about getting UIA flows in advance ofactually attempting an action, and the possibility of the user trying to changeusername/password part way through could make that a bit difficult. It may comein a future reorganisation of registration in nheko, though.

Final Report

Sun, 22 Aug 2021 16:31:00 +0100

It's the end of Google Summer of Code, and I've achieved what I set out to do!I want to say a big thank you to my mentors anoa, Nico and red_sky for thehelp they have given, and to the others in the community who have madesuggestions for or comments on this project. I've learnt a lot in the pastcouple months, like how to work on big codebases within a big ecosystem,why unit tests can be useful, a bit of C++, and how to be onMatrix Live :-)

Links to all the work I've done are below, but in summary:

I wrote a Matrix Spec Change (MSC) proposal for token authenticated registration
I implemented the MSC in Synapse, the (currently) most used Matrix homeserver
I implemented the MSC in Nheko, a popular cross-platform Matrix client

For more details about each stage, see theblog index.

Of course, there are still a few things to do:

Displaying a message to the user when they enter an invalid registration token in Nheko
Tests for Nheko once the Synapse code is merged
Pagination of the GET /_synapse/admin/v1/registration_tokens endpoint in Synapse
Tests in Complement
Getting the MSC merged
And supporting registration tokens in more clients! (and servers)

Contributions

Before the start of the coding period I worked on a couple of good first issuesfor Synapse and Nheko in order to get a feel for the codebases and workflows.

Make reason and score optional for report_event (Synapse)
Registration well known (Nheko)

As the first part of the GSoC project, I wrote an MSC which describes howregistration tokens in Matrix would work.

MSC3231: Token authenticated registration (Matrix specification)

I then started work on the server implementation in Synapse. This is the bulkof the code I wrote for the project, and was gradually improved over the courseof the coding period. Included is: a configuration option which requires theregistration token user-interactive authentication stage to be completed forregistration; an endpoint for checking the validity of registration tokens;a fallback web page for clients that do not support the authentication typenatively; and an admin API for managing registration tokens.

Implement MSC3231: Token authenticated registration (Synapse)
Display an error during failure of fallback UIA (Synapse)

Before I started work on the client implementation, I reorganised the code forthe registration page in Nheko to make it easier to understand. I then addedsupport for the registration token authentication type tomtxclient (the Matrixlibrary Nheko uses), and used this in Nheko. When a server requires aregistration token, Nheko presents an input dialog where the user can enter one.

Reorganise src/RegisterPage.cpp (Nheko)
Support registration token UIA type (mtxclient)
Support token authenticated registration (Nheko)
Support registration token validity checking (mtxclient)

During GSoC I found out about synadm,a CLI tool for convenient use of Synapse's admin API. Towards the end of thecoding period I added support for the new registration token admin API tosynadm, which has made token management much easier.

Add support for registration token management (synadm)

How to try it

~~None of the code has been released yet, so you'll need to get the latestsources of each project.~~The Synapse implementation is released in v1.42.0, but for Nheko you will needto get the latest source:

git clone https://github.com/Nheko-Reborn/nheko.git

and follow the installation instructions using the bundled mtxclient.

Synapse and Synadm

Wed, 22 Sep 2021 18:02:00 +0100

The Synapse implementationhas been released since Synapsev1.42.0,and support forregistration token management in synadmis available in v0.31.

This makes it a lot easier to use registration tokens: just enable the Synapseconfig option (registration_requires_token) and usesynadm regtok new. Client support is still lacking though :(

Token Authenticated Registration in the Matrix Spec

Thu, 03 Feb 2022 16:08:00 +0100

Been a while since the last update...
The main news is that with the release of v1.2 of the Matrix specification,token authenticated registrationis now in the released spec!ShadowJonathan has written patches to use the stablem.login.registration_token auth type inSynapse andRuma,and I've done the same formtxclient.

A while (2 months) ago I started working on getting token authenticatedregistration support into matrix-js-sdk and matrix-react-sdk so that it can beused in Element Web. I didn't finish this, but hopefully I'll get back to itin the next few weeks. We'll see.

Element Web supports registration tokens

Wed, 22 Feb 2023 21:00:00 +0000

Just over a year since they made it into the spec, Element Web finally nativelysupports registration tokensin version 1.11.23!