From 60c6ecde6ee23c491d71f16de820fda03ec5a3b6 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Fri, 12 Aug 2022 17:08:04 +0100 Subject: [PATCH] Proposal for a M_USER_NOT_APPROVED error code --- proposals/XXXX-user-not-approved-error.md | 90 +++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 proposals/XXXX-user-not-approved-error.md diff --git a/proposals/XXXX-user-not-approved-error.md b/proposals/XXXX-user-not-approved-error.md new file mode 100644 index 000000000..822f65d33 --- /dev/null +++ b/proposals/XXXX-user-not-approved-error.md @@ -0,0 +1,90 @@ +# MSCXXXX: `M_USER_NOT_APPROVED` error code + +Over the past few years, there has been some demand for the ability to let +administrators of homeservers approve any new user created on their homeserver +before their account can be used. This allows for better control upon +registration and a potential option for mitigating abuse as an alternative to +disabling registration on a homeserver or forcing new users to fill in +additional details such as an email address. + +## Proposal + +This document proposes the addition of a new `M_USER_NOT_APPROVED` error code to +the Matrix specification. This error code can be returned in two scenarios: +registration and login. + +This proposal does not describe a way for the homeserver to alert an +administrator about new accounts that are waiting to be reviewed, or a way for +administrators to approve or deny an account. This is left as an implementation +detail, as different homeserver implementations have different ways for +administrators to interact with them (e.g. Synapse's admin API vs Conduit's +admin room). + +### Registration + +When a user successfully registers on a homeserver that is configured so that +new accounts must be approved by an administrator, the final `POST +/_matrix/client/v3/register` request is responded to with a `403 Forbidden` +response that includes the `M_USER_NOT_APPROVED` error code. For example: + +```json +{ + "errcode": "M_USER_NOT_APPROVED", + "error": "This account needs to be approved by an administrator before it can be used." +} +``` + +### Login + +When a user whose account is still pending approval by a server administrator +attempts to log in, `POST /_matrix/client/v3/login` requests are responded to +with a `403 Forbidden` response that includes the `M_USER_NOT_APPROVED` error +code. For example: + +```json +{ + "errcode": "M_USER_NOT_APPROVED", + "error": "This account is pending approval by a server administrator. Please try again later." +} +``` + +This error can be returned in any login request, as long as the homeserver is +confident that the user trying to log in is pending approval - as opposed to +registration requests where only the last one can return such an error, in order +to ensure the registration completes. + +Once an account is approved, homeserver must allow the user to log in (unless +the account becomes unavailable for unrelated reasons, e.g. by getting +deactivated). + +## Potential issues + +This MSC does not include a way to communicate to clients early on whether the +homeserver requires new accounts to be approved by an administrator, which can +make the registration experience frustrating (because the user might not be +expecting to need to wait before using your account). + +It is also unclear how to inform a user about their account being approved. This +can probably be done on a best-effort basis using contact information (e.g. +email address) provided by the user during the registration process, if any. + +## Alternatives + +The homeserver could include a boolean indicating whether new accounts require +approval in the response to an initial `/register` request, but it feels out of +place and possibly non-trivial to implement in a way that doesn't get in the way +of User-Interactive Authentication. + +## Security considerations + +It shouldn't be necessary to implement the `M_USER_NOT_APPROVED` error code on +other endpoints than `/register` and `/login`. This is because other endpoints +are either unauthenticated (in which case we don't care about whether the user +is approved) or authenticated via an access token (in which case the fact that +the user has an access token either means they've managed to log in (meaning +they've been approved) or a server administrator generated one for them). + +## Unstable prefix + +During development, `ORG_MATRIX_MSCXXXX_USER_NOT_APPROVED` must be used instead +of `M_USER_NOT_APPROVED`.