From 2e4e5e25e81d306be67a0d9bb736a504588ed775 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 13:41:53 -0700 Subject: [PATCH 1/5] Improve documentation around /account/whoami Clarifies: https://github.com/matrix-org/matrix-doc/issues/1135 Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 36 ++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index e3262fe4..6bf4f1fb 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -29,7 +29,13 @@ paths: get: summary: Gets information about the owner of an access token. description: |- - Gets information about the owner of a given access token. + Gets information about the owner of a given access token. + + If the owner of the access token is an application service, + the server should return the user ID making the request. The + server should respect the application service client/server API + extensions during this request. If the request is made for a + virtual user, the server should verify that it is registered. operationId: getTokenOwner security: - accessToken: [] @@ -40,8 +46,8 @@ paths: The token belongs to a known user. examples: application/json: { - "user_id": "@joe:example.org" - } + "user_id": "@joe:example.org" + } schema: type: object required: ["user_id"] @@ -49,5 +55,29 @@ paths: user_id: type: string description: The user id that owns the access token. + 401: + description: + The token is not recongized + examples: + application/json: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecongised access token." + } + schema: + "$ref": "definitions/error.yaml" + 403: + description: + The appservice cannot masquerade the user or has not registered them. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Application service has not registered this user." + } + schema: + "$ref": "definitions/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" tags: - User data From 5285dbc6559bdecc5ffc787fdd7bbccd31757845 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 13:44:20 -0700 Subject: [PATCH 2/5] Add clarifications of /account/whoami to changelog Signed-off-by: Travis Ralston --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 23898e0f..48ac4910 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -23,6 +23,8 @@ Unreleased changes (`#1137 `_). - Clarify that ``m.tag`` ordering is done with numbers, not strings (`#1139 `_). + - Clarify that ``/account/whoami`` should consider application services + (`#1152 `_). - Changes to the API which will be backwards-compatible for clients: From 6ba5d7ca920450d7bdf9bca9223cff7f556b2150 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 14:59:11 -0700 Subject: [PATCH 3/5] Reword appservice requirements for /account/whoami Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index 6bf4f1fb..e56ecb9a 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -31,15 +31,26 @@ paths: description: |- Gets information about the owner of a given access token. - If the owner of the access token is an application service, + If the owner of the access token is an application service, the server should return the user ID making the request. The - server should respect the application service client/server API - extensions during this request. If the request is made for a - virtual user, the server should verify that it is registered. + user ID making the request can be determined by checking to + see if the ``user_id`` query parameter was also supplied. If + the parameter is not present, the default application service + user ID should be used (defined as the ``sender_localpart`` + in the registration). If the parameter is present, the given + user ID should be verified to be both registered and in the + application service's namespace. operationId: getTokenOwner security: - accessToken: [] - parameters: [] + parameters: + # TODO: Break this out to a template or something (and apply it everywhere) + - in: query + name: user_id + type: string + required: false + description: |- + The user ID to masquerade as. Only applies to application services. responses: 200: description: @@ -67,7 +78,7 @@ paths: "$ref": "definitions/error.yaml" 403: description: - The appservice cannot masquerade the user or has not registered them. + The appservice cannot masquerade as the user or has not registered them. examples: application/json: { "errcode": "M_FORBIDDEN", From b7f8f20de9eea1969a31a949a69cebc304e6ee49 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 15:32:49 -0700 Subject: [PATCH 4/5] Reword the appservice portion of /account/whoami Credit goes to richvdh - suggestions taken with edits. Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index e56ecb9a..0ebd0bb7 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -31,26 +31,16 @@ paths: description: |- Gets information about the owner of a given access token. - If the owner of the access token is an application service, - the server should return the user ID making the request. The - user ID making the request can be determined by checking to - see if the ``user_id`` query parameter was also supplied. If - the parameter is not present, the default application service - user ID should be used (defined as the ``sender_localpart`` - in the registration). If the parameter is present, the given - user ID should be verified to be both registered and in the - application service's namespace. + Note that, as with the rest of the Client-Server API, + Application Services may masquerade as users within their + namespace by giving a ``user_id`` query parameter. In this + situation, the server should verify that the given ``user_id`` + is registered by the appservice, and return it in the response + body. operationId: getTokenOwner security: - accessToken: [] - parameters: - # TODO: Break this out to a template or something (and apply it everywhere) - - in: query - name: user_id - type: string - required: false - description: |- - The user ID to masquerade as. Only applies to application services. + parameters: [] responses: 200: description: From 159ab7313f7bab86b1af7e547478f1e73a5abe5a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 6 Mar 2018 15:50:13 -0700 Subject: [PATCH 5/5] Fix typos in whoami.yaml Signed-off-by: Travis Ralston --- api/client-server/whoami.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml index 0ebd0bb7..8f5abdf7 100644 --- a/api/client-server/whoami.yaml +++ b/api/client-server/whoami.yaml @@ -58,11 +58,11 @@ paths: description: The user id that owns the access token. 401: description: - The token is not recongized + The token is not recognised examples: application/json: { "errcode": "M_UNKNOWN_TOKEN", - "error": "Unrecongised access token." + "error": "Unrecognised access token." } schema: "$ref": "definitions/error.yaml"