matrix-spec-proposals/proposals/3231-token-authenticated-registration.md

MSC3231: Token Authenticated Registration

Currently, homeserver administrators must choose between allowing anyone to register and completely disabling registrations. This is a problem for administrators who want to let certain people have an account on their server, but do not want to register the accounts manually (possibly because the initial password may not be changed by the user).

There are some existing external solutions (see the Alternatives section), but these require additional effort from administrators and are disconnected from Matrix clients. It would be useful for administrators to have a convenient method of limiting registrations to certain people which requires minimal setup and is integrated with existing clients.

Proposal

The /_matrix/client/r0/register endpoint uses the User-Interactive Authentication API. A new authentication type m.login.registration_token will be defined which requires a token key to be present in the submitted auth dict. The token will be a string of no more than 64 characters, and contain only characters matched by the regex [A-Za-z0-9._~-]. This will avoid URL encoding issues with the validity checking endpoint, and prevent DoS attacks from extremely long tokens.

For example, when a client attempts registration with no auth dict, a server may respond with:

HTTP/1.1 401 Unauthorized

{
	"flows": [
		{
			"stages": [ "m.login.registration_token" ]
		}
	],
	"params": {},
	"session": "xxxxx"
}

The client would then prompt the user to enter a token and send a new request with an auth dict:

POST /_matrix/client/r0/register

{
	"auth": {
		"type": "m.login.registration_token",
		"token": "fBVFdqVE",
		"session": "xxxxx"
	}
	"device_id": "ABC",
	"initial_device_display_name": "Some Client",
	"password": "badpassword",
	"username": "bob"
}

If the server verifies that fBVFdqVE is a valid token then the account is registered as normal assuming all other required auth stages have been completed, otherwise a 401 status is returned. Once registration of the user has completed, the server may alter the validity of the token. For example, the token may be completely invalidated, or its number of permitted uses reduced. Management of the tokens is left to the server implementation.

Using the User-Interactive Authentication API means clients' existing registration logic will be unaffected, with a fallback available for clients without native support for the new authentication type.

Checking the validity of a token

A Client may wish to present username and password inputs only after it has checked the token is valid.

Clients would be able to check the validity of a token in advance of registration with a GET request to /_matrix/client/r0/register/m.login.registration_token/validity. This endpoint would take a required token query parameter, and validity would be indicated by the boolean valid key in the response.

For example, a client would send:

GET /_matrix/client/r0/register/m.login.registration_token/validity?token=abcd

If abcd is a valid token, the server would respond with:

HTTP/1.1 200 OK

{
	"valid": true
}

This does not perform any actual authentication, and the validity of the token may change between the check and the User-Interactive Authentication.

This endpoint should be rate limited in order to prevent dictionary attacks.

Potential issues

The new authentication type would only apply to the /_matrix/client/r0/register endpoint. This should not cause problems, but it would be worth noting in any change to the specification.

Alternatives

matrix-registration is an application which provides token management and a standalone web interface. It uses Synapse's admin API to do registrations.

Midnight sits in front of a homeserver and handles the /_matrix/client/r0/register endpoint. It provides token management and does additional checks on the requested username. Registration requests are forwarded to the homeserver once authenticated. It uses the User-Interactive Authentication API in a very similar way to this MSC, which could allow existing Matrix clients to be used.

matrix-register-bot is a Matrix bot which allows registrations done through the provided web interface to be accepted or denied by users in a certain room. When a registration is approved temporary credentials are sent to the user's verified email address. It can use Synapse's admin API or matrix-synapse-rest-auth to do the registration.

Unstable prefix

Implementations should use org.matrix.msc3231.login.registration_token as the authentication type until this MSC has passed FCP and been merged. Similarly, /_matrix/client/unstable/org.matrix.msc3231/register/org.matrix.msc3231.login.registration_token/validity should be used as the endpoint for checking the validity of a token in advance.