diff --git a/proposals/3866-user-not-approved-error.md b/proposals/3866-user-not-approved-error.md new file mode 100644 index 000000000..34afadced --- /dev/null +++ b/proposals/3866-user-not-approved-error.md @@ -0,0 +1,126 @@ +# MSC3866: `M_USER_AWAITING_APPROVAL` 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_AWAITING_APPROVAL` 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). + +An error with the code `M_USER_AWAITING_APPROVAL` must include an +`approval_notice_medium` field, which indicates to the user how the homeserver +will let them know of their account's approval. This proposal specifies the +following values: + +* `m.email`: the user is made aware of their account's approval by email to an + address they provided during registration. +* `m.none`: the user is not made aware of their account approval in an automated + way that's managed by the homeserver. This can mean that a server + administrator will reach out to them out of bounds (using any relevant + medium), or that they should wait some time and try logging in again to see if + their account has been approved. + +### 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_AWAITING_APPROVAL` error code. For example: + +```json +{ + "errcode": "M_USER_AWAITING_APPROVAL", + "error": "This account needs to be approved by an administrator before it can be used.", + "approval_notice_medium": "m.email" +} +``` + +### 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_AWAITING_APPROVAL` +error code. For example: + +```json +{ + "errcode": "M_USER_AWAITING_APPROVAL", + "error": "This account is pending approval by a server administrator. Please try again later.", + "approval_notice_medium": "m.email" +} +``` + +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. + +This error can also be returned by login requests performed in the context of a +user's first authentication through an SSO provider. Since this does not involve +the user's client performing a `/register` request, this means the homeserver +must track approval of users when they are registered as part of the SSO flow. + +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 + +### Informing the user about this feature before they register + +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 their account). The author of this +proposal tried and failed to figure out a good way to expose this information: + +* the capabilities endpoint is authenticated and therefore does not work in this + context +* the `/versions` endpoint does not feel like the correct place to expose + information about locally-enabled features +* adding a boolean to initial `/register` requests feels out of place, and could + potentially be non-trivial to implement in a way that doesn't get in the way + of User-Interactive Authentication + +### Informing the user about their account's approval + +By design, Matrix does not force users to provide way to contact them outside of +Matrix (e.g. via email) when registering. This means the homeserver might not +have a way to let the user know once their account has been approved by their +administrator. In this case, homeservers should use the `m.none` value for the +`approval_notice_medium` field in error responses. The expectation is then that +a server administrator reaches out to the user out of bounds, or that the user +waits some time before manually trying to log in again. + +## Security considerations + +It shouldn't be necessary to implement the `M_USER_AWAITING_APPROVAL` 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, the following unstable identifiers must be used: + +| Stable identifier | Unstable identifier | +|----------------------------|---------------------------------------------| +| `M_USER_AWAITING_APPROVAL` | `ORG.MATRIX.MSC3866_USER_AWAITING_APPROVAL` | +| `m.email` | `org.matrix.msc3866.email` | +| `m.none` | `org.matrix.msc3866.none` |