From ace2712719705b3d105e1dad013fcce74f1d9483 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 26 Sep 2024 15:19:45 +0200 Subject: [PATCH] MSC3939: Account locking (#1934) --- .../client_server/newsfragments/1934.feature | 1 + content/client-server-api/_index.md | 56 +++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1934.feature diff --git a/changelogs/client_server/newsfragments/1934.feature b/changelogs/client_server/newsfragments/1934.feature new file mode 100644 index 000000000..75b556885 --- /dev/null +++ b/changelogs/client_server/newsfragments/1934.feature @@ -0,0 +1 @@ +Add account locking as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/3939). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 1a6f1c6ec..e9efe8ec2 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -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.