MSC3231: Token authenticated registration

proposals/3231-token-authenticated-registration.md

@@ -0,0 +1,138 @@
+# 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](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-register)
+endpoint uses the [User-Interactive Authentication API](https://matrix.org/docs/spec/client_server/r0.6.1#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](https://github.com/ZerataX/matrix-registration/) is an
+application which provides token management and a standalone web interface.
+It uses Synapse's admin API to do registrations.
+
+[Midnight](https://github.com/KombuchaPrivacy/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](https://github.com/krombel/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](https://github.com/kamax-matrix/matrix-synapse-rest-password-provider#integrate)
+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.