Merge branch 'm.org-master' into rav/proposal/cs_api_in_login

pull/977/head
Travis Ralston 6 years ago
commit 828e3f83bd

@ -101,6 +101,11 @@ paths:
"room_id": "!d41d8cd:matrix.org"}
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required: ["room_id"]
403:
description: |-
You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
@ -208,6 +213,11 @@ paths:
"room_id": "!d41d8cd:matrix.org"}
schema:
type: object
properties:
room_id:
type: string
description: The joined room ID.
required: ["room_id"]
403:
description: |-
You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:

@ -0,0 +1,45 @@
# Soft Remote Logout Proposal
## Motivation
Currently when a user logs out of riot, the app will destroy things like
encryption keys. If the logout was done by the user in local app then it will
have first prompted the user to export the encryption keys. However, when the
app is logged out remotely (i.e. it received a 401 from the server) there is no
opportunity to ask the user to backup the keys, resulting in those keys being
lost.
While this behaviour is useful in many circumstances, e.g. remote logging out a
stolen/lost device, it also means that the server shouldn't automatically
log out devices, to avoid users losing encryption keys.
## Proposal
A new parameter is added to the JSON body of 401 responses, called
`soft_logout`. This is a boolean flag (defaulting to `false`) that signals to
the client whether it should keep local data and simply prompt to reauth (when
`true`) or to destroy the current data like it does today (when `false`).
The major disadvantage with this approach is that once the client is logged
out, the user can no longer remotely cause the client to destroy the local
data. However, this is not substantially different from today where the app has
to be opened to receive remote logout requests (via 401), as it allows
attackers to get at encryption keys even after remote logout if they simply
avoid opening the app.
### Example Client UX
When handling a soft logout the client could show a "re-login" dialogue, rather
than back to the default logged out screen. This new dialogue would then have
several options including logging out, exporting keys and logging out fully.
## Alternatives
One alternative is to force the user to enter a password for backing up keys
when they enter the app, and then have the app keep secure backups of they
keys. This then means its safer to not delete the secure backups when the app
is logged out remotely.

@ -0,0 +1,32 @@
# MSC1721: Rename `m.login.cas` to `m.login.sso`
The Matrix Client-Server spec includes a [section on client login using Central
Authentication Service
(CAS)](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login).
The spec currently fails to mention it, but this process is triggered when [`GET
/login`](https://matrix.org/docs/spec/client_server/r0.4.0.html#get-matrix-client-r0-login)
returns a flow type of `m.login.cas`.
Nothing in this flow is specific to CAS - it is equally applicable for other
web-based single-sign-on processes, such as SAML.
Accordingly, we should rename `cas` to `sso`.
## Proposal
1. `m.login.sso` should be defined as a valid login type for return from `GET
/login`. (We should probably mention `m.login.cas` in the spec while we are
there.)
2. When a client wishes to use the SSO login type, it should redirect to
`/_matrix/client/r0/login/sso/redirect` (instead of
`/_matrix/client/r0/login/cas/redirect`).
3. Servers should treat `/_matrix/client/r0/login/sso/redirect` identically to
`/_matrix/client/r0/login/cas/redirect`: they should issue a redirect to
their configured single-sign-on system.
4. Servers which support `m.login.sso` should make sure they update their [login
fallback page](https://matrix.org/docs/spec/client_server/r0.4.0.html#login-fallback)
to understand the new login type.

@ -1,152 +0,0 @@
# MSC1730: Mechanism for redirecting to an alternative server during login
## Background/requirements
This is a proposal for a mechanism for handling the following situation.
A large, loosely-coupled organisation wants its members to be able to
communicate with one another via Matrix. The organisation consists of several
departments which are cooperative but prefer to host their own infrastructure.
The organisation has an existing single-sign-on system which covers the entire
organisation, and which they would like their members to use when
authenticating to the Matrix system.
## Proposal
The response to `POST /_matrix/client/r0/login` currently includes the fields
`user_id`, `access_token`, `device_id`, and the deprecated `home_server`.
We will add to this the the field `well_known`, which has the same format as
the [`/.well-known/matrix/client`
object](https://matrix.org/docs/spec/client_server/r0.4.0.html#get-well-known-matrix-client).
Servers MAY add this field to the login response if they wish to redirect
clients to an alternative homeserver after login. Clients SHOULD use the
provided `well_known` object to reconfigure themselves, optionally validating the
URLs within.
## Application
Let's imagine for this description that our organisation is the University of
Canadialand, which is divided into departments including Engineering, History,
Physics, and so on.
Central University IT currently host a SAML2-based single-sign-on system, which
asks users to select their department, and then defers to the departmental
authentication system to authenticate them. Note that the users do not have a
globally-unique identifier.
University IT now sets up a Matrix Homeserver instance, which they host at
`https://matrix.ac.cdl`. They run a publicity campaign encouraging university
members to use the service by configuring off-the-shelf Matrix clients to use
the homeserver at `https://matrix.ac.cdl`. They may also release customised
clients configured to use that URL by default.
However, the departments actually want to host their own homeservers; these
might be at `https://matrix.eng.ac.cdl`, `https://matrix.hist.ac.cdl`, etc. The
central IT homeserver therefore redirects clients to the departmental
homeserver after login.
A complete login flow is as shown in the following sequence diagram:
![Sequence diagram](images/1730-seq-diagram.1.svg)
Note that this flow is complicated by the out-of-band SAML2 authentication. We
envisage that a similar technique could also be used for a standard
username/password authentication, however.
## Rejected solutions
Alternative solutions might include:
### Have all users on one homeserver
In many situtations, it might be more appropriate to have a single homeserver,
so users' MXids would look like `@user:ac.cdl` instead of
`@user:eng.ac.cdl`.
However, there are circumstances where separate homeservers are required:
* the departments may be only very loosely related
* the departments may have privacy concerns
* the dpeartments may be geographically distributed with slow or unreliable
links to the central system
* load-balancing may be essential.
### Tell users the C-S API for their home homeserver
We could tell Engineering users to configure their clients with
`https://matrix.eng.ac.cdl`, History users to use `https://matrix.hist.ac.cdl`,
etc.
The problems with this are:
* Each department must issue its own documentation and publicity advising how
to configure a Matrix client
* It becomes impractical to distribute preconfigured clients.
### Proxy all C-S endpoints
It would be possible for the the central homeserver to proxy all C-S
interaction, as well as `/login`, directing requests to the right server for
the user.
This is unsatisfactory due to the additional latency imposed, the load on the
central homeserver, and the fact that it makes the central server a single
point of failure for the entire system.
### Require clients to perform a .well-known lookup after login
We could require clients to do a .well-known lookup on the domain of their MXID
once they have discovered it from the `/login` response.
This has the following problems:
* In most cases this `.well-known` lookup will be entirely redundant. It adds
latency and overhead, and complicates client implementations.
* It complicates deployment, since each department has to host a `.well-known`
file at their root domain.
### Add an alternative redirection mechanism in the login flow
We could specify that the `/login` response could contain a `redirect` field
property instead of the existing `user_id`/`access_token`/`device_id`
properties. The `redirect` property would give the C-S API of the target
HS. The client would then repeat its `/login` request, and use the specified
endpoint for all future C-S interaction.
This approach would complicate client implementations.
### Modify the single-sign-on flow
It would be possible to modify the single-sign-on flow to allow an alternative
homeserver to be specified for the final `m.login.token`-based call to
`/login` (and subsequent C-S API calls).
This is discussed in more detail in
[MSC1731](https://github.com/matrix-org/matrix-doc/blob/rav/proposals/homeserver_in_sso_login/proposals/1731-redirect-in-sso-login.md).
It has the disadvantage of limiting the solution to SSO logins. The solution
presented in this proposal also extends to password-based logins.
### Use a 3pid login flow
It has been suggested that we could use a login flow based on third-party
identifiers.
In the current ecosystem, to do a 3pid login, clients must still be configured
to send their `/login` request to a particular homeserver, which will then take
them through an authentication process. We are therefore still left with the
problem that we need to switch homeservers between login and initial sync.
An alternative would be for clients to somehow know that they should go through
the single-sign-on process *before* choosing a homeserver, and for the
output of the single-sign-on process to indicate the homeserver to use. This
would require either substantially customised Matrix clients, or substantial
modifications to the login flow in Matrix, possibly involving authenticating
against an identity server. The latter is something which could be considered,
but the scope of the changes required make it impractical in the short/medium
term.

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 35 KiB

@ -1,43 +0,0 @@
# https://sequencediagram.org/
participantspacing equal
participant Client
participant matrix.ac.cdl
participant SAML2 SSO system
participant matrix.eng.ac.cdl
activate Client
Client->matrix.ac.cdl:""GET /_matrix/client/r0/login""
activate matrix.ac.cdl
Client<--matrix.ac.cdl:"""type": "m.login.sso"""
deactivate matrix.ac.cdl
# Start SSO flow: displayed in browser for web clients, or via fallback auth in embeddedbrowser for others
Client->matrix.ac.cdl:""GET /_matrix/client/r0/login/sso/redirect\n--?redirectUrl=<clienturl>--""
activate matrix.ac.cdl
matrix.ac.cdl->matrix.ac.cdl:Generate SAML request
Client<--matrix.ac.cdl:302 to SSO system
deactivate matrix.ac.cdl
Client->SAML2 SSO system:""GET /single-sign-on\n--?SAMLRequest=<request>&RelayState=<clienturl>--""
activate SAML2 SSO system
Client<-->SAML2 SSO system: auth credentials
SAML2 SSO system-->Client:auto-submitting HTML form including SAML Response
deactivate SAML2 SSO system
Client->matrix.ac.cdl:""POST /SAML2\n--SAMLResponse=<response>\nRelayState=<params>
activate matrix.ac.cdl
matrix.ac.cdl->matrix.ac.cdl:map user to HS
Client<--matrix.ac.cdl:auto-submitting HTML form for target HS
deactivate matrix.ac.cdl
Client->matrix.eng.ac.cdl:""POST /SAML2\n--SAMLResponse=<response>\nRelayState=<clienturl>
activate matrix.eng.ac.cdl
Client<--matrix.eng.ac.cdl:302 to clienturl with\n""--?loginToken=<token>
deactivate matrix.eng.ac.cdl
Client->matrix.ac.cdl:""POST /_matrix/client/r0/login\n--{"type": "m.login.token","token": "<token>"}
activate matrix.ac.cdl
matrix.ac.cdl->matrix.eng.ac.cdl:""POST /_matrix/client/r0/login\n--{"type": "m.login.token", "token": "<token>"}
activate matrix.eng.ac.cdl
matrix.ac.cdl<--matrix.eng.ac.cdl:""--{"user_id": "@user:eng.ac.cdl", "access_token": "abc123",\n "well_known": {"m.homeserver": "..."}}
deactivate matrix.eng.ac.cdl
Client<--matrix.ac.cdl:""--{"user_id": "@user:eng.ac.cdl",\n "access_token": "abc123",\n "well-known": {"m.homeserver": "..."}}
deactivate matrix.ac.cdl
Client<-#0000FF>matrix.eng.ac.cdl: Matrix

@ -43,6 +43,8 @@ The specification consists of the following parts:
The `Appendices <appendices.html>`_ contain supplemental information not specific to
one of the above APIs.
The `Matrix Client-Server API Swagger Viewer <https://matrix.org/docs/api/client-server/>`_ is useful for browsing the Client-Server API.
Introduction to the Matrix APIs
-------------------------------
.. WARNING::

@ -485,6 +485,11 @@ Definition:
{
"kind": "room_member_count",
"is": "2"
},
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.encrypted"
}
],
"actions": [
@ -496,11 +501,6 @@ Definition:
{
"set_tweak": "highlight",
"value": false
},
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.encrypted"
}
]
}
@ -569,7 +569,7 @@ Definition:
Matches all encrypted events. Unlike other push rules, this rule cannot
be matched against the content of the event by nature of it being encrypted.
This causes the rule to be an "all or nothing" match where it either
matches *all* events that are encrypted (in 1:1 rooms) or none.
matches *all* events that are encrypted (in group rooms) or none.
Definition:

@ -1,3 +1,7 @@
.. raw:: html
%proposalscssinjection%
.. title:: Proposals for Spec Changes to Matrix
.. contents:: Table of Contents

Loading…
Cancel
Save