diff --git a/changelogs/client_server/newsfragments/3616.feature b/changelogs/client_server/newsfragments/3616.feature new file mode 100644 index 00000000..307e527f --- /dev/null +++ b/changelogs/client_server/newsfragments/3616.feature @@ -0,0 +1 @@ +Add token-authenticated registration support as per [MSC3231](https://github.com/matrix-org/matrix-doc/pull/3231). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/3616.new b/changelogs/client_server/newsfragments/3616.new new file mode 100644 index 00000000..a1d875ee --- /dev/null +++ b/changelogs/client_server/newsfragments/3616.new @@ -0,0 +1 @@ +Add `/register/m.login.registration_token/validity` as per [MSC3231](https://github.com/matrix-org/matrix-doc/pull/3231). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 7dfc4598..dbc324fb 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -618,6 +618,7 @@ This specification defines the following auth types: - `m.login.email.identity` - `m.login.msisdn` - `m.login.dummy` +- `m.login.registration_token` ##### Password-based @@ -789,6 +790,49 @@ just the type and session, if provided: } ``` +##### Token-authenticated registration + +{{% added-in v="1.2" %}} + +| Type | Description | +|-------------------------------|-------------------------------------------------------------------| +| `m.login.registration_token` | Registers an account with a pre-shared token for authentication | + +{{% boxes/note %}} +The `m.login.registration_token` authentication type is only valid on the +[`/register`](#post_matrixclientv3register) endpoint. +{{% /boxes/note %}} + +This authentication type provides homeservers the ability to allow registrations +to a limited set of people instead of either offering completely open registrations +or completely closed registration (where the homeserver administrators create +and distribute accounts). + +The token required for this authentication type is shared out of band from +Matrix and is an opaque string with maximum length of 64 characters in the +range `[A-Za-z0-9._~-]`. The server can keep any number of tokens for any +length of time/validity. Such cases might be a token limited to 100 uses or +for the next 2 hours - after the tokens expire, they can no longer be used +to create accounts. + +To use this authentication type, clients should submit an auth dict with just +the type, token, and session: + +```json +{ + "type": "m.login.registration_token", + "token": "fBVFdqVE", + "session": "" +} +``` + +To determine if a token is valid before attempting to use it, the client can +use the `/validity` API defined below. The API doesn't guarantee that a token +will be valid when used, but does avoid cases where the user finds out late +in the registration process that their token has expired. + +{{% http-api spec="client-server" api="registration_tokens" %}} + #### Fallback Clients cannot be expected to be able to know how to process every diff --git a/data/api/client-server/registration_tokens.yaml b/data/api/client-server/registration_tokens.yaml new file mode 100644 index 00000000..11241b57 --- /dev/null +++ b/data/api/client-server/registration_tokens.yaml @@ -0,0 +1,80 @@ +# Copyright 2022 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Registration Token API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/register/m.login.registration_token/validity": + get: + x-addedInMatrixVersion: "1.2" + summary: Query if a given registration token is still valid. + description: |- + Queries the server to determine if a given registration token is still + valid at the time of request. This is a point-in-time check where the + token might still expire by the time it is used. + + Servers should be sure to rate limit this endpoint to avoid brute force + attacks. + operationId: registrationTokenValidity + parameters: + - in: query + name: token + type: string + x-example: "fBVFdqVE" + required: true + description: The token to check validity of. + responses: + 200: + description: The check has a result. + examples: + application/json: { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: |- + True if the token is still valid, false otherwise. This should + additionally be false if the token is not a recognised token by + the server. + required: ['valid'] + 403: + description: |- + The homeserver does not permit registration and thus all tokens are + considered invalid. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Registration is not enabled on this homeserver." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Account management