Introduction

2021-05-22

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 registration disabled. Like some others who run small servers I do not have the resources to provide a public service, and do not want strangers to be partly reliant on me for 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 them with the required login information. This means: extra interaction is required to set-up an account, some people will forget to (or not be bothered to) change their password, and the existing registration flows integrated into clients cannot be used.

It would be useful for server admins to have a method of controlling registrations which requires minimal setup and lets people register through existing clients. This functionality may also be useful to organisations which do not have a single sign-on system. The simplest solution is to authenticate registering users by a token which the admin provides. This would require a small addition to the specification 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 require additional effort on the part of admins and are disconnected from Matrix clients.

The minimum I would like to achieve for GSoC would be to write an MSC for a new user-interactive authentication type and implement the server side in Synapse, including an admin API for managing tokens. I would also aim to implement the client side in Nheko, and, in the event that everything turns out to be easier than expected, it would be nice to support registration tokens 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 will look.

Alice administers a Synapse homeserver (example.net) and wants to allow Bob to create 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 his client and enters the homeserver, username, and password, the client attempts to 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 the request:

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 new request 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 specified it 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 to Alice.

---

<- Back to index