wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Spec terms of service at registration (MSC1692) (#1812)

Browse source 
Spec for matrix-org/matrix-spec-proposals#1692

Co-authored-by: Hubert Chathi <hubertc@matrix.org>
This commit is contained in:
Richard van der Hoff 2024-05-08 14:51:18 +01:00 • committed by GitHub
parent f4b34ba962
commit df1e799c51
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 226 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

153
content/client-server-api/_index.md
View file

@ -546,8 +546,10 @@ request parameter.
A client should first make a request with no `auth` parameter.
The homeserver returns an HTTP 401 response, with a JSON body, as follows:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
```json
{
@ -590,8 +592,10 @@ given. It also contains other keys dependent on the auth type being
attempted. For example, if the client is attempting to complete auth
type `example.type.foo`, it might submit something like this:
POST /_matrix/client/v3/endpoint HTTP/1.1
Content-Type: application/json
```
POST /_matrix/client/v3/endpoint HTTP/1.1
Content-Type: application/json
```
```json
{
@ -611,8 +615,10 @@ along with the same object as when no authentication was attempted, with
the addition of the `completed` key which is an array of auth types the
client has completed successfully:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
```json
{
@ -643,8 +649,10 @@ but the client may make a second attempt, it returns the same HTTP
status 401 response as above, with the addition of the standard
`errcode` and `error` fields describing the error. For example:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
```json
{
@ -671,8 +679,10 @@ status 401 response as above, with the addition of the standard
If the request fails for a reason other than authentication, the server
returns an error message in the standard format. For example:
HTTP/1.1 400 Bad request
Content-Type: application/json
```
HTTP/1.1 400 Bad request
Content-Type: application/json
```
```json
{
@ -970,6 +980,129 @@ in the registration process that their token has expired.
{{% http-api spec="client-server" api="registration_tokens" %}}
##### Terms of service at registration
{{% added-in v="1.11" %}}
| Type | Description |
|--------------------------|--------------------------------------------------------------------------|
| `m.login.terms` | Authentication requires the user to accept a set of policy documents. |
{{% boxes/note %}}
The `m.login.terms` authentication type is only valid on the
[`/register`](#post_matrixclientv3register) endpoint.
{{% /boxes/note %}}
This authentication type is used when the homeserver requires new users to
accept a given set of policy documents, such as a terms of service and a privacy
policy. There may be many different types of documents, all of which are
versioned and presented in (potentially) multiple languages.
When the server requires the user to accept some terms, it does so by returning
a 401 response to the `/register` request, where the response body includes
`m.login.terms` in the `flows` list, and the `m.login.terms` property in the
`params` object has the structure [shown below](#definition-mloginterms-params).
If a client encounters an invalid parameter, registration should stop with an
error presented to the user.
The client should present the user with a checkbox to accept each policy,
including a link to the provided URL. Once the user has done so, the client
submits an `auth` dict with just the `type` and `session`, as follows, to
indicate that all of the policies have been accepted:
```json
{
"type": "m.login.terms",
"session": "<session ID>"
}
```
The server is expected to track which document versions it presented to the
user during registration, if applicable.
**Example**
1. A client might submit a registration request as follows:
```
POST /_matrix/client/v3/register
```
```json
{
"username": "cheeky_monkey",
"password": "ilovebananas"
}
```
2. The server requires the user to accept some terms of service before
registration, so returns the following response:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
```json
{
"flows": [
{ "stages": [ "m.login.terms" ] }
],
"params": {
"m.login.terms": {
"policies": {
"terms_of_service": {
"version": "1.2",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-1.2-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-1.2-fr.html"
}
}
}
}
},
"session": "kasgjaelkgj"
}
```
3. The client presents the list of documents to the user, inviting them to
accept the polices.
4. The client repeats the registration request, confirming that the user has
accepted the documents:
```
POST /_matrix/client/v3/register
```
```json
{
"username": "cheeky_monkey",
"password": "ilovebananas",
"auth": {
"type": "m.login.terms",
"session": "kasgjaelkgj"
}
}
```
5. All authentication steps have now completed, so the request is successful:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "abc123",
"device_id": "GHTYAJCE",
"user_id": "@cheeky_monkey:matrix.org"
}
```
{{% definition path="api/client-server/definitions/m.login.terms_params" %}}
#### Fallback
Clients cannot be expected to be able to know how to process every