From 0f623113f10cfc50d99305a8d61ce02371636f5c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 18:35:18 -0600 Subject: [PATCH 1/2] Clarify that UIA stages cannot be attempted twice Fixes https://github.com/matrix-org/matrix-doc/issues/1987 Note: Synapse currently does not care, however the spirit of the text in the spec implies that completed == done forever, so we're just reinforcing it here. --- .../client_server/newsfragments/2054.clarification | 1 + specification/client_server_api.rst | 11 ++++++----- 2 files changed, 7 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2054.clarification diff --git a/changelogs/client_server/newsfragments/2054.clarification b/changelogs/client_server/newsfragments/2054.clarification new file mode 100644 index 00000000..e43aea2d --- /dev/null +++ b/changelogs/client_server/newsfragments/2054.clarification @@ -0,0 +1 @@ +Clarify that User-Interactive Authentication stages cannot be attempted more than once. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6c2e364a..318ac08d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -453,11 +453,10 @@ params presented, that type may be present as a key in this dictionary. For example, the public part of an OAuth client ID could be given here. session - This is a session identifier that the client must pass back to the home - server, if one is provided, in subsequent attempts to authenticate in the same - API call. + This is a session identifier that the client must pass back to the homeserver, + if one is provided, in subsequent attempts to authenticate in the same API call. -The client then chooses a flow and attempts to complete one of the stages. It +The client then chooses a flow and attempts to complete the first stage. It does this by resubmitting the same request with the addition of an ``auth`` key in the object that it submits. This dictionary contains a ``type`` key whose value is the name of the authentication type that the client is attempting to complete. @@ -558,7 +557,9 @@ message in the standard format. For example: } If the client has completed all stages of a flow, the homeserver performs the -API call and returns the result as normal. +API call and returns the result as normal. Completed stages cannot be re-tried; +The client must abandon the current session and start over. Homeservers should +treat retries as authentication errors. Some authentication types may be completed by means other than through the Matrix client, for example, an email confirmation may be completed when the user From e644227f4b607b3438cb37b21616a68e7f007645 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 14:13:20 -0600 Subject: [PATCH 2/2] Clarify that the server shouldn't process retries for UIA --- specification/client_server_api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 318ac08d..4593311d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -557,9 +557,10 @@ message in the standard format. For example: } If the client has completed all stages of a flow, the homeserver performs the -API call and returns the result as normal. Completed stages cannot be re-tried; -The client must abandon the current session and start over. Homeservers should -treat retries as authentication errors. +API call and returns the result as normal. Completed stages cannot be retried +by clients, therefore servers must return either a 401 response with the completed +stages, or the result of the API call if all stages were completed when a client +retries a stage. Some authentication types may be completed by means other than through the Matrix client, for example, an email confirmation may be completed when the user