From 0c4b09305e2bb89064d28e1927bfbcbb0f3669ea Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 15 Nov 2018 12:34:53 +0000 Subject: [PATCH 1/9] Proposal to rename m.login.cas to m.login.sso --- proposals/1721-rename-cas-to-sso.md | 37 +++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 proposals/1721-rename-cas-to-sso.md diff --git a/proposals/1721-rename-cas-to-sso.md b/proposals/1721-rename-cas-to-sso.md new file mode 100644 index 000000000..10902ce7d --- /dev/null +++ b/proposals/1721-rename-cas-to-sso.md @@ -0,0 +1,37 @@ +# 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 should probably rename the post-authentication callback endpoint + `/_matrix/client/r0/login/sso/ticket` instead of + `/_matrix/client/r0/login/cas/ticket`. Note, however, that this name is only + a suggestion: the full name of this endpoint is implementation-specific. + +5. 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. From 96d7eed1c6b1a74870bc505c09e5c99fa0575efd Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Thu, 3 May 2018 23:19:16 +0900 Subject: [PATCH 2/9] joining.yaml: add missing response schema details --- api/client-server/joining.yaml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index 7dc1e0a4a..1bd7224fe 100644 --- a/api/client-server/joining.yaml +++ b/api/client-server/joining.yaml @@ -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: From b5a82a5eb1f32ae29e9c576e03ba54c66afb6405 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 22 Nov 2018 23:04:43 +0000 Subject: [PATCH 3/9] no need to rename ticket endpoint --- proposals/1721-rename-cas-to-sso.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/proposals/1721-rename-cas-to-sso.md b/proposals/1721-rename-cas-to-sso.md index 10902ce7d..5d4abcd8e 100644 --- a/proposals/1721-rename-cas-to-sso.md +++ b/proposals/1721-rename-cas-to-sso.md @@ -17,7 +17,7 @@ Accordingly, we should rename `cas` to `sso`. 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). + there.) 2. When a client wishes to use the SSO login type, it should redirect to `/_matrix/client/r0/login/sso/redirect` (instead of @@ -27,11 +27,6 @@ Accordingly, we should rename `cas` to `sso`. `/_matrix/client/r0/login/cas/redirect`: they should issue a redirect to their configured single-sign-on system. -4. Servers should probably rename the post-authentication callback endpoint - `/_matrix/client/r0/login/sso/ticket` instead of - `/_matrix/client/r0/login/cas/ticket`. Note, however, that this name is only - a suggestion: the full name of this endpoint is implementation-specific. - -5. Servers which support `m.login.sso` should make sure they update their [login +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. From 6782b6399fc3ae70ef5c23c68703e73467409e5b Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Fri, 23 Nov 2018 17:54:00 +0900 Subject: [PATCH 4/9] Update according to the comments --- api/client-server/joining.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index 1bd7224fe..1dcf769f3 100644 --- a/api/client-server/joining.yaml +++ b/api/client-server/joining.yaml @@ -104,7 +104,7 @@ paths: properties: room_id: type: string - description: The joined room id + description: The joined room ID. required: ["room_id"] 403: description: |- @@ -216,7 +216,7 @@ paths: properties: room_id: type: string - description: The joined room id + description: The joined room ID. required: ["room_id"] 403: description: |- From 43109a717fe575344a380644d8294bb5bbde857d Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Mon, 3 Dec 2018 12:27:58 +0000 Subject: [PATCH 5/9] placeholder for proposals CSS --- specification/proposals_intro.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 55e8cd62c..923148678 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -1,3 +1,7 @@ +.. raw:: html + + %proposalscssinjection% + .. title:: Proposals for Spec Changes to Matrix .. contents:: Table of Contents From 16f17855c9365f5e59fd954ce61f404b67739112 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Wed, 5 Dec 2018 15:47:55 +0000 Subject: [PATCH 6/9] link to CS API Swagger Viewer --- specification/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/index.rst b/specification/index.rst index 4cbb1de32..bb9187393 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -43,6 +43,8 @@ The specification consists of the following parts: The `Appendices `_ contain supplemental information not specific to one of the above APIs. +The `Matrix Client-Server API Swagger Viewer `_ is useful for browsing the Client-Server API. + Introduction to the Matrix APIs ------------------------------- .. WARNING:: From 55ebf7dc3275822ad0126546baef4b1361418baf Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 10 Dec 2018 09:59:15 +0000 Subject: [PATCH 7/9] MSC 1466 - Soft Logout (#1467) --- proposals/1466-soft-logout.md | 45 +++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 proposals/1466-soft-logout.md diff --git a/proposals/1466-soft-logout.md b/proposals/1466-soft-logout.md new file mode 100644 index 000000000..321983106 --- /dev/null +++ b/proposals/1466-soft-logout.md @@ -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. + From d197a5761fcfda0bd121f5a449673f144e8137a7 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Tue, 11 Dec 2018 16:05:42 +0000 Subject: [PATCH 8/9] Clarify encrypted push rules Fix `.m.rule.encrypted_room_one_to_one` by moving a condition to the right block of the rule. Fix `.m.rule.encrypted` to state that it applies to group rooms. Signed-off-by: J. Ryan Stinnett --- specification/modules/push.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 4a6dfb104..008eaa8b6 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -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: From 6dab28770875386d5422a8dc8849959daa63b720 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Dec 2018 15:49:24 -0700 Subject: [PATCH 9/9] Revert "MSC1730: Mechanism for redirecting to an alternative server during login" --- proposals/1730-cs-api-in-login-response.md | 152 --------------------- proposals/images/1730-seq-diagram.1.svg | 1 - proposals/images/1730-seq-diagram.txt | 43 ------ 3 files changed, 196 deletions(-) delete mode 100644 proposals/1730-cs-api-in-login-response.md delete mode 100644 proposals/images/1730-seq-diagram.1.svg delete 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 deleted file mode 100644 index 088df2573..000000000 --- a/proposals/1730-cs-api-in-login-response.md +++ /dev/null @@ -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. diff --git a/proposals/images/1730-seq-diagram.1.svg b/proposals/images/1730-seq-diagram.1.svg deleted file mode 100644 index 786b975d6..000000000 --- a/proposals/images/1730-seq-diagram.1.svg +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 100644 index 7c467f784..000000000 --- a/proposals/images/1730-seq-diagram.txt +++ /dev/null @@ -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=--"" -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