From 25d01aa4312b64131edd3097d687df3902093eff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:33:09 -0600 Subject: [PATCH 1/4] Dedicate a section on how to use access tokens Fixes https://github.com/matrix-org/matrix-doc/issues/1042. --- specification/client_server_api.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 58f68f25..27cd9a0f 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -191,10 +191,6 @@ previously obtained credentials in the form of an ``access_token`` query parameter or through an Authorization Header of ``Bearer $access_token``. An access token is typically obtained via the `Login`_ or `Registration`_ processes. -When credentials are required but missing or invalid, the HTTP call will -return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or -``M_UNKNOWN_TOKEN`` respectively. - .. NOTE:: This specification does not mandate a particular format for the access @@ -202,6 +198,19 @@ return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or to choose an appropriate format. Server implementors may like to investigate `macaroons `_. +Using access tokens +~~~~~~~~~~~~~~~~~~~ + +Access tokens may be provided in two ways, both of which the homeserver MUST +support: + +1. Via a query string parameter, ``access_token=TheTokenHere``. +#. Via a request header, ``Authorization: Bearer TheTokenHere``. + +When credentials are required but missing or invalid, the HTTP call will +return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or +``M_UNKNOWN_TOKEN`` respectively. + Relationship between access tokens and devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From b159f218576aec308745283b3ffdcb4a4561bdd5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:34:23 -0600 Subject: [PATCH 2/4] changelog --- changelogs/client_server/newsfragments/1517.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1517.clarification diff --git a/changelogs/client_server/newsfragments/1517.clarification b/changelogs/client_server/newsfragments/1517.clarification new file mode 100644 index 00000000..b16928c1 --- /dev/null +++ b/changelogs/client_server/newsfragments/1517.clarification @@ -0,0 +1 @@ +Clarify how access tokens are meant to be supplied to the homeserver. \ No newline at end of file From ca87876f1ba2a16f88a60ae9880d1db54ddf496b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:37:52 -0600 Subject: [PATCH 3/4] Clarify that the Authorization header is preferred --- specification/client_server_api.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 27cd9a0f..e64572ab 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -207,6 +207,11 @@ support: 1. Via a query string parameter, ``access_token=TheTokenHere``. #. Via a request header, ``Authorization: Bearer TheTokenHere``. +Clients are encouraged to use the ``Authorization`` header where possible +to prevent the access token being leaked in access/HTTP logs. The query +string should only be used in cases where the ``Authorization`` header is +unaccessible for the client. + When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or ``M_UNKNOWN_TOKEN`` respectively. From d6c54b0278bbf284c1232878fec41f24d9c9b468 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 16:39:01 -0600 Subject: [PATCH 4/4] unaccessible isn't a word --- 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 e64572ab..7cd14f7f 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -210,7 +210,7 @@ support: Clients are encouraged to use the ``Authorization`` header where possible to prevent the access token being leaked in access/HTTP logs. The query string should only be used in cases where the ``Authorization`` header is -unaccessible for the client. +inaccessible for the client. When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or