From d24f15a3a91b19429d65dd516e8cded1c7a2b44f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 15 May 2020 13:41:05 -0600 Subject: [PATCH 1/7] Spec soft-logout per MSC1466 MSC: https://github.com/matrix-org/matrix-doc/issues/1466 --- api/client-server/registration.yaml | 5 ++++- .../client_server/newsfragments/2545.feature | 1 + specification/client_server_api.rst | 22 +++++++++++++++++++ 3 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2545.feature diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 50ce4a96..a6d5d275 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -346,8 +346,11 @@ paths: logout_devices: type: boolean description: |- - Whether the other access tokens, and their associated devices, for the user should be + Whether the other access tokens, and their associated devices, for the user should be revoked if the request succeeds. Defaults to true. + + When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_ + for the user's remaining devices. example: true auth: description: |- diff --git a/changelogs/client_server/newsfragments/2545.feature b/changelogs/client_server/newsfragments/2545.feature new file mode 100644 index 00000000..40c066f4 --- /dev/null +++ b/changelogs/client_server/newsfragments/2545.feature @@ -0,0 +1 @@ +Add soft-logout support per `MSC1466 `_. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index fce879a2..3c99d305 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -123,6 +123,10 @@ The common error codes are: :``M_UNKNOWN_TOKEN``: The access token specified was not recognised. + An additional response parameter, ``soft_logout``, might be present on the response + for 401 HTTP status codes. See `the soft logout section <#soft-logout>`_ for more + information. + :``M_MISSING_TOKEN``: No access token was specified for the request. @@ -404,6 +408,24 @@ should pass the ``device_id`` in the request body. If the client sets the to that device. There is therefore at most one active access token assigned to each device at any one time. +Soft logout +~~~~~~~~~~~ + + + +When a requests fail due to a 401 status code per above, the server can +include an extra response parameter, ``soft_logout``, to indicate if the +device information has been retained by the server. This defaults to ``false``, +implying the server has deleted the device alongside the access token. + +When ``soft_logout`` is true, the client can acquire a new access token by +specifying the device ID it is already using to the login API. In most cases +a ``soft_logout: true`` response indicates that the user's session has expired +on the server-side and the user simply needs to provide their credentials again. + +If ``soft_logout`` is ``false``, the client will not be able to reuse the device +information it already has - the server has destroyed the session. + User-Interactive Authentication API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From bd26a41114719c59c43befbc944301d49bfa4603 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 15 May 2020 13:42:08 -0600 Subject: [PATCH 2/7] off by one error --- .../client_server/newsfragments/{2545.feature => 2546.feature} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/client_server/newsfragments/{2545.feature => 2546.feature} (100%) diff --git a/changelogs/client_server/newsfragments/2545.feature b/changelogs/client_server/newsfragments/2546.feature similarity index 100% rename from changelogs/client_server/newsfragments/2545.feature rename to changelogs/client_server/newsfragments/2546.feature From b4beb05dde0d255d0738a11718fc0bc042d53f21 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 15 May 2020 13:44:21 -0600 Subject: [PATCH 3/7] Remove excess whitespace --- specification/client_server_api.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 3c99d305..4082fceb 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -411,8 +411,6 @@ each device at any one time. Soft logout ~~~~~~~~~~~ - - When a requests fail due to a 401 status code per above, the server can include an extra response parameter, ``soft_logout``, to indicate if the device information has been retained by the server. This defaults to ``false``, From 19cac033058898eaf1d90b2b16651ad70ff94f3c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 15 May 2020 22:45:18 -0600 Subject: [PATCH 4/7] Update specification/client_server_api.rst Co-authored-by: Hubert Chathi --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 4082fceb..62550d0a 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -411,7 +411,7 @@ each device at any one time. Soft logout ~~~~~~~~~~~ -When a requests fail due to a 401 status code per above, the server can +When a request fails due to a 401 status code per above, the server can include an extra response parameter, ``soft_logout``, to indicate if the device information has been retained by the server. This defaults to ``false``, implying the server has deleted the device alongside the access token. From 77d83b9ce503b9874bad98180eb233789b4bcd6a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 19 May 2020 08:05:47 -0600 Subject: [PATCH 5/7] Clarify that soft logout is about client state --- specification/client_server_api.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 62550d0a..11a1e3cd 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -412,17 +412,17 @@ Soft logout ~~~~~~~~~~~ When a request fails due to a 401 status code per above, the server can -include an extra response parameter, ``soft_logout``, to indicate if the -device information has been retained by the server. This defaults to ``false``, -implying the server has deleted the device alongside the access token. +include an extra response parameter, ``soft_logout``, to indicate if the client's +persisted information can be retained. This defaults to ``false``, indicating +that the server has destroyed the session. Any persisted state held by the client, +such as encryption keys and device information, will not be able to be reused. When ``soft_logout`` is true, the client can acquire a new access token by specifying the device ID it is already using to the login API. In most cases a ``soft_logout: true`` response indicates that the user's session has expired on the server-side and the user simply needs to provide their credentials again. -If ``soft_logout`` is ``false``, the client will not be able to reuse the device -information it already has - the server has destroyed the session. +In either case, the client's previously known access token will no longer function. User-Interactive Authentication API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 10e4ad72ca7bd6ed36b1611e0723fcf494c34306 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 19 May 2020 11:58:28 -0600 Subject: [PATCH 6/7] Clarify retention of information for soft logout Co-authored-by: Hubert Chathi --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 11a1e3cd..f4cc7478 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -415,7 +415,7 @@ When a request fails due to a 401 status code per above, the server can include an extra response parameter, ``soft_logout``, to indicate if the client's persisted information can be retained. This defaults to ``false``, indicating that the server has destroyed the session. Any persisted state held by the client, -such as encryption keys and device information, will not be able to be reused. +such as encryption keys and device information, must not be reused and must be discarded. When ``soft_logout`` is true, the client can acquire a new access token by specifying the device ID it is already using to the login API. In most cases From a5cb9c655c083e38989215e6e405599def15f9f7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 May 2020 12:38:40 -0600 Subject: [PATCH 7/7] It's important to say who Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- api/client-server/registration.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index a6d5d275..bab9139c 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -346,7 +346,7 @@ paths: logout_devices: type: boolean description: |- - Whether the other access tokens, and their associated devices, for the user should be + Whether the user's other access tokens, and their associated devices, should be revoked if the request succeeds. Defaults to true. When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_