MSC4323: User suspension & locking endpoints (#4323)
timedout
2 weeks ago
committed by
GitHub
parent
765af8d00f
commit
24f045ba45
@ -0,0 +1,147 @@
|
||||
# MSC4323: User suspension & locking endpoints
|
||||
|
||||
Currently the specification outlines error codes for suspended and locked users,
|
||||
even going as far as to suggest which endpoints can and cannot be executed by suspended users.
|
||||
However, it does not currently define an endpoint which server administrators can call to suspend
|
||||
and unsuspend users on their server.
|
||||
As a result, moderation tooling such as Draupnir and Meowlnir have to implement
|
||||
implementation-specific calls, which is not sustainable as more implementations other than Synapse
|
||||
integrate this feature.
|
||||
|
||||
This proposal will outline new endpoints that will allow server administrators to
|
||||
suspend, unsuspend, lock, and unlock given users.
|
||||
|
||||
## Proposal
|
||||
|
||||
> [!IMPORTANT]
|
||||
> What defines a "server administrator" is left up to the implementation itself as most already have
|
||||
> their own systems for defining administrators (e.g. Synapse has a database flag, Conduit has room
|
||||
> membership) which rarely has a reason to be exposed outside of their respective management
|
||||
> interfaces.
|
||||
|
||||
Complementing [section 10.22 (Server Administration)][p1] of the client-to-server specification,
|
||||
four new endpoints are introduced:
|
||||
|
||||
- `GET /_matrix/client/v1/admin/suspend/{userId}`
|
||||
- `PUT /_matrix/client/v1/admin/suspend/{userId}`
|
||||
- `GET /_matrix/client/v1/admin/lock/{userId}`
|
||||
- `PUT /_matrix/client/v1/admin/lock/{userId}`
|
||||
|
||||
These new endpoints are similar to [`GET /_matrix/client/v3/admin/whois/{userId}`][p2] in that they
|
||||
are clearly defined as administration endpoints, however are restricted to only permitting
|
||||
execution on local server users.
|
||||
|
||||
### New endpoint definitions
|
||||
|
||||
The response body of both the `GET` and `PUT` endpoints, as well as the request body of the
|
||||
`PUT` endpoints, are defined below. Custom properties may be used provided they utilise
|
||||
[proper namespacing][p3] in their fields.
|
||||
|
||||
**Suspend**:
|
||||
|
||||
A single key, `suspended`, with a boolean indicating if the target account is suspended:
|
||||
|
||||
```json
|
||||
{"suspended": true}
|
||||
```
|
||||
|
||||
**Lock**:
|
||||
|
||||
A single key, `locked`, with a boolean indicating if the target account is locked:
|
||||
|
||||
```json
|
||||
{"locked": false}
|
||||
```
|
||||
|
||||
### New capability definition
|
||||
|
||||
The server should advertise that these new endpoints are available for the authenticated user
|
||||
to use by including the following new capability:
|
||||
|
||||
```json5
|
||||
{
|
||||
"capabilities": {
|
||||
"m.account_moderation": {
|
||||
"suspend": true, // or false if unavailable/unimplemented
|
||||
"lock": true // or false if unavailable/unimplemented
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This allows clients to determine whether they are able to suspend/lock users on this homeserver,
|
||||
allowing them to do things like dynamically show or hide a "suspend user" button, etc.
|
||||
|
||||
The capability should not be advertised at all if both `suspend` and `lock` would be `false`.
|
||||
Omitting a key is equivalent to it being `false`.
|
||||
|
||||
### Errors and restrictions
|
||||
|
||||
Sending a request to the respective endpoints returns:
|
||||
|
||||
- `400 / M_INVALID_PARAM`: The user ID does not belong to the local server.
|
||||
- `403 / M_FORBIDDEN`: The requesting user is not a server administrator, is trying to suspend/lock
|
||||
their own account, or the target user is another administrator.
|
||||
- `404 / M_NOT_FOUND`: The user ID is not found, or is deactivated.
|
||||
|
||||
In order to prevent user enumeration, implementations have to ensure that authorization is checked
|
||||
prior to trying to do account lookups.
|
||||
As this endpoint requires authentication with an administrator account, guest access is not
|
||||
permitted. Additionally, no rate-limiting is imposed.
|
||||
|
||||
[p1]: https://spec.matrix.org/v1.15/client-server-api/#server-administration
|
||||
[p2]: https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv3adminwhoisuserid
|
||||
[p3]: https://spec.matrix.org/v1.15/appendices/#common-namespaced-identifier-grammar
|
||||
|
||||
## Potential issues
|
||||
|
||||
This proposal does not outline any metadata fields for management, such as action reasons,
|
||||
temporary actions, authors, etc, which implementation-specific methods may currently have.
|
||||
This is for the sake of brevity and simplicity, and may be expanded upon by a future proposal.
|
||||
|
||||
This proposal is also written under the assumption that all server administrators are equal, and
|
||||
cannot be suspended or locked. If a server permits such actions against a privileged user, without
|
||||
stripping their privileges, conflicting behaviours may be encountered.
|
||||
|
||||
## Alternatives
|
||||
|
||||
A full "user-info" endpoint has been suggested, which would include more information about a user's
|
||||
account that could interest server administrators. This proposal focuses solely on providing
|
||||
tooling with the capability to suspend and lock without needing to maintain several
|
||||
implementation-specific versions of their code, and adding a full-fleged user-info endpoint is
|
||||
almost entirely out of scope.
|
||||
|
||||
## Security considerations
|
||||
|
||||
Adding these new endpoints may provide a path to circumvent restrictions previously imposed on
|
||||
implementation-specific versions of the suspend and lock endpoints (such as them being blocked off
|
||||
at the reverse proxy) - server developers will likely want to ensure that their users are made
|
||||
appropriate aware of this (via release notes or some other similar high-visibility channel) so that
|
||||
they can apply those same restrictions to these new endpoints if necessary.
|
||||
|
||||
These endpoints also increase the compromise value of an administrator account, as an attacker who
|
||||
breaches one of these accounts will be able to suspend or lock other users on the server. While
|
||||
the attacker would not be able to lock out other administrators, a single-administrator homeserver
|
||||
may be vulnerable to a temporary takeover if the sole administrator account is breached and
|
||||
the deployment cannot be secured & have the change reverted quickly.
|
||||
It may possibly also allow an attacker to disable other room-level moderation tooling, such as
|
||||
moderation bots, assuming those tools are not also server administrators.
|
||||
|
||||
## Unstable prefix
|
||||
|
||||
| Stable | Unstable |
|
||||
| ------ | -------- |
|
||||
| `/_matrix/client/v1/admin/...` | `/_matrix/client/unstable/uk.timedout.msc4323/admin/...` |
|
||||
| `m.account_moderation` | `uk.timedout.msc4323` |
|
||||
|
||||
`locked` and `suspended` in the request/response bodies do not require an unstable prefix
|
||||
as the entire body is new.
|
||||
|
||||
Servers should advertise `"uk.timedout.msc4323":true` in their `/versions` response while this
|
||||
proposal is unstable in order to advertise support for this new feature.
|
||||
It is left as an implementation detail whether to require authentication to view this version flag
|
||||
or not, as the capabilities endpoint requires authentication regardless.
|
||||
|
||||
## Dependencies
|
||||
|
||||
None
|
||||
Loading…
Reference in New Issue