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

MSC3939: Account locking (#1934)

Browse source
This commit is contained in:
Johannes Marbach 2024-09-26 15:19:45 +02:00 • committed by GitHub
parent 2cbf6067a6
commit ace2712719
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 57 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -100,6 +100,9 @@ section](#soft-logout) for more information.
`M_MISSING_TOKEN`
No access token was specified for the request.
`M_USER_LOCKED`
The account has been [locked](#account-locking) and cannot be used at this time.
`M_BAD_JSON`
Request contained valid JSON, but it was malformed in some way, e.g.
missing required keys, invalid values for keys.
@ -516,6 +519,10 @@ token available. If it does not have a refresh token available, or refreshing
fails with `soft_logout: true`, the client can acquire a new access token by
specifying the device ID it is already using to the login API.
{{% changed-in v="1.12" %}} A client that receives such a response together
with an `M_USER_LOCKED` error code, cannot obtain a new access token until
the account has been [unlocked](#account-locking).
### User-Interactive Authentication API
#### Overview
@ -1425,6 +1432,55 @@ number and a symbol and be at a minimum 8 characters in length. Servers
MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
{{% /boxes/warning %}}
#### Account locking
{{% added-in v="1.12" %}}
Server administrators may apply locks to prevent users from usefully
using their accounts, for instance, due to safety or security concerns.
In contrast to account deactivation, locking is a non-destructive action
that can be reversed. This specification describes the behaviour of clients
and servers when an account is locked. It deliberately leaves the methods
for locking and unlocking accounts as a server implementation detail.
When an account is locked, servers MUST return a `401 Unauthorized` error
response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout)
set to `true` on all but the following Client-Server APIs:
- [`POST /logout`](#post_matrixclientv3logout)
- [`POST /logout/all`](#post_matrixclientv3logoutall)
Servers MAY additionally include details of why the lock was applied in
the `error` field.
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json
```
```json
{
"errcode": "M_USER_LOCKED",
"error": "This account has been locked",
"soft_logout": true
}
```
Servers SHOULD NOT invalidate access tokens on locked accounts unless the
client requests a logout (using the above endpoints). This ensures that
users can retain their sessions without having to log back in if the account
becomes unlocked.
Upon receiving an `M_USER_LOCKED` error, clients SHOULD retain session
information including encryption state and inform the user that their account
has been locked. While the lock is applied, clients SHOULD hide the normal UI
from the user, preventing general use of their account. Clients SHOULD, however,
continue to make rate-limited requests to [`/sync`](#get_matrixclientv3sync)
and other APIs to detect when the lock has been lifted.
To enable users to appeal to a lock clients MAY use
[server contact discovery](#getwell-knownmatrixsupport).
### Adding Account Administrative Contact Information
A homeserver may keep some contact information for administrative use.