From 60c6ecde6ee23c491d71f16de820fda03ec5a3b6 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Fri, 12 Aug 2022 17:08:04 +0100 Subject: [PATCH 1/6] 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`. From aa87ba91fd09ec0d605ae51a8b48b0f534c281e0 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Fri, 12 Aug 2022 17:10:17 +0100 Subject: [PATCH 2/6] MSC number --- ...-not-approved-error.md => 3866-user-not-approved-error.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{XXXX-user-not-approved-error.md => 3866-user-not-approved-error.md} (97%) diff --git a/proposals/XXXX-user-not-approved-error.md b/proposals/3866-user-not-approved-error.md similarity index 97% rename from proposals/XXXX-user-not-approved-error.md rename to proposals/3866-user-not-approved-error.md index 822f65d33..77fd37f26 100644 --- a/proposals/XXXX-user-not-approved-error.md +++ b/proposals/3866-user-not-approved-error.md @@ -1,4 +1,4 @@ -# MSCXXXX: `M_USER_NOT_APPROVED` error code +# MSC3866: `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 @@ -86,5 +86,5 @@ 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 +During development, `ORG_MATRIX_MSC3866_USER_NOT_APPROVED` must be used instead of `M_USER_NOT_APPROVED`. From 48ade79bd5150c23c44c7c090568fe469e0b4f62 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 15 Aug 2022 11:47:04 +0100 Subject: [PATCH 3/6] Update error code following review --- proposals/3866-user-not-approved-error.md | 35 ++++++++++++----------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/proposals/3866-user-not-approved-error.md b/proposals/3866-user-not-approved-error.md index 77fd37f26..7f8aa86f2 100644 --- a/proposals/3866-user-not-approved-error.md +++ b/proposals/3866-user-not-approved-error.md @@ -1,4 +1,4 @@ -# MSC3866: `M_USER_NOT_APPROVED` error code +# 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 @@ -9,9 +9,9 @@ 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 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 @@ -25,11 +25,11 @@ admin room). 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: +response that includes the `M_USER_AWAITING_APPROVAL` error code. For example: ```json { - "errcode": "M_USER_NOT_APPROVED", + "errcode": "M_USER_AWAITING_APPROVAL", "error": "This account needs to be approved by an administrator before it can be used." } ``` @@ -38,12 +38,12 @@ response that includes the `M_USER_NOT_APPROVED` error code. For example: 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: +with a `403 Forbidden` response that includes the `M_USER_AWAITING_APPROVAL` +error code. For example: ```json { - "errcode": "M_USER_NOT_APPROVED", + "errcode": "M_USER_AWAITING_APPROVAL", "error": "This account is pending approval by a server administrator. Please try again later." } ``` @@ -77,14 +77,15 @@ 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). +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, `ORG_MATRIX_MSC3866_USER_NOT_APPROVED` must be used instead -of `M_USER_NOT_APPROVED`. +During development, `ORG_MATRIX_MSC3866_USER_AWAITING_APPROVAL` must be used +instead of `M_USER_AWAITING_APPROVAL`. From 96296d034c319bf4cc7f16e2e7d26e7ef9231af1 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 15 Aug 2022 15:59:04 +0100 Subject: [PATCH 4/6] Fix unstable prefix --- proposals/3866-user-not-approved-error.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3866-user-not-approved-error.md b/proposals/3866-user-not-approved-error.md index 7f8aa86f2..4cf31b873 100644 --- a/proposals/3866-user-not-approved-error.md +++ b/proposals/3866-user-not-approved-error.md @@ -87,5 +87,5 @@ them). ## Unstable prefix -During development, `ORG_MATRIX_MSC3866_USER_AWAITING_APPROVAL` must be used +During development, `ORG.MATRIX.MSC3866_USER_AWAITING_APPROVAL` must be used instead of `M_USER_AWAITING_APPROVAL`. From 3df48d3349538081cc015948a0be12ccb783707a Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 28 Sep 2022 16:59:46 +0100 Subject: [PATCH 5/6] Incorporate review --- proposals/3866-user-not-approved-error.md | 57 +++++++++++++++++------ 1 file changed, 43 insertions(+), 14 deletions(-) diff --git a/proposals/3866-user-not-approved-error.md b/proposals/3866-user-not-approved-error.md index 4cf31b873..52fc4f7f0 100644 --- a/proposals/3866-user-not-approved-error.md +++ b/proposals/3866-user-not-approved-error.md @@ -20,6 +20,18 @@ 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. The allowed values are: + +* `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 @@ -30,7 +42,8 @@ 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." + "error": "This account needs to be approved by an administrator before it can be used.", + "approval_notice_medium": "m.email" } ``` @@ -44,7 +57,8 @@ error code. For example: ```json { "errcode": "M_USER_AWAITING_APPROVAL", - "error": "This account is pending approval by a server administrator. Please try again later." + "error": "This account is pending approval by a server administrator. Please try again later.", + "approval_notice_medium": "m.email" } ``` @@ -53,27 +67,42 @@ 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 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. +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 From 51fd1ed6e57566e138aa9099cd2e4f6e77d3d711 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 29 Sep 2022 12:39:36 +0100 Subject: [PATCH 6/6] Add missing unstable identifiers --- proposals/3866-user-not-approved-error.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/proposals/3866-user-not-approved-error.md b/proposals/3866-user-not-approved-error.md index 52fc4f7f0..34afadced 100644 --- a/proposals/3866-user-not-approved-error.md +++ b/proposals/3866-user-not-approved-error.md @@ -22,7 +22,8 @@ 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. The allowed values are: +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. @@ -116,5 +117,10 @@ them). ## Unstable prefix -During development, `ORG.MATRIX.MSC3866_USER_AWAITING_APPROVAL` must be used -instead of `M_USER_AWAITING_APPROVAL`. +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` |