attempt to clarify MSC1730

pull/977/head
Richard van der Hoff 6 years ago
parent 94d83c0483
commit 57421cc59b

@ -1,111 +1,114 @@
# MSC1730: Mechanism for redirecting to an alternative server during login
Complex homeserver deployments may consist of several homeserver instances,
where the HS to be used for a user session is determined at login time. The HS
might be chosen based on any of a number of factors, such as the individual
user, or a simple round-robin to load-balance.
## Background/requirements
One solution to this is for users to log in via a "portal server", which
accepts the login request, and picks the server accordingly. This proposal
suggests adding a field to the `/login` response which tells clients which
endpoint they should use for the client-server (C-S) API after login.
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 should add to this a `base_cs_url` field, which SHOULD be returned by
compliant homeservers, which gives a base URL for the client-server API.
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).
As with
[.well-known](https://matrix.org/docs/spec/client_server/r0.4.0.html#well-known-uri),
clients would then add `/_matrix/client/...` to this URL to form valid C-S
endpoints.
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.
One way that this could be used is that the portal server proxies the `/login`
request, and passes it on to the target HS, as shown in the sequence diagram below:
## Application
![Sequence diagram](images/1730-seq-diagram.svg)
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.
Alternatively, the portal server could redirect the original `login` request to
the target HS with a `307 Temporary Redirect` response:
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.
![Sequence diagram](images/1730-seq-diagram-2.svg)
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.
(Note that the deprecated `home_server` field gives the `server_name` of the
relevant homeserver, which may be quite different to the location of the C-S
API, so is not of use here. Further we cannot repurpose it, because (a) this
might break existing clients; (b) it spells homeserver wrong.)
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.
### Notes on proxying vs redirecting
A complete login flow is as shown in the following sequence diagram:
Proxying the `/login` request as shown in the first sequence diagram above
leads to the following concerns:
![Sequence diagram](images/1730-seq-diagram.svg)
* The target homeserver sees the request coming from the portal server rather
than the client, so that the wrong IP address will be recorded against the
user's session. (This might be a problem for, for example, IP locking the
session, and might affect the `last_seen_ip` field returned by `GET
/_matrix/client/r0/devices`.)
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.
This can be mitigated to some extent via the use of an `X-Forwarded-For`
header, but that then requires the portal server to authenticate itself with
the target homeserver in some way.
## Rejected solutions
* It causes additional complexity in the portal server, which must now be
responsible for making outbound HTTP requests.
Alternative solutions might include:
* It potentially leads to a privacy leak, since the portal server could snoop
on the returned access token. (Given that the portal server must be trusted
to some extent in this architecture, it is unclear how much of a concern this
really is.)
### Have all users on one homeserver
On the other hand, redirecting it with a `307` response may reduce flexibility,
or require more state to be managed on the portal server [1]. Furthermore
support for `307` redirects among user-agents may vary
([RFC2616](https://tools.ietf.org/html/rfc2616#section-10.3.8) said "If the 307
status code is received in response to a request other than GET or HEAD, the
user agent MUST NOT automatically redirect the request unless it can be
confirmed by the user", though this appears to have been dropped by
[RFC7231](https://tools.ietf.org/html/rfc7231#section-6.4.7) and I am unaware
of any current browsers which do not follow `307` redirects.)
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`.
In any case, this is an implementation decision; portal servers can use
whichever method best suits their needs.
However, there are circumstances where separate homeservers are required:
## Tradeoffs
* 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.
Alternative solutions might include:
### 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 portal to proxy all C-S interaction, as well as
`/login`, directing requests to the right server for the user.
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
portal server, and the fact that it makes the portal a single point of failure
for the entire system.
central homeserver, and the fact that it makes the central server a single
point of failure for the entire system.
### Perform a .well-known lookup after login
### Require clients to perform a .well-known lookup after login
Once clients know the server name of the homeserver they should be using
(having extracted it from the `/login` response), they could perform a
`.well-known` lookup on the target server to locate its C-S API.
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 advantage of reusing existing mechanisms, but has the following
problems:
This has the following problems:
* Clients are currently required to do a `.well-known` lookup *before* login,
so that they can find the correct endpoint for the `/login` API. That means
they will have to do *two* `.well-known` lookups - one before and one after
login.
* In most cases this `.well-known` lookup will be entirely redundant. It adds
latency and overhead, and complicates client implementations.
This adds latency and overhead, and complicates client implementations.
* It complicates deployment, since each target server has to support a
`.well-known` lookup. (This is somewhat weak: target servers should
support `.well-known` lookups anyway.)
* 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
@ -116,13 +119,3 @@ 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.
[1] The reason more state is needed is as follows: because the portal is now
redirecting the login rather than proxying it, it cannot modify the login
dictionary. This is a problem for the single-sign-on flow, which culminates in
an `m.login.token` login. The only way that the portal can identify a given
user session - and thus know where to redirect to - is via the login token, and
of course, it cannot modify that token without making it invalid for the target
HS. It therefore has to use the login token as a session identifier, and store
session state..

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 13 KiB

@ -1,18 +0,0 @@
participantspacing equal
Client->Portal:""POST /_matrix/client/r0/login
activate Portal
Portal-->Client:""307"" redirect
deactivate Portal
Client->Target HS:""POST /_matrix/client/r0/login
activate Target HS
Target HS->Client:""{"base_cs_url": "http://targeths",\n"access_token": "...", ...}
deactivate Target HS
Client->Target HS: ""/_matrix/client/versions
activate Target HS
Target HS-->Client: ""{"versions": [...]}
deactivate Target HS
Client<->Target HS: Further C-S APIs

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 35 KiB

@ -1,17 +1,43 @@
participantspacing equal
# https://sequencediagram.org/
Client->Portal:""POST /_matrix/client/r0/login
activate Portal
Portal->Target HS:""POST /_matrix/client/r0/login
activate Target HS
Target HS-->Portal:""{"base_cs_url": "http://targeths",\n"access_token": "...", ...}
deactivate Target HS
Portal->Client:""{"base_cs_url": "http://targeths",\n"access_token": "...", ...}
deactivate Portal
participantspacing equal
participant Client
participant matrix.ac.cdl
participant SAML2 SSO system
participant matrix.eng.ac.cdl
Client->Target HS: ""/_matrix/client/versions
activate Target HS
Target HS-->Client: ""{"versions": [...]}
deactivate Target HS
activate Client
Client<->Target HS: Further C-S APIs
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

Loading…
Cancel
Save