Merge master into MSC2342 spec
Travis Ralston
4 years ago
commit
a15fe3723d
@ -1 +1 @@
|
||||
Fix misspelling of _deprecated_.
|
||||
Fix various spelling errors throughout the specification.
|
||||
|
||||
@ -0,0 +1 @@
|
||||
Added data structures for defining moderation policies in rooms per `MSC2313 <https://github.com/matrix-org/matrix-doc/pull/2313>`_.
|
||||
@ -0,0 +1 @@
|
||||
Fix various spelling errors throughout the specification.
|
||||
@ -0,0 +1 @@
|
||||
Clarify the IV data type for encrypted files.
|
||||
@ -0,0 +1 @@
|
||||
Fix the ``.m.rule.contains_user_name`` default push rule to set the highlight tweak.
|
||||
@ -0,0 +1 @@
|
||||
Optionally invalidate other access tokens during password modification per `MSC2457 <https://github.com/matrix-org/matrix-doc/pull/2457>`_.
|
||||
@ -0,0 +1 @@
|
||||
Fix various spelling errors throughout the specification.
|
||||
@ -0,0 +1 @@
|
||||
Clarify that an ``event_id`` is returned when sending events.
|
||||
@ -0,0 +1 @@
|
||||
Add User-Interactive Authentication for SSO-backed homeserver per `MSC2454 <https://github.com/matrix-org/matrix-doc/pull/2454>`_.
|
||||
@ -0,0 +1 @@
|
||||
Remove the unused ``query_auth`` API per `MSC2451 <https://github.com/matrix-org/matrix-doc/pull/2451>`_.
|
||||
@ -0,0 +1 @@
|
||||
Fix typo in Request Authentication python example.
|
||||
@ -0,0 +1 @@
|
||||
Clarify which fields are required on the key server endpoints.
|
||||
@ -0,0 +1 @@
|
||||
Clarify the limits of ``prev_events`` and ``auth_events`` for PDUs.
|
||||
@ -0,0 +1,10 @@
|
||||
{
|
||||
"$ref": "core/state_event.json",
|
||||
"type": "m.policy.rule.room",
|
||||
"state_key": "rule:#*:example.org",
|
||||
"content": {
|
||||
"entity": "#*:example.org",
|
||||
"recommendation": "m.ban",
|
||||
"reason": "undesirable content"
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,10 @@
|
||||
{
|
||||
"$ref": "core/state_event.json",
|
||||
"type": "m.policy.rule.server",
|
||||
"state_key": "rule:*.example.org",
|
||||
"content": {
|
||||
"entity": "*.example.org",
|
||||
"recommendation": "m.ban",
|
||||
"reason": "undesirable engagement"
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,10 @@
|
||||
{
|
||||
"$ref": "core/state_event.json",
|
||||
"type": "m.policy.rule.user",
|
||||
"state_key": "rule:@alice*:example.org",
|
||||
"content": {
|
||||
"entity": "@alice*:example.org",
|
||||
"recommendation": "m.ban",
|
||||
"reason": "undesirable behaviour"
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,30 @@
|
||||
# Copyright 2020 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
properties:
|
||||
entity:
|
||||
description: |-
|
||||
The entity affected by this rule. Glob characters ``*`` and ``?`` can be used
|
||||
to match zero or more and one or more characters respectively.
|
||||
type: string
|
||||
recommendation:
|
||||
description: The suggested action to take. Currently only ``m.ban`` is specified.
|
||||
type: string
|
||||
reason:
|
||||
description: The human-readable description for the ``recommendation``.
|
||||
type: string
|
||||
type: object
|
||||
required:
|
||||
- entity
|
||||
- recommendation
|
||||
- reason
|
||||
@ -0,0 +1,15 @@
|
||||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
description: A moderation policy rule which affects room IDs and room aliases.
|
||||
properties:
|
||||
content:
|
||||
$ref: "../moderation_policy_rule.yaml"
|
||||
state_key:
|
||||
description: An arbitrary string decided upon by the sender.
|
||||
type: string
|
||||
type:
|
||||
enum:
|
||||
- m.policy.rule.room
|
||||
type: string
|
||||
type: object
|
||||
@ -0,0 +1,15 @@
|
||||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
description: A moderation policy rule which affects servers.
|
||||
properties:
|
||||
content:
|
||||
$ref: "../moderation_policy_rule.yaml"
|
||||
state_key:
|
||||
description: An arbitrary string decided upon by the sender.
|
||||
type: string
|
||||
type:
|
||||
enum:
|
||||
- m.policy.rule.server
|
||||
type: string
|
||||
type: object
|
||||
@ -0,0 +1,15 @@
|
||||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
description: A moderation policy rule which affects users.
|
||||
properties:
|
||||
content:
|
||||
$ref: "../moderation_policy_rule.yaml"
|
||||
state_key:
|
||||
description: An arbitrary string decided upon by the sender.
|
||||
type: string
|
||||
type:
|
||||
enum:
|
||||
- m.policy.rule.user
|
||||
type: string
|
||||
type: object
|
||||
@ -0,0 +1,39 @@
|
||||
# MSC2422: Allow `color` as attribute for `<font>` in messages
|
||||
|
||||
Currently the spec recommends that you to use `data-mx-color` instead of the standard
|
||||
`color` html attribute for the `<font>` tag. This is probably done to make it
|
||||
consistent with `<span>`, where you may not want to allow a generic style tag for.
|
||||
|
||||
On the other hand the /rainbow command on almost every client just uses the
|
||||
`color` attribute of the `<font>` tag. While some clients support
|
||||
`data-mx-color` (i.e. Riot Web), most clients don't. Most clients support
|
||||
rendering `color` however.
|
||||
|
||||
It would probably be for the best to allow or even prefer `color` on the
|
||||
`<font>` tag.
|
||||
|
||||
## Proposal
|
||||
|
||||
Add the `color` attribute to the allowed attributes of `<font>` in section
|
||||
13.2.1.7. No changes to the allowable values from the HTML spec are made here.
|
||||
|
||||
## Potential issues
|
||||
|
||||
- We now have a redundant attribute in the spec. While it matches what the
|
||||
clients currently do, it may be better to fix each client instead.
|
||||
- Clients may not sanitize the color attribute and will let other color values
|
||||
through, increasing compatibility issues again.
|
||||
- Clients may never support the data-mx-* attributes now.
|
||||
- Old messages could loose their color
|
||||
- This proposal doesn't touch span at all, maybe it should?
|
||||
|
||||
## Alternatives
|
||||
|
||||
- fix the clients
|
||||
-> This currently seems not feasible. Multiple clients started using color first (i.e. RiotX, Gomuks) and if it isn't spelled out explicitly in the spec, this will probably continue.
|
||||
- remove the `data-mx-color` and `data-mx-bg-color` attributes entirely, leaving us just with `color` for `<font>`
|
||||
-> This would break old messages and can be done independently of this proposal at a later date, if it is deemed useful.
|
||||
- Add a section to tell the clients to prefer `color` over `mx-data-color`
|
||||
-> I don't really know, why mx-data-* was chosen, but I assume there was a reason, so I don't want to change that.
|
||||
- Spec an entirely different format for messages (that would probably not make this proposal obsolete)
|
||||
-> This wouldn't fix the issue, where some client may choose to remove the color tag, since it is discouraged in the spec. Migration would probably also take a while, so this proposal is a quick solution, that doesn't prevent other solutions at a later date.
|
||||
@ -0,0 +1,247 @@
|
||||
# MSC2432: Updated semantics for publishing room aliases
|
||||
|
||||
This MSC offers an alternative to [MSC2260](https://github.com/matrix-org/matrix-doc/issues/2260).
|
||||
|
||||
## Background
|
||||
|
||||
The [`m.room.aliases`](https://matrix.org/docs/spec/client_server/r0.6.0#m-room-aliases)
|
||||
state event exists to list the available aliases for a given room. This serves
|
||||
two purposes:
|
||||
|
||||
* It allows existing members of the room to discover alternative aliases,
|
||||
which may be useful for them to pass this knowledge on to others trying to
|
||||
join.
|
||||
|
||||
* Secondarily, it helps to educate users about how Matrix works by
|
||||
illustrating multiple aliases per room and giving a perception of the size
|
||||
of the network.
|
||||
|
||||
However, it has problems:
|
||||
|
||||
* Any user in the entire ecosystem can create aliases for rooms, which are
|
||||
then unilaterally added to `m.room.aliases`, and room admins are unable to
|
||||
remove them. This is an abuse
|
||||
vector (https://github.com/matrix-org/matrix-doc/issues/625).
|
||||
|
||||
* For various reasons, the `m.room.aliases` event tends to get out of sync
|
||||
with the actual aliases (https://github.com/matrix-org/matrix-doc/issues/2262).
|
||||
|
||||
## Proposal
|
||||
|
||||
We propose that that room moderators should be able to manually curate a list
|
||||
of "official" aliases for their room, instead of matrix servers automatically
|
||||
publishing lists of all room aliases into the room state. No particular
|
||||
guarantees are offered that this alias list is entirely accurate: it becomes
|
||||
room moderators' responsibility to keep it so.
|
||||
|
||||
Meanwhile, the aliases that map to a given room on a given server become
|
||||
the ultimate responsibility of the administrators of that server. We give them
|
||||
tools to inspect the alias list and clean it up when necessary, in addition to
|
||||
the current tools which allow restriction of who can create aliases in the
|
||||
first place.
|
||||
|
||||
A detailed list of proposed modifications to the Matrix spec follows:
|
||||
|
||||
* `m.room.aliases` loses any special meaning within the spec. In particular:
|
||||
|
||||
* Clients should no longer format it specially in room timelines.
|
||||
|
||||
* Clients and servers should no longer consider `m.room.aliases` when
|
||||
[calculating the display name for a
|
||||
room](https://matrix.org/docs/spec/client_server/r0.6.0#calculating-the-display-name-for-a-room).
|
||||
|
||||
(Note: servers follow the room display-name algorithm when calculating
|
||||
room names for certain types of push notification.)
|
||||
|
||||
* A future room version will remove the special [authorization
|
||||
rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules) and
|
||||
[redaction rules](https://matrix.org/docs/spec/client_server/r0.6.0#redactions).
|
||||
|
||||
* [`m.room.canonical_alias`](https://matrix.org/docs/spec/client_server/r0.6.0#m-room-canonical-alias)
|
||||
is extended to include a new `alt_aliases` property. This, if present,
|
||||
should be a list of alternative aliases for the room. An example event might
|
||||
look like:
|
||||
|
||||
```json
|
||||
{
|
||||
"content": {
|
||||
"alias": "#somewhere:localhost",
|
||||
"alt_aliases": [
|
||||
"#somewhere:overthere.com",
|
||||
"#somewhereelse:example.com"
|
||||
]
|
||||
},
|
||||
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
|
||||
"state_key": "",
|
||||
"type": "m.room.canonical_alias"
|
||||
}
|
||||
```
|
||||
|
||||
It is valid for `alt_aliases` to be non-empty even if `alias` is absent or
|
||||
empty. This means that no alias has been picked out as the 'main' alias.
|
||||
|
||||
(Note: although the spec currently claims that `alias` is mandatory, Synapse
|
||||
generates `m.room.canonical_alias` events with no `alias` property when the
|
||||
main alias is deleted. This change would legitimise that behaviour.)
|
||||
|
||||
(For clarity: it is not proposed that the `alt_aliases` be considered when
|
||||
calculating the displayname for a room.)
|
||||
|
||||
* [`PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}`](https://matrix.org/docs/spec/client_server/r0.6.0#put-matrix-client-r0-rooms-roomid-state-eventtype-statekey)
|
||||
is extended to recommend that servers validate any *new* aliases added to
|
||||
`m.room.canonical_alias` by checking that it is a valid alias according to
|
||||
the [syntax](https://matrix.org/docs/spec/appendices#room-aliases), and by
|
||||
looking up the alias and and that it corresponds to the expected room ID.
|
||||
|
||||
(Note: Synapse currently implements this check on the main alias, though
|
||||
this is unspecced.)
|
||||
|
||||
The following error codes are specified:
|
||||
|
||||
* HTTP 400, with `errcode: M_INVALID_PARAMETER` if an attempt is made to add
|
||||
an entry which is not a well-formed alias (examples: too long, doesn't
|
||||
start with `#`, doesn't contain a `:`).
|
||||
|
||||
* HTTP 400, with `errcode: M_BAD_ALIAS` if an added alias does not point at
|
||||
the given room (either because the alias doesn't exist, because it can't
|
||||
be resolved due to an unreachable server, or because the alias points at a
|
||||
different room).
|
||||
|
||||
* Currently, [`PUT /_matrix/client/r0/directory/room/{roomAlias}`](https://matrix.org/docs/spec/client_server/r0.6.0#put-matrix-client-r0-directory-room-roomalias)
|
||||
attempts to send updated `m.room.aliases` events on the caller's
|
||||
behalf. (This is implemented in Synapse but does not appear to be explicitly
|
||||
specced.) This functionality should be removed.
|
||||
|
||||
* Currently, [`DELETE /_matrix/client/r0/directory/room/{roomAlias}`](https://matrix.org/docs/spec/client_server/r0.6.0#delete-matrix-client-r0-directory-room-roomalias),
|
||||
attempts to send updated `m.room.aliases` and/or `m.room.canonical_alias`
|
||||
events on the caller's behalf, removing any aliases which have been
|
||||
deleted. (Again, this is implemented in Synapse but does not appear to be
|
||||
explicitly specced.) The `m.room.aliases` functionality should be removed,
|
||||
and the `m.room.canonical_alias` functionality should be extended to cover
|
||||
`alt_aliases`.
|
||||
|
||||
The behaviour if the calling user has permission to delete the alias but
|
||||
does not have permission to send `m.room.canonical_alias` events in the room
|
||||
(for example, by virtue of being a "server administrator", or by being the
|
||||
user that created the alias) is implementation-defined. It is *recommended*
|
||||
that in this case, the alias is deleted anyway, and a successful response is
|
||||
returned to the client.
|
||||
|
||||
* A new api endpoint, `GET /_matrix/client/r0/rooms/{roomId}/aliases` is
|
||||
added, which returns the list of aliases currently defined on the local
|
||||
server for the given room. The response looks like:
|
||||
|
||||
```json
|
||||
{
|
||||
"aliases": [
|
||||
"#somewhere:example.com",
|
||||
"#somewhereelse:example.com",
|
||||
"#special_alias:example.com"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This API can be called by any current member of the room (calls from other
|
||||
users result in `M_FORBIDDEN`). For rooms with `history_visibility` set to
|
||||
`world_readable`, it can also be called by users outside the room.
|
||||
|
||||
Servers might also choose to allow access to other users such as server
|
||||
administrators.
|
||||
|
||||
Various APIs are currently subject to implementation-defined access
|
||||
restrictions. No change to the specification is introduced in this regard
|
||||
(implementations will continue to be free to impose their own
|
||||
restrictions). Nevertheless as part of this MSC it is useful to consider some
|
||||
proposed changes to Synapse's implementation:
|
||||
|
||||
* No change: `PUT /_matrix/client/r0/directory/room/{roomAlias}`: Synapse
|
||||
only allows access to current members of the room, and also exposes some
|
||||
configuration options which allow restriction of which users are allowed to
|
||||
create aliases in general.
|
||||
|
||||
* `DELETE /_matrix/client/r0/directory/room/{roomAlias}`: in this case,
|
||||
currently Synapse restricts its use to the user that created the alias, and
|
||||
server admins.
|
||||
|
||||
It is proposed to extend this to local users who have a power-level
|
||||
sufficient to send an `m.room.canonical_alias` event in the room that the
|
||||
alias currently points to.
|
||||
|
||||
* [`PUT /_matrix/client/r0/directory/list/room/{roomId}`](https://matrix.org/docs/spec/client_server/r0.6.0#put-matrix-client-r0-directory-list-room-roomid)
|
||||
and the corresponding unspecced `DELETE` api (both of which set the
|
||||
visibility of a room in the public directory): currently Synapse restricts
|
||||
their use to server admins and local users who have a PL sufficient to send
|
||||
an `m.room.aliases` event in the room (ignoring the special auth
|
||||
rules). This will be changed to check against the PL required to send an
|
||||
`m.room.canonical_alias` event.
|
||||
|
||||
It is envisaged that Matrix clients will then change their "Room Settings" user
|
||||
interface to display the aliases from `m.room.canonical_alias` instead of those
|
||||
in `m.room.aliases`, as well as giving moderators the ability to update that
|
||||
list. Clients might also wish to use the new `GET
|
||||
/_matrix/client/r0/rooms/{roomId}/aliases` endpoint to obtain and display the
|
||||
currently-available local aliases, though given that this list may be subject
|
||||
to abuse, it should probably not be shown by default.
|
||||
|
||||
### Future work
|
||||
|
||||
This work isn't considered part of this MSC, but rather a potential extension
|
||||
for the future.
|
||||
|
||||
* It may be useful to be able to query remote servers for their alias
|
||||
list. This could be done by extending `GET
|
||||
/_matrix/client/r0/rooms/{roomId}/aliases` to take a `server_name`
|
||||
parameter, and defining an API in the server_server spec which will expose
|
||||
the requested information, subject to the calling homeserver having at least
|
||||
one user with a right to see it.
|
||||
|
||||
* Similarly, room moderators may wish to be able to delete aliases on a remote
|
||||
server for their room. We could envisage a federation API which allows such
|
||||
a request to be made, subject to the calling homeserver having at least one
|
||||
moderator in the room.
|
||||
|
||||
## Potential issues
|
||||
|
||||
The biggest problem with this proposal is that existing clients, which rely on
|
||||
`m.room.aliases` in one way or another, will lose functionality. In particular,
|
||||
they may not know about aliases that exist, or they may look at outdated
|
||||
`m.room.aliases` events that list aliases that no longer exist. However, since
|
||||
`m.room.aliases` is best-effort anyway, these are both problems that exist to
|
||||
some extent today.
|
||||
|
||||
## Alternatives
|
||||
|
||||
We considered continuing to use `m.room.aliases` to advertise room aliases
|
||||
instead of `m.room.canonical_alias`, but the significant changes in semantics
|
||||
made that seem inappropriate.
|
||||
|
||||
We also considered using separate state events for each advertised alias,
|
||||
rather than listing them all in one event. This might increase the number of
|
||||
aliases which can be advertised, and help to reduce races when editing the
|
||||
list. However, the 64KB limit of an event still allows room for hundreds of
|
||||
aliases of any sane length, and we don't expect the list to be changing
|
||||
frequently enough for races to be a practical concern. Ultimately the added
|
||||
complexity seemed redundant.
|
||||
|
||||
A previous suggestion was
|
||||
[MSC2260](https://github.com/matrix-org/matrix-doc/issues/2260), which proposed
|
||||
keeping `m.room.aliases` largely as-is, but giving room moderators tools to
|
||||
control who can send them via room power-levels. We dismissed it for the
|
||||
reasons set out at
|
||||
https://github.com/matrix-org/matrix-doc/pull/2260#issuecomment-584207073.
|
||||
|
||||
## Security considerations
|
||||
|
||||
None currently identified.
|
||||
|
||||
## Unstable prefix
|
||||
|
||||
While this feature is in development, the following names will be in use:
|
||||
|
||||
| Proposed final name | Name while in development |
|
||||
| --- | --- |
|
||||
| `GET /_matrix/client/r0/rooms/{roomId}/aliases` | `GET /_matrix/client/unstable/org.matrix.msc2432/rooms/{roomId}/aliases` |
|
||||
|
||||
Servers will indicate support for the new endpoint via a non-empty value for feature flag
|
||||
`org.matrix.msc2432` in `unstable_features` in the response to `GET
|
||||
/_matrix/client/versions`.
|
||||
@ -0,0 +1,56 @@
|
||||
# MSC2451: Remove the `query_auth` federation endpoint
|
||||
|
||||
This API was added without sufficient thought nor testing. The endpoint isn't
|
||||
used in any known implementations, and we do not believe it to be necessary
|
||||
for federation to work. The only known implementation (in Synapse) was not fully
|
||||
fleshed out and is broken.
|
||||
|
||||
For background, the idea behind this endpoint was that two homeservers would be
|
||||
able to share state events with the hope of filling in missing state from one
|
||||
of homeservers allowing state resolution to complete. This was to protect
|
||||
against a joining server not providing the full (or providing stale) state.
|
||||
|
||||
In addition to the ideas above not coming to fruition, it is unclear whether the
|
||||
current design of this endpoint would be sufficient. If this state negotiation
|
||||
feature is needed in the future it should be redesigned from scratch via the MSC
|
||||
proposal process.
|
||||
|
||||
## Proposal
|
||||
|
||||
Remove the following endpoint:
|
||||
|
||||
* [POST `/_matrix/federation/v1/query_auth/{roomId}/{eventId}`](https://matrix.org/docs/spec/server_server/r0.1.3#post-matrix-federation-v1-query-auth-roomid-eventid)
|
||||
|
||||
## Potential issues
|
||||
|
||||
Removing this endpoint impacts backwards compatibility, in practice removing
|
||||
this endpoint should have minimal impact as it was an unused error path in
|
||||
Synapse. The federation client code to call this endpoint was removed in Synapse
|
||||
v1.5.0rc1.
|
||||
|
||||
There is no evidence of other homeserver implementations having implemented this
|
||||
endpoint.
|
||||
|
||||
### History
|
||||
|
||||
This endpoint (and the federation client code) to call it was initially
|
||||
added in Synapse v0.7.0 (see [#43](https://github.com/matrix-org/synapse/pull/43)).
|
||||
The federation client code was heavily modified for v1.0.0rc1 (see
|
||||
[#5227](https://github.com/matrix-org/synapse/pull/5227/)),
|
||||
|
||||
The federation client code to call this endpoint was removed in v1.5.0rc1 of
|
||||
Synapse (see [#6214](https://github.com/matrix-org/synapse/pull/6214). After
|
||||
that point this endpoint is not called).
|
||||
|
||||
During removal it was noted that the code to call this endpoint was already
|
||||
unreachable. It seems that this code was never reachable and was meant for an
|
||||
error situation which was never built out (see `git log -S NOT_ANCESTOR`, the
|
||||
error condition is never assigned).
|
||||
|
||||
## Alternatives
|
||||
|
||||
The endpoint could be deprecated and removed in a future version of the specification.
|
||||
|
||||
## Security considerations
|
||||
|
||||
None.
|
||||
@ -0,0 +1,230 @@
|
||||
# User-Interactive Authentication for SSO-backed homeserver
|
||||
|
||||
Certain endpoints, such as `DELETE /_matrix/client/r0/devices/{deviceId}` and
|
||||
`POST /_matrix/client/r0/account/3pid/add`, require the user to reconfirm their
|
||||
identity, as a guard against a leaked access token being used to take over an
|
||||
entire account.
|
||||
|
||||
On a normal homeserver, this is done by prompting the user to enter their
|
||||
password. However, on a homeserver where users authenticate via a single-sign-on
|
||||
system, the user doesn't have a password registered with the homeserver. Instead
|
||||
we need to delegate that check to the SSO system.
|
||||
|
||||
At the protocol level, this means adding support for SSO to the
|
||||
[user-interactive authentication API](https://matrix.org/docs/spec/client_server/r0.6.0#user-interactive-authentication-api).
|
||||
|
||||
In theory, once SSO is added as a possible flow for authentication, any clients
|
||||
that already implement the [fallback process for unknown authentication types](https://matrix.org/docs/spec/client_server/r0.6.0#fallback)
|
||||
will work fine without modification. It is unknown whether this is widely
|
||||
supported among clients.
|
||||
|
||||
## Proposal
|
||||
|
||||
An [additional authentication type](https://matrix.org/docs/spec/client_server/r0.6.0#authentication-types)
|
||||
of `m.login.sso` is added to the user-interactive authentication specification.
|
||||
|
||||
There are no additional parameters as part of this authentication type. As per
|
||||
the user-interactive authentication specification, the only parameter included in
|
||||
the `auth` dictionary should be the session ID from the homeserver, e.g.:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"session": "<session ID>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Detailed fallback authentication flow:
|
||||
|
||||
The following is a re-iteration of the [fallback authentication flow](https://matrix.org/docs/spec/client_server/r0.6.0#fallback),
|
||||
but with details filled in for the proposed new authentication type.
|
||||
|
||||
When choosing this authentication flow, the following should occur:
|
||||
|
||||
1. If the client wants to complete authentication using SSO, it opens a browser
|
||||
window for `/_matrix/client/r0/auth/m.login.sso/fallback/web?session=<...>`
|
||||
with session set to the UI-Auth session id (from the "auth" dict).
|
||||
|
||||
The homeserver returns a page which asks for the user's confirmation before
|
||||
proceeding. See the security considerations section below for why this is
|
||||
necessary. For example, the page could say words to the effect of:
|
||||
|
||||
> A client is trying to remove a device/add an email address/take over your
|
||||
> account. To confirm this action, **re-authenticate with single sign-on**.
|
||||
> If you did not expect this, your account may be compromised!
|
||||
2. The link, once the user clicks on it, goes to the SSO provider's page.
|
||||
3. The SSO provider validates the user, and redirects the browser back to the
|
||||
homeserver.
|
||||
4. The homeserver validates the response from the SSO provider, updates the
|
||||
user-interactive auth session to show that the SSO has completed, and
|
||||
[serves the fallback auth completion page as specced](https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
|
||||
5. The client resubmits its original request, with its original session id,
|
||||
which now should complete.
|
||||
|
||||
Note that the post-SSO URL on the homeserver is left up to the homeserver
|
||||
implementation rather than forming part of the specification, choices might be
|
||||
limited by the chosen SSO implementation, for example:
|
||||
|
||||
* SAML2 servers typically only support one URL per service provider, so in
|
||||
practice it will need to be the same as that already used for the login flow
|
||||
(for synapse, it's `/_matrix/saml2/authn_response`) - and the server needs to
|
||||
be able to figure out if it's doing SSO for a login attempt or an SSO
|
||||
attempt.
|
||||
* CAS doesn't have the same restriction.
|
||||
|
||||
### Example flow:
|
||||
|
||||
A more complete example is provided below in which a user attempts to delete
|
||||
a device and is pushed into the user interactive authentication process with
|
||||
SSO being the only possible flow.
|
||||
|
||||
0. Client submits the request, which the server says requires SSO:
|
||||
|
||||
```
|
||||
POST /_matrix/client/r0/delete_devices HTTP/1.1
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer xyzzy
|
||||
|
||||
{
|
||||
"devices": ["FSVVTZRRAA"]
|
||||
}
|
||||
|
||||
HTTP/1.1 401 Unauthorized
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"flows": [
|
||||
{
|
||||
"stages": [
|
||||
"m.login.sso"
|
||||
]
|
||||
}
|
||||
],
|
||||
"params": {},
|
||||
"session": "dTKfsLHSAJeAhqfxUsvrIVJd"
|
||||
}
|
||||
```
|
||||
|
||||
1. Client opens a browser window for the fallback endpoint:
|
||||
|
||||
```
|
||||
GET /_matrix/client/r0/auth/m.login.sso/fallback/web
|
||||
?session=dTKfsLHSAJeAhqfxUsvrIVJd HTTP/1.1
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
<body>
|
||||
A client is trying to remove a device from your account. To confirm this
|
||||
action, <a href="https://sso_provider/validate?SAMLRequest=...">re-authenticate with single sign-on</a>.
|
||||
If you did not expect this, your account may be compromised!
|
||||
</body>
|
||||
```
|
||||
|
||||
2. The user clicks the confirmation link which goes to the SSO provider's site:
|
||||
|
||||
```
|
||||
GET https://sso_provider/validate?SAMLRequest=<etc> HTTP/1.1
|
||||
|
||||
<SAML/CAS or other SSO data>
|
||||
```
|
||||
|
||||
3. The SSO provider validates the user and ends up redirecting the browser back
|
||||
to the homeserver. The example below shows a 302 for simplicity, this might
|
||||
vary based on SSO implementation.
|
||||
|
||||
```
|
||||
HTTP/1.1 302 Moved
|
||||
Location: https://homeserver/_matrix/saml2/authn_response?
|
||||
SAMLResponse=<etc>
|
||||
```
|
||||
|
||||
4. The browser sends the SSO response to the homeserver, which validates it and
|
||||
shows the fallback auth completion page:
|
||||
|
||||
```
|
||||
GET /_matrix/saml2/authn_response?SAMLResponse=<etc>
|
||||
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
<script>
|
||||
if (window.onAuthDone) {
|
||||
window.onAuthDone();
|
||||
} else if (window.opener && window.opener.postMessage) {
|
||||
window.opener.postMessage("authDone", "*");
|
||||
}
|
||||
</script>
|
||||
|
||||
<p>Thank you.</p>
|
||||
<p>You may now close this window and return to the application.</p>
|
||||
```
|
||||
|
||||
5. The client closes the browser popup if it is still open, and resubmits its
|
||||
original request, which now succeeds:
|
||||
|
||||
```
|
||||
POST /_matrix/client/r0/delete_devices HTTP/1.1
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer xyzzy
|
||||
|
||||
{
|
||||
"auth": {
|
||||
"session": "dTKfsLHSAJeAhqfxUsvrIVJd"
|
||||
}
|
||||
}
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
## Alternatives
|
||||
|
||||
An alternative client flow where the fallback auth ends up redirecting to a
|
||||
given URI, instead of doing JavaScript `postMessage` foo could be considered.
|
||||
This is probably an orthogonal change to the fallback auth though.
|
||||
|
||||
## Security considerations
|
||||
|
||||
### Why we need user to confirm before the SSO flow
|
||||
|
||||
Recall that the thing we are trying to guard against here is a single leaked
|
||||
access-token being used to take over an entire account. So let's assume the
|
||||
attacker has got hold of an access token for your account. What happens if the
|
||||
confirmation step is skipped?
|
||||
|
||||
The attacker, who has your access token, starts a UI Authentication session to
|
||||
add their email address to your account.
|
||||
|
||||
They then sends you a link "hey, check out this cool video!"; the link leads (via
|
||||
an innocent-looking URL shortener or some other phishing technique) to
|
||||
`/_matrix/client/r0/auth/m.login.sso/fallback/web?session=<...>`, with the ID of
|
||||
the session that he just created.
|
||||
|
||||
Since there is no confirmation step, the server redirects directly to the SSO
|
||||
provider.
|
||||
|
||||
It's common for SSO providers to redirect straight back to the app if you've
|
||||
recently authenticated with them; even in the best case, the SSO provider shows
|
||||
an innocent message along the lines of "Confirm that you want to sign in to
|
||||
\<your Matrix homeserver>".
|
||||
|
||||
After redirecting back to the homeserver, the SSO is completed and the
|
||||
attacker's session is validated. They are now able to make their malicious
|
||||
change to your account.
|
||||
|
||||
This problem can be mitigated by clearly telling the user what is about to happen.
|
||||
|
||||
### Reusing User Interactive Authentication sessions
|
||||
|
||||
The security of this relies on User Interactive Authentication sessions only
|
||||
being used for the same request as they were initiated for. This security is not
|
||||
only a concern for the proposed SSO authentication type. It is not believed
|
||||
that this is currently enforced in implementations.
|
||||
|
||||
## Unstable prefix
|
||||
|
||||
A vendor prefix of `org.matrix.login.sso` is proposed (instead of `m.login.sso`)
|
||||
until this is part of the specification.
|
||||
@ -0,0 +1,56 @@
|
||||
# Invalidating devices during password modification
|
||||
|
||||
There are multiple use cases for why a user might want to modify their password:
|
||||
|
||||
* Adopting a password manager (to use a unique password or more secure password).
|
||||
* Password rotation.
|
||||
* Re-secure a compromised account.
|
||||
* ... probably tons of others ...
|
||||
|
||||
These can be summarized into two groups:
|
||||
|
||||
1. "My account has been compromised and I need to re-secure it."
|
||||
2. "I just want to change my password."
|
||||
|
||||
The [current Matrix specification](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-account-password)
|
||||
does not provide a way to differentiate between these use cases. It currently
|
||||
specifies behavior that fits well into the first use-case above: that the
|
||||
sessions except the current session should be revoked.
|
||||
|
||||
It is reasonable for a client to want to specify this behavior to offer two
|
||||
different workflows:
|
||||
|
||||
1. Modify a password and log all other devices out (for use when an account has
|
||||
been compromised).
|
||||
2. Modify a password and do not touch any session data (for use in a
|
||||
non-malicious situations).
|
||||
|
||||
Alternately a client may default to whichever workflow is best for their users.
|
||||
|
||||
## Proposal
|
||||
|
||||
An optional field is added to the JSON body of the [password reset endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-account-password)
|
||||
called `logout_devices`. This is a boolean flag (defaulting to `true`) that
|
||||
signals to whether other devices and sessions should be invalidated after
|
||||
modifying the password.
|
||||
|
||||
## Potential issues
|
||||
|
||||
The specification states:
|
||||
|
||||
> The homeserver SHOULD NOT revoke the access token provided in the request,
|
||||
> however all other access tokens for the user should be revoked if the request
|
||||
> succeeds.
|
||||
|
||||
Defaulting `logout_devices` to `true` should be backwards compatible.
|
||||
|
||||
## Alternatives
|
||||
|
||||
A new endpoint could be provided in a future version of the specification that
|
||||
supports an additional field (as described above).
|
||||
|
||||
## Security considerations
|
||||
|
||||
By defaulting to invalidating devices and sessions the security considerations
|
||||
of this endpoint should remain intact. A client will need to be modified to
|
||||
choose to keep other devices active.
|
||||
@ -0,0 +1,128 @@
|
||||
.. Copyright 2020 The Matrix.org Foundation C.I.C.
|
||||
..
|
||||
.. Licensed under the Apache License, Version 2.0 (the "License");
|
||||
.. you may not use this file except in compliance with the License.
|
||||
.. You may obtain a copy of the License at
|
||||
..
|
||||
.. http://www.apache.org/licenses/LICENSE-2.0
|
||||
..
|
||||
.. Unless required by applicable law or agreed to in writing, software
|
||||
.. distributed under the License is distributed on an "AS IS" BASIS,
|
||||
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
.. See the License for the specific language governing permissions and
|
||||
.. limitations under the License.
|
||||
|
||||
Moderation policy lists
|
||||
=======================
|
||||
|
||||
.. _module:moderation-policies:
|
||||
|
||||
With Matrix being an open network where anyone can participate, a very wide
|
||||
range of content exists and it is important that users are empowered to select
|
||||
which content they wish to see, and which content they wish to block. By
|
||||
extension, room moderators and server admins should also be able to select
|
||||
which content they do not wish to host in their rooms and servers.
|
||||
|
||||
The protocol's position on this is one of neutrality: it should not be deciding
|
||||
what content is undesirable for any particular entity and should instead be
|
||||
empowering those entities to make their own decisions. As such, a generic
|
||||
framework for communicating "moderation policy lists" or "moderation policy rooms"
|
||||
is described. Note that this module only describes the data structures and not
|
||||
how they should be interpreting: the entity making the decisions on filtering
|
||||
is best positioned to interpret the rules how it sees fit.
|
||||
|
||||
Moderation policy lists are stored as room state events. There are no restrictions
|
||||
on how the rooms can be configured (they could be public, private, encrypted, etc).
|
||||
|
||||
There are currently 3 kinds of entities which can be affected by rules: ``user``,
|
||||
``server``, and ``room``. All 3 are described with ``m.policy.rule.<kind>`` state
|
||||
events. The ``state_key`` for a policy rule is an arbitrary string decided by the
|
||||
sender of the rule.
|
||||
|
||||
Rules contain recommendations and reasons for the rule existing. The ``reason``
|
||||
is a human-readable string which describes the ``recommendation``. Currently only
|
||||
one recommendation, ``m.ban``, is specified.
|
||||
|
||||
``m.ban`` recommendation
|
||||
------------------------
|
||||
|
||||
When this recommendation is used, the entities affected by the rule should be
|
||||
banned from participation where possible. The enforcement of this is deliberately
|
||||
left as an implementation detail to avoid the protocol imposing its opinion on how
|
||||
the policy list is to be interpreted. However, a suggestion for a simple implementation
|
||||
is as follows:
|
||||
|
||||
* Is a ``user`` rule...
|
||||
|
||||
* Applied to a user: The user should be added to the subscriber's ignore list.
|
||||
* Applied to a room: The user should be banned from the room (either on sight or immediately).
|
||||
* Applied to a server: The user should not be allowed to send invites to users on the server.
|
||||
|
||||
* Is a ``room`` rule...
|
||||
|
||||
* Applied to a user: The user should leave the room and not join it
|
||||
(`MSC2270 <https://github.com/matrix-org/matrix-doc/pull/2270>`_-style ignore).
|
||||
* Applied to a room: No-op because a room cannot ban itself.
|
||||
* Applied to a server: The server should prevent users from joining the room and from receiving
|
||||
invites to it.
|
||||
|
||||
* Is a ``server`` rule...
|
||||
|
||||
* Applied to a user: The user should not receive events or invites from the server.
|
||||
* Applied to a room: The server is added as a denied server in the ACLs.
|
||||
* Applied to a server: The subscriber should avoid federating with the server as much as
|
||||
possible by blocking invites from the server and not sending traffic unless strictly
|
||||
required (no outbound invites).
|
||||
|
||||
Subscribing to policy lists
|
||||
---------------------------
|
||||
|
||||
This is deliberatly left as an implementation detail. For implementations using the
|
||||
Client-Server API, this could be as easy as joining or peeking the room. Joining or peeking
|
||||
is not required, however: an implementation could poll for updates or use a different
|
||||
technique for receiving updates to the policy's rules.
|
||||
|
||||
Sharing
|
||||
-------
|
||||
|
||||
In addition to sharing a direct reference to the room which contains the policy's rules,
|
||||
plain http or https URLs can be used to share links to the list. When the URL is approached
|
||||
with a ``Accept: application/json`` header or has ``.json`` appended to the end of the URL, it
|
||||
should return a JSON object containing a ``room_uri`` property which references the room.
|
||||
Currently this would be a ``matrix.to`` URI, however in future it could be a Matrix-schemed
|
||||
URI instead. When not approached with the intent of JSON, the service could return a
|
||||
user-friendly page describing what is included in the ban list.
|
||||
|
||||
Events
|
||||
------
|
||||
|
||||
The ``entity`` described by the state events can contain ``*`` and ``?`` to match zero or more
|
||||
and one or more characters respectively. Note that rules against rooms can describe a room ID
|
||||
or room alias - the subscriber is responsible for resolving the alias to a room ID if desired.
|
||||
|
||||
{{m_policy_rule_user_event}}
|
||||
|
||||
{{m_policy_rule_room_event}}
|
||||
|
||||
{{m_policy_rule_server_event}}
|
||||
|
||||
Client behaviour
|
||||
----------------
|
||||
As described above, the client behaviour is deliberatly left undefined.
|
||||
|
||||
Server behaviour
|
||||
----------------
|
||||
Servers have no additional requirements placed on them by this module.
|
||||
|
||||
Security considerations
|
||||
-----------------------
|
||||
This module could be used to build a system of shared blacklists, which may create
|
||||
a divide within established communities if not carefully deployed. This may well not
|
||||
be a suitable solution for all communities.
|
||||
|
||||
Depending on how implementations handle subscriptions, user IDs may be linked to
|
||||
policy lists and therefore expose the views of that user. For example, a client implementation
|
||||
which joins the user to the policy room would expose the user's ID to observers of the
|
||||
policy room. In future, `MSC1228 <https://github.com/matrix-org/matrix-doc/pulls/1228>`_
|
||||
and `MSC1777 <https://github.com/matrix-org/matrix-doc/pulls/1777>`_ (or similar) could
|
||||
help solve this concern.
|
||||
Loading…
Reference in New Issue