|
| 1 | +# MSC3939: Account locking |
| 2 | + |
| 3 | +Account locking is a common safety and security tool where server administrators |
| 4 | +can prevent a user from usefully using their account. For example, too many failed |
| 5 | +login attempts, escalation in moderation action, or out of band verification |
| 6 | +needing to be completed. |
| 7 | + |
| 8 | +Currently, Matrix only supports deactivating an account. This is a destructive |
| 9 | +action which often leads to the account leaving all joined rooms, among other |
| 10 | +details. With account locking, the effect of making the user unable to access |
| 11 | +their account is achieved without destroying that same account - the account |
| 12 | +can always be unlocked. |
| 13 | + |
| 14 | +This proposal covers account locking, though leaves the specifics of use as an |
| 15 | +implementation detail. APIs for administration of locking are also not provided. |
| 16 | + |
| 17 | +## Proposal |
| 18 | + |
| 19 | +When an account is locked, clients receive a `401 Unauthorized` error response |
| 20 | +to most APIs with an `M_USER_LOCKED` error code and `soft_logout` set to `true`. |
| 21 | +Excluded APIs are described below. We enable `soft_logout` to encourage clients |
| 22 | +to make use of the [soft logout](https://spec.matrix.org/v1.9/client-server-api/#soft-logout) |
| 23 | +semantics: keep encryption state, but otherwise render the account unusable. 401 |
| 24 | +is used to support legacy clients by giving the user a semantically meaningful |
| 25 | +experience: they may need to try logging in again, and when they do they may get |
| 26 | +a more useful error message about their account status, though their session data |
| 27 | +may be deleted by the client if it doesn't recognize the error code. Soft logout |
| 28 | +aims to prevent total destruction of this data, however. |
| 29 | + |
| 30 | +Upon receiving the `M_USER_LOCKED` error, clients SHOULD retain session information |
| 31 | +including encryption state and inform the user that their account has been locked. |
| 32 | +Details about *why* the user's account is locked are not formally described by |
| 33 | +this proposal, though future MSCs which cover informing users about actions taken |
| 34 | +against their account should have such details. Clients may wish to make use of |
| 35 | +[server contact discovery](https://spec.matrix.org/v1.10/client-server-api/#getwell-knownmatrixsupport) |
| 36 | +in the meantime. |
| 37 | + |
| 38 | +Clients SHOULD hide the normal UI from the user when informing them that their |
| 39 | +account is locked, preventing general use of the account. |
| 40 | + |
| 41 | +Clients SHOULD continue to `/sync` and make other API calls to more quickly detect |
| 42 | +when the lock has been lifted. However, clients should rate-limit their requests. If unlocked, the APIs will either return a different |
| 43 | +error code or a normal 200 OK/successful response. For example, `/sync` will return |
| 44 | +to working as though nothing ever happened. If the error code changes to |
| 45 | +`M_UNKNOWN_TOKEN`, the client should delete local session data as it normally |
| 46 | +would when seeing the error code (and use soft logout as it normally would). This |
| 47 | +is typically expected if the server admin logged the user out or the user logged |
| 48 | +themselves out. |
| 49 | + |
| 50 | +Locked accounts are still permitted to access the following API endpoints: |
| 51 | + |
| 52 | +* [`POST /logout`](https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3logout) |
| 53 | +* [`POST /logout/all`](https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3logoutall) |
| 54 | + |
| 55 | +When a user's account is locked, servers SHOULD NOT invalidate an account's access tokens in case the account becomes |
| 56 | +unlocked: the user should be able to retain their sessions without having to log |
| 57 | +back in. However, if a client requests a logout (using the above endpoints), the |
| 58 | +associated access tokens should be invalidated as normal. |
| 59 | + |
| 60 | +## Potential issues |
| 61 | + |
| 62 | +This proposal does not communicate *why* a user's account is restricted. The human-readable `error` |
| 63 | +field may contain some information, though anything comprehensive may not be surfaced to the user. |
| 64 | +A future MSC is expected to build a system for both informing the user of the action taken against |
| 65 | +their account and allow the user to appeal that action. |
| 66 | + |
| 67 | +## Alternatives |
| 68 | + |
| 69 | +[MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823) covers |
| 70 | +a similar concept, though is semantically different. See [matrix-org/glossary](https://github.com/matrix-org/glossary) |
| 71 | +for details. |
| 72 | + |
| 73 | +Another similar concept would be "shadow banning", though this only applies to |
| 74 | +moderation use cases. |
| 75 | + |
| 76 | +A 403 HTTP status code was considered instead of 401 with a `soft_logout`. A 403 |
| 77 | +would indicate that the given action is denied, but otherwise keep the user logged |
| 78 | +in. This could wrongly indicate [suspension](https://github.com/matrix-org/matrix-spec-proposals/pull/3823), |
| 79 | +confusing the user. Instead, we provide a semantically similar experience where |
| 80 | +the user gets soft logged out on legacy clients, preserving encryption and related |
| 81 | +session data (assuming the client also supports soft logout). This can result in |
| 82 | +some loss of other session data however, like device-specific settings. Users may |
| 83 | +also be differently confused when they try to log back in and get cryptic error |
| 84 | +messages (indicating wrong username/password), however as mentioned above in the |
| 85 | +Potential Issues section, communicating actions taken against an account is a |
| 86 | +concern for a future MSC. |
| 87 | + |
| 88 | +## Unstable prefix |
| 89 | + |
| 90 | +Until this proposal is considered stable, implementations must use |
| 91 | +`ORG_MATRIX_MSC3939_USER_LOCKED` instead of `M_USER_LOCKED`. |
0 commit comments