From 6f2c2b2c7ec560f4cb00bff26d3d288702eb150b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 23 Nov 2018 12:35:06 +0000 Subject: [PATCH 1/8] MSC1730: Mechanism for redirecting to an alternative server during login --- proposals/1730-cs-api-in-login-response.md | 66 ++++++++++++++++++++++ proposals/images/1730-seq-diagram.svg | 1 + proposals/images/1730-seq-diagram.txt | 17 ++++++ 3 files changed, 84 insertions(+) create mode 100644 proposals/1730-cs-api-in-login-response.md create mode 100644 proposals/images/1730-seq-diagram.svg create mode 100644 proposals/images/1730-seq-diagram.txt diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md new file mode 100644 index 00000000..b481342b --- /dev/null +++ b/proposals/1730-cs-api-in-login-response.md @@ -0,0 +1,66 @@ +# 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 depends on the individual user, and is determined at +login time. + +It may therefore be useful to provide a mechanism to tell clients which +endpoint they should use for the client-server (C-S) API after login. + +## 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 an optional field `base_cs_url`, which gives a base URL +for the client-server API. + +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. + +(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.) + +A representative sequence diagram is shown below. + +![Sequence diagram](images/1730-seq-diagram.svg) + +## Tradeoffs + +Alternative solutions might include: + +### 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. + +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. + +### 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. + +This has the advantage of reusing existing mechanisms, but 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. + + This adds latency and overhead, and complicates client implementations. + +* It complicates deployment, since each target server has to support a + `.well-known` lookup. + +* Since the portal already has knowledge of the location of the C-S API for the + target homeserver, and has mapped the login request onto the correct HS, it + feels redundant to have a separate mechanism which repeats that mapping. diff --git a/proposals/images/1730-seq-diagram.svg b/proposals/images/1730-seq-diagram.svg new file mode 100644 index 00000000..ac5cd762 --- /dev/null +++ b/proposals/images/1730-seq-diagram.svg @@ -0,0 +1 @@ +ClientPortalTarget HSPOST /_matrix/client/r0/loginPOST /_matrix/client/r0/login{"access_token": "...", ...}{"base_cs_url": "https://targeths","access_token": "...", ...}/_matrix/client/versions{"versions": [...]}Further C-S APIs \ No newline at end of file diff --git a/proposals/images/1730-seq-diagram.txt b/proposals/images/1730-seq-diagram.txt new file mode 100644 index 00000000..a472ab85 --- /dev/null +++ b/proposals/images/1730-seq-diagram.txt @@ -0,0 +1,17 @@ +participantspacing equal + +Client->Portal:""POST /_matrix/client/r0/login +activate Portal +Portal->Target HS:""POST /_matrix/client/r0/login +activate Target HS +Target HS-->Portal:""{"access_token": "...", ...} +deactivate Target HS +Portal->Client:""{"base_cs_url": "https://targeths",\n"access_token": "...", ...} +deactivate Portal + +Client->Target HS: ""/_matrix/client/versions +activate Target HS +Target HS-->Client: ""{"versions": [...]} +deactivate Target HS + +Client<->Target HS: Further C-S APIs \ No newline at end of file From a39189c08bd2af44c421b5f442811490c7235fb2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 23 Nov 2018 22:18:10 +0000 Subject: [PATCH 2/8] Update proposal Notes on problems, workaround, and another alternative --- proposals/1730-cs-api-in-login-response.md | 49 ++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md index b481342b..77f0fe34 100644 --- a/proposals/1730-cs-api-in-login-response.md +++ b/proposals/1730-cs-api-in-login-response.md @@ -29,6 +29,35 @@ A representative sequence diagram is shown below. ![Sequence diagram](images/1730-seq-diagram.svg) +### Potential issues + +A significant problem with the proposed architecture is that the portal server +has to proxy the `/login` request, so that it can update the response. This +leads to the following concerns: + +* 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`.) + + 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. + +* It causes additional complexity in the portal server, which must now be + responsible for making outbound HTTP requests. + +* 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.) + +An alternative implementation of the portal server would be for the portal +server to redirect the `/login` request with a 307 response. This solves the +above problems, but may reduce flexibility, or require more state to be managed +on the portal server [1]. + ## Tradeoffs Alternative solutions might include: @@ -64,3 +93,23 @@ problems: * Since the portal already has knowledge of the location of the C-S API for the target homeserver, and has mapped the login request onto the correct HS, it feels redundant to have a separate mechanism which repeats that mapping. + +### 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. + + +[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.. From 94d83c04832d4431ba24671f4c9404557248fde3 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 26 Nov 2018 18:36:07 +0000 Subject: [PATCH 3/8] Update based on feedback Mostly this is clarification of the problem domain; it also updates some of the discussion points to reflect my current thinking. --- proposals/1730-cs-api-in-login-response.md | 55 +++++++++++++--------- proposals/images/1730-seq-diagram-2.svg | 1 + proposals/images/1730-seq-diagram-2.txt | 18 +++++++ proposals/images/1730-seq-diagram.svg | 2 +- proposals/images/1730-seq-diagram.txt | 4 +- 5 files changed, 56 insertions(+), 24 deletions(-) create mode 100644 proposals/images/1730-seq-diagram-2.svg create mode 100644 proposals/images/1730-seq-diagram-2.txt diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md index 77f0fe34..7e5ed495 100644 --- a/proposals/1730-cs-api-in-login-response.md +++ b/proposals/1730-cs-api-in-login-response.md @@ -1,10 +1,13 @@ # 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 depends on the individual user, and is determined at -login time. +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. -It may therefore be useful to provide a mechanism to tell clients which +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. ## Proposal @@ -12,27 +15,32 @@ endpoint they should use for the client-server (C-S) API after login. 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 an optional field `base_cs_url`, which gives a base URL -for the client-server API. +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. 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. +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: + +![Sequence diagram](images/1730-seq-diagram.svg) + +Alternatively, the portal server could redirect the original `login` request to +the target HS with a `307 Temporary Redirect` response: + +![Sequence diagram](images/1730-seq-diagram-2.svg) + (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.) -A representative sequence diagram is shown below. +### Notes on proxying vs redirecting -![Sequence diagram](images/1730-seq-diagram.svg) - -### Potential issues - -A significant problem with the proposed architecture is that the portal server -has to proxy the `/login` request, so that it can update the response. This +Proxying the `/login` request as shown in the first sequence diagram above leads to the following concerns: * The target homeserver sees the request coming from the portal server rather @@ -53,10 +61,18 @@ leads to the following concerns: to some extent in this architecture, it is unclear how much of a concern this really is.) -An alternative implementation of the portal server would be for the portal -server to redirect the `/login` request with a 307 response. This solves the -above problems, but may reduce flexibility, or require more state to be managed -on the portal server [1]. +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 any case, this is an implementation decision; portal servers can use +whichever method best suits their needs. ## Tradeoffs @@ -88,11 +104,8 @@ problems: This adds latency and overhead, and complicates client implementations. * It complicates deployment, since each target server has to support a - `.well-known` lookup. - -* Since the portal already has knowledge of the location of the C-S API for the - target homeserver, and has mapped the login request onto the correct HS, it - feels redundant to have a separate mechanism which repeats that mapping. + `.well-known` lookup. (This is somewhat weak: target servers should + support `.well-known` lookups anyway.) ### Add an alternative redirection mechanism in the login flow diff --git a/proposals/images/1730-seq-diagram-2.svg b/proposals/images/1730-seq-diagram-2.svg new file mode 100644 index 00000000..6af300f8 --- /dev/null +++ b/proposals/images/1730-seq-diagram-2.svg @@ -0,0 +1 @@ +ClientPortalTarget HSPOST /_matrix/client/r0/login307 redirectPOST /_matrix/client/r0/login{"base_cs_url": "http://targeths","access_token": "...", ...}/_matrix/client/versions{"versions": [...]}Further C-S APIs \ No newline at end of file diff --git a/proposals/images/1730-seq-diagram-2.txt b/proposals/images/1730-seq-diagram-2.txt new file mode 100644 index 00000000..8be837d3 --- /dev/null +++ b/proposals/images/1730-seq-diagram-2.txt @@ -0,0 +1,18 @@ +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 \ No newline at end of file diff --git a/proposals/images/1730-seq-diagram.svg b/proposals/images/1730-seq-diagram.svg index ac5cd762..e8913b47 100644 --- a/proposals/images/1730-seq-diagram.svg +++ b/proposals/images/1730-seq-diagram.svg @@ -1 +1 @@ -ClientPortalTarget HSPOST /_matrix/client/r0/loginPOST /_matrix/client/r0/login{"access_token": "...", ...}{"base_cs_url": "https://targeths","access_token": "...", ...}/_matrix/client/versions{"versions": [...]}Further C-S APIs \ No newline at end of file +ClientPortalTarget HSPOST /_matrix/client/r0/loginPOST /_matrix/client/r0/login{"base_cs_url": "http://targeths","access_token": "...", ...}{"base_cs_url": "http://targeths","access_token": "...", ...}/_matrix/client/versions{"versions": [...]}Further C-S APIs \ No newline at end of file diff --git a/proposals/images/1730-seq-diagram.txt b/proposals/images/1730-seq-diagram.txt index a472ab85..c4763f62 100644 --- a/proposals/images/1730-seq-diagram.txt +++ b/proposals/images/1730-seq-diagram.txt @@ -4,9 +4,9 @@ Client->Portal:""POST /_matrix/client/r0/login activate Portal Portal->Target HS:""POST /_matrix/client/r0/login activate Target HS -Target HS-->Portal:""{"access_token": "...", ...} +Target HS-->Portal:""{"base_cs_url": "http://targeths",\n"access_token": "...", ...} deactivate Target HS -Portal->Client:""{"base_cs_url": "https://targeths",\n"access_token": "...", ...} +Portal->Client:""{"base_cs_url": "http://targeths",\n"access_token": "...", ...} deactivate Portal Client->Target HS: ""/_matrix/client/versions From 6fa754c447fe93cffd5c011640fe4c63c7daaa4b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 26 Nov 2018 23:37:10 +0000 Subject: [PATCH 4/8] Tradeoffs->rejected solutions because apparently this was somehow confusing --- proposals/1730-cs-api-in-login-response.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md index 7e5ed495..6059d92e 100644 --- a/proposals/1730-cs-api-in-login-response.md +++ b/proposals/1730-cs-api-in-login-response.md @@ -74,7 +74,7 @@ of any current browsers which do not follow `307` redirects.) In any case, this is an implementation decision; portal servers can use whichever method best suits their needs. -## Tradeoffs +## Rejected solutions Alternative solutions might include: From 57421cc59bb14c5c7e324eafdd33f7e9fddec58a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 6 Dec 2018 12:48:12 +0000 Subject: [PATCH 5/8] attempt to clarify MSC1730 --- proposals/1730-cs-api-in-login-response.md | 159 ++++++++++----------- proposals/images/1730-seq-diagram-2.svg | 1 - proposals/images/1730-seq-diagram-2.txt | 18 --- proposals/images/1730-seq-diagram.svg | 2 +- proposals/images/1730-seq-diagram.txt | 54 +++++-- 5 files changed, 117 insertions(+), 117 deletions(-) delete mode 100644 proposals/images/1730-seq-diagram-2.svg delete mode 100644 proposals/images/1730-seq-diagram-2.txt diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md index 7e5ed495..5d8652c6 100644 --- a/proposals/1730-cs-api-in-login-response.md +++ b/proposals/1730-cs-api-in-login-response.md @@ -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.. diff --git a/proposals/images/1730-seq-diagram-2.svg b/proposals/images/1730-seq-diagram-2.svg deleted file mode 100644 index 6af300f8..00000000 --- a/proposals/images/1730-seq-diagram-2.svg +++ /dev/null @@ -1 +0,0 @@ -ClientPortalTarget HSPOST /_matrix/client/r0/login307 redirectPOST /_matrix/client/r0/login{"base_cs_url": "http://targeths","access_token": "...", ...}/_matrix/client/versions{"versions": [...]}Further C-S APIs \ No newline at end of file diff --git a/proposals/images/1730-seq-diagram-2.txt b/proposals/images/1730-seq-diagram-2.txt deleted file mode 100644 index 8be837d3..00000000 --- a/proposals/images/1730-seq-diagram-2.txt +++ /dev/null @@ -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 \ No newline at end of file diff --git a/proposals/images/1730-seq-diagram.svg b/proposals/images/1730-seq-diagram.svg index e8913b47..786b975d 100644 --- a/proposals/images/1730-seq-diagram.svg +++ b/proposals/images/1730-seq-diagram.svg @@ -1 +1 @@ -ClientPortalTarget HSPOST /_matrix/client/r0/loginPOST /_matrix/client/r0/login{"base_cs_url": "http://targeths","access_token": "...", ...}{"base_cs_url": "http://targeths","access_token": "...", ...}/_matrix/client/versions{"versions": [...]}Further C-S APIs \ No newline at end of file +Clientmatrix.ac.cdlSAML2 SSO systemmatrix.eng.ac.cdlGET /_matrix/client/r0/login"type": "m.login.sso"GET /_matrix/client/r0/login/sso/redirect?redirectUrl=<clienturl>Generate SAML request302 to SSO systemGET /single-sign-on?SAMLRequest=<request>&RelayState=<clienturl>auth credentialsauto-submitting HTML form including SAML ResponsePOST /SAML2SAMLResponse=<response>RelayState=<params>map user to HSauto-submitting HTML form for target HSPOST /SAML2SAMLResponse=<response>RelayState=<clienturl>302 to clienturl with?loginToken=<token>POST /_matrix/client/r0/login{"type": "m.login.token","token": "<token>"}POST /_matrix/client/r0/login{"type": "m.login.token", "token": "<token>"}{"user_id": "@user:eng.ac.cdl", "access_token": "abc123", "well_known": {"m.homeserver": "..."}}{"user_id": "@user:eng.ac.cdl", "access_token": "abc123", "well-known": {"m.homeserver": "..."}}Matrix \ No newline at end of file diff --git a/proposals/images/1730-seq-diagram.txt b/proposals/images/1730-seq-diagram.txt index c4763f62..7c467f78 100644 --- a/proposals/images/1730-seq-diagram.txt +++ b/proposals/images/1730-seq-diagram.txt @@ -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 \ No newline at end of file +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=--"" +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=&RelayState=--"" +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=\nRelayState= +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=\nRelayState= +activate matrix.eng.ac.cdl +Client<--matrix.eng.ac.cdl:302 to clienturl with\n""--?loginToken= +deactivate matrix.eng.ac.cdl +Client->matrix.ac.cdl:""POST /_matrix/client/r0/login\n--{"type": "m.login.token","token": ""} +activate matrix.ac.cdl +matrix.ac.cdl->matrix.eng.ac.cdl:""POST /_matrix/client/r0/login\n--{"type": "m.login.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 From 9c9c5a8c65db6fcbc7ce2edd0fe555ef34153370 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 6 Dec 2018 16:06:17 +0000 Subject: [PATCH 6/8] more alternatives --- proposals/1730-cs-api-in-login-response.md | 31 ++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md index 5d8652c6..93cfc29e 100644 --- a/proposals/1730-cs-api-in-login-response.md +++ b/proposals/1730-cs-api-in-login-response.md @@ -119,3 +119,34 @@ 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. From 275e516f93cd783d7fec631ad0b31e793c95bf85 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 6 Dec 2018 16:32:55 +0000 Subject: [PATCH 7/8] Rename svg file to bust cache github is serving up the old file for some reason --- proposals/1730-cs-api-in-login-response.md | 2 +- .../images/{1730-seq-diagram.svg => 1730-seq-diagram.1.svg} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename proposals/images/{1730-seq-diagram.svg => 1730-seq-diagram.1.svg} (100%) diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md index 0043ce26..b5e04215 100644 --- a/proposals/1730-cs-api-in-login-response.md +++ b/proposals/1730-cs-api-in-login-response.md @@ -50,7 +50,7 @@ homeserver after login. A complete login flow is as shown in the following sequence diagram: -![Sequence diagram](images/1730-seq-diagram.svg) +![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 diff --git a/proposals/images/1730-seq-diagram.svg b/proposals/images/1730-seq-diagram.1.svg similarity index 100% rename from proposals/images/1730-seq-diagram.svg rename to proposals/images/1730-seq-diagram.1.svg From 6f7b3198fb7c181647ee88fd0c8f45c39466b6a0 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 6 Dec 2018 16:36:41 +0000 Subject: [PATCH 8/8] fix list which got lost in merge --- proposals/1730-cs-api-in-login-response.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/1730-cs-api-in-login-response.md b/proposals/1730-cs-api-in-login-response.md index b5e04215..088df257 100644 --- a/proposals/1730-cs-api-in-login-response.md +++ b/proposals/1730-cs-api-in-login-response.md @@ -68,6 +68,12 @@ so users' MXids would look like `@user:ac.cdl` instead of 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