5.1 KiB
MSC3939: Account locking
Account locking is a common safety and security tool where server administrators can prevent a user from usefully using their account. For example, too many failed login attempts, escalation in moderation action, or out of band verification needing to be completed.
Currently, Matrix only supports deactivating an account. This is a destructive action which often leads to the account leaving all joined rooms, among other details. With account locking, the effect of making the user unable to access their account is achieved without destroying that same account - the account can always be unlocked.
This proposal covers account locking, though leaves the specifics of use as an implementation detail. APIs for administration of locking are also not provided.
Proposal
When an account is locked, clients receive a 401 Unauthorized error response
to most APIs with an M_USER_LOCKED error code and soft_logout set to true.
Excluded APIs are described below. We enable soft_logout to encourage clients
to make use of the soft logout
semantics: keep encryption state, but otherwise render the account unusable. 401
is used to support legacy clients by giving the user a semantically meaningful
experience: they may need to try logging in again, and when they do they may get
a more useful error message about their account status, though their session data
may be deleted by the client if it doesn't recognize the error code. Soft logout
aims to prevent total destruction of this data, however.
Upon receiving the M_USER_LOCKED error, clients SHOULD retain session information
including encryption state and inform the user that their account has been locked.
Details about why the user's account is locked are not formally described by
this proposal, though future MSCs which cover informing users about actions taken
against their account should have such details. Clients may wish to make use of
server contact discovery
in the meantime.
Clients SHOULD hide the normal UI from the user when informing them that their account is locked, preventing general use of the account.
Clients SHOULD continue to /sync and make other API calls to more quickly detect
when the lock has been lifted. However, clients should rate-limit their requests. If unlocked, the APIs will either return a different
error code or a normal 200 OK/successful response. For example, /sync will return
to working as though nothing ever happened. If the error code changes to
M_UNKNOWN_TOKEN, the client should delete local session data as it normally
would when seeing the error code (and use soft logout as it normally would). This
is typically expected if the server admin logged the user out or the user logged
themselves out.
Locked accounts are still permitted to access the following API endpoints:
When a user's account is locked, servers SHOULD NOT invalidate an account's access tokens in case the account becomes unlocked: the user should be able to retain their sessions without having to log back in. However, if a client requests a logout (using the above endpoints), the associated access tokens should be invalidated as normal.
Potential issues
This proposal does not communicate why a user's account is restricted. The human-readable error
field may contain some information, though anything comprehensive may not be surfaced to the user.
A future MSC is expected to build a system for both informing the user of the action taken against
their account and allow the user to appeal that action.
Alternatives
MSC3823 covers a similar concept, though is semantically different. See matrix-org/glossary for details.
Another similar concept would be "shadow banning", though this only applies to moderation use cases.
A 403 HTTP status code was considered instead of 401 with a soft_logout. A 403
would indicate that the given action is denied, but otherwise keep the user logged
in. This could wrongly indicate suspension,
confusing the user. Instead, we provide a semantically similar experience where
the user gets soft logged out on legacy clients, preserving encryption and related
session data (assuming the client also supports soft logout). This can result in
some loss of other session data however, like device-specific settings. Users may
also be differently confused when they try to log back in and get cryptic error
messages (indicating wrong username/password), however as mentioned above in the
Potential Issues section, communicating actions taken against an account is a
concern for a future MSC.
Unstable prefix
Until this proposal is considered stable, implementations must use
ORG_MATRIX_MSC3939_USER_LOCKED instead of M_USER_LOCKED.