From 0dd330962d7bf54e65737d5ca0e5f9a074c237e3 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 3 Jul 2018 14:14:26 -0400 Subject: [PATCH 1/6] initial draft of .well-known discovery --- .../definitions/wellknown/homeserver.yaml | 23 ++++++ .../definitions/wellknown/homeserver.yaml~ | 23 ++++++ .../wellknown/identity_server.yaml | 23 ++++++ api/client-server/wellknown.yaml | 63 ++++++++++++++++ specification/client_server_api.rst | 72 +++++++++++++++++++ 5 files changed, 204 insertions(+) create mode 100644 api/client-server/definitions/wellknown/homeserver.yaml create mode 100644 api/client-server/definitions/wellknown/homeserver.yaml~ create mode 100644 api/client-server/definitions/wellknown/identity_server.yaml create mode 100644 api/client-server/wellknown.yaml diff --git a/api/client-server/definitions/wellknown/homeserver.yaml b/api/client-server/definitions/wellknown/homeserver.yaml new file mode 100644 index 00000000..7efba816 --- /dev/null +++ b/api/client-server/definitions/wellknown/homeserver.yaml @@ -0,0 +1,23 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Homeserver Information +description: |- + Used by clients to discover homeserver information. +type: object +properties: + base_url: + type: string + description: The base URL for the homeserver for client-server connections. +required: + - base_url diff --git a/api/client-server/definitions/wellknown/homeserver.yaml~ b/api/client-server/definitions/wellknown/homeserver.yaml~ new file mode 100644 index 00000000..e42dfbf3 --- /dev/null +++ b/api/client-server/definitions/wellknown/homeserver.yaml~ @@ -0,0 +1,23 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Authentication Data +description: |- + Used by clients to submit authentication information to the interactive-authentication API +type: object +properties: + base_url: + type: string + description: The base URL for the homeserver for client-server connections. +required: + - base_url diff --git a/api/client-server/definitions/wellknown/identity_server.yaml b/api/client-server/definitions/wellknown/identity_server.yaml new file mode 100644 index 00000000..eb0e0baf --- /dev/null +++ b/api/client-server/definitions/wellknown/identity_server.yaml @@ -0,0 +1,23 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +title: Identity Server Information +description: |- + Used by clients to discover identity server information. +type: object +properties: + base_url: + type: string + description: The base URL for the identity server for client-server connections. +required: + - base_url diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml new file mode 100644 index 00000000..44d9ef73 --- /dev/null +++ b/api/client-server/wellknown.yaml @@ -0,0 +1,63 @@ +# Copyright 2018 New Vector Ltd +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server server discovery API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https +basePath: /.well-known +produces: + - application/json +paths: + "/matrix/client": + get: + summary: Gets Matrix server discovery information about the domain. + description: |- + Gets discovery information about the domain. The file may include + additional keys, which SHOULD follow the Java package naming convention, + e.g. ``com.example.myapp.property``. This ensures property names are + suitably namespaced for each application and reduces the risk of + clashes. + + **FIXME:** do we need to add a note that this endpoint is not + necessarily handled by the homeserver, but by another webserver? Or + does the context make this clear enough? + operationId: getWellknown + responses: + 200: + description: Server discovery information + examples: + application/json: { + "m.homeserver": { + "base_url": "https://matrix.example.com" + }, + "m.identity_server": { + "base_url": "https://identity.example.com" + } + } + schema: + type: object + properties: + m.homeserver: + description: Information about the homeserver to connect to. + "$ref": "definitions/wellknown/homeserver.yaml" + m.identity_server: + description: Information about the identity server to connect to. + "$ref": "definitions/wellknown/identity_server.yaml" + 404: + description: No server discovery information available + tags: + - Server administration diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index dec3a4f4..e0befddf 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -164,6 +164,78 @@ recommended. {{versions_cs_http_api}} +Server Discovery +~~~~~~~~~~~~~~~~ + +In order to allow users to connect to a Matrix server without needing to +explicitly specify the homeserver's URL or other parameters, clients may use an +auto-discovery mechanism to determine the server's URL based on a user's +Matrix ID. Auto-discovery should only be done at login time, with the +discovered values retained for the duration of the user's session. + +In this section, the following terms are used with specific meanings: + +``PROMPT`` + Retrieve the specific piece of information from the user in a way which + fits within the existing client UX, if the client is inclined to do so. + Failure can take place instead if no good UX is possible at this point. + +``IGNORE`` + Stop the current auto-discovery mechanism. If no more auto-discovery + mechanisms are available, then the client may use other methods of + determining the required parameters, such as prompting the user, or using + default values. + +``FAIL_PROMPT`` + Inform the user that auto-discovery failed due to invalid/empty data and + ``PROMPT`` for the parameter. + +``FAIL_ERROR`` + Inform the user that auto-discovery did not return any usable URLs. Do not + continue further with the current login process. At this point, valid data + was obtained, but no homeserver is available to serve the client. No further + guess should be attempted and the user should make a conscientious decision + what to do next. + +Well-known URI +++++++++++++++ + +The ``.well-known`` method uses a JSON file at a predetermined location to +specify parameter values. The flow for this method is as follows: + +1. Extract the server name from the user's Matrix ID by splitting the Matrix ID + at the first colon. +2. Extract the DNS name from the server name. +3. Make a GET request to ``https://dns_name/.well-known/matrix/client``. + + a. If the returned status code is 404, then ``IGNORE``. + b. If the returned status code is not 200, or the response body is empty, + then ``FAIL_PROMPT``. + c. Parse the response body as a JSON object + + i. If the content cannot be parsed, then ``FAIL_PROMPT``. + + d. Extract the ``base_url`` value from the ``m.homeserver`` property. This + value is to be used as the base URL of the homeserver. + + i. If this value is not provided, then ``FAIL_PROMPT``. + + e. Validate the homeserver base URL: + + i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. + ii. Clients should validate that the URL points to a valid homeserver + before accepting it. Currently, the suggested way of validating is + to connect to the ``/_matrix/client/versions`` endpoint, and to parse + and validate the data. If any step in the validation fails, then + ``FAIL_ERROR``. + + f. If the ``m.identity_server`` property is present, extract the + ``base_url`` value for use as the base URL of the identity server. This + value can be validated as in the step above, but using + ``/_matrix/identity/api/v1``. + +{{wellknown_cs_http_api}} + Client Authentication --------------------- From 5bc29eb11c5c07c47e6fb4afe0c7c1caba12cbf2 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 4 Jul 2018 17:01:35 -0400 Subject: [PATCH 2/6] remove accidentally-committed backup file --- .../definitions/wellknown/homeserver.yaml~ | 23 ------------------- 1 file changed, 23 deletions(-) delete mode 100644 api/client-server/definitions/wellknown/homeserver.yaml~ diff --git a/api/client-server/definitions/wellknown/homeserver.yaml~ b/api/client-server/definitions/wellknown/homeserver.yaml~ deleted file mode 100644 index e42dfbf3..00000000 --- a/api/client-server/definitions/wellknown/homeserver.yaml~ +++ /dev/null @@ -1,23 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -title: Authentication Data -description: |- - Used by clients to submit authentication information to the interactive-authentication API -type: object -properties: - base_url: - type: string - description: The base URL for the homeserver for client-server connections. -required: - - base_url From ce1e2c0904a793b25527e88e060e0d0f6809cc1f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 4 Jul 2018 17:58:37 -0400 Subject: [PATCH 3/6] incorporate feedback from reviewers --- api/client-server/wellknown.yaml | 13 +++++++----- changelogs/client_server.rst | 4 ++++ specification/client_server_api.rst | 31 ++++++++++++++++------------- 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml index 44d9ef73..8d19f38a 100644 --- a/api/client-server/wellknown.yaml +++ b/api/client-server/wellknown.yaml @@ -27,14 +27,13 @@ paths: summary: Gets Matrix server discovery information about the domain. description: |- Gets discovery information about the domain. The file may include - additional keys, which SHOULD follow the Java package naming convention, + additional keys, which MUST follow the Java package naming convention, e.g. ``com.example.myapp.property``. This ensures property names are suitably namespaced for each application and reduces the risk of clashes. - **FIXME:** do we need to add a note that this endpoint is not - necessarily handled by the homeserver, but by another webserver? Or - does the context make this clear enough? + Note that this endpoint is not necessarily handled by the homeserver, + but by another webserver, to be used for discovering the homeserver URL. operationId: getWellknown responses: 200: @@ -55,8 +54,12 @@ paths: description: Information about the homeserver to connect to. "$ref": "definitions/wellknown/homeserver.yaml" m.identity_server: - description: Information about the identity server to connect to. + description: Optional. Information about the identity server to connect to. "$ref": "definitions/wellknown/identity_server.yaml" + additionalProperties: + description: Application-dependent keys using Java package naming convention. + required: + - m.homeserver 404: description: No server discovery information available tags: diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index feabecab..c6eb740a 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -16,6 +16,10 @@ Unreleased changes - Add sticker message event definition. (`#1158 `_). + - Server discovery: + - Add ``.well-known`` discovery method + (`#1359 `_). + - Spec clarifications: - Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index e0befddf..fbeb87cb 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -168,17 +168,17 @@ Server Discovery ~~~~~~~~~~~~~~~~ In order to allow users to connect to a Matrix server without needing to -explicitly specify the homeserver's URL or other parameters, clients may use an -auto-discovery mechanism to determine the server's URL based on a user's -Matrix ID. Auto-discovery should only be done at login time, with the -discovered values retained for the duration of the user's session. +explicitly specify the homeserver's URL or other parameters, clients SHOULD use +an auto-discovery mechanism to determine the server's URL based on a user's +Matrix ID. Auto-discovery should only be done at login time. In this section, the following terms are used with specific meanings: ``PROMPT`` Retrieve the specific piece of information from the user in a way which - fits within the existing client UX, if the client is inclined to do so. - Failure can take place instead if no good UX is possible at this point. + fits within the existing client user experience, if the client is inclined to + do so. Failure can take place instead if no good user experience for this is + possible at this point. ``IGNORE`` Stop the current auto-discovery mechanism. If no more auto-discovery @@ -223,16 +223,19 @@ specify parameter values. The flow for this method is as follows: e. Validate the homeserver base URL: i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. - ii. Clients should validate that the URL points to a valid homeserver - before accepting it. Currently, the suggested way of validating is - to connect to the ``/_matrix/client/versions`` endpoint, and to parse - and validate the data. If any step in the validation fails, then - ``FAIL_ERROR``. + ii. Clients SHOULD validate that the URL points to a valid homeserver + before accepting it by connecting to the ``/_matrix/client/versions`` + endpoint, and parsing and validating the data. If any step in the + validation fails, then ``FAIL_ERROR``. Validation is done as a simple + check against configuration errors, before sending sensitive + information such as a user's password to the server. f. If the ``m.identity_server`` property is present, extract the - ``base_url`` value for use as the base URL of the identity server. This - value can be validated as in the step above, but using - ``/_matrix/identity/api/v1``. + ``base_url`` value for use as the base URL of the identity server. + Validation for this URL is done as in the step above, but using + ``/_matrix/identity/api/v1`` as the endpoint to connect to. If the + ``m.identity_server`` property is present, but does not have a + ``base_url`` value, then ``FAIL_ERROR``. {{wellknown_cs_http_api}} From fcca80dad8329332733a23038a9840db397af4c8 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 14 Aug 2018 17:58:57 -0400 Subject: [PATCH 4/6] various minor fixes - formatting fixes - add examples to homeserver/identity server discovery schema - replace DNS name with hostname --- .../definitions/wellknown/homeserver.yaml | 7 ++++--- .../definitions/wellknown/identity_server.yaml | 7 ++++--- api/client-server/wellknown.yaml | 8 ++++---- specification/client_server_api.rst | 14 +++++++------- 4 files changed, 19 insertions(+), 17 deletions(-) diff --git a/api/client-server/definitions/wellknown/homeserver.yaml b/api/client-server/definitions/wellknown/homeserver.yaml index 7efba816..92ff34ed 100644 --- a/api/client-server/definitions/wellknown/homeserver.yaml +++ b/api/client-server/definitions/wellknown/homeserver.yaml @@ -16,8 +16,9 @@ description: |- Used by clients to discover homeserver information. type: object properties: - base_url: - type: string - description: The base URL for the homeserver for client-server connections. + base_url: + type: string + description: The base URL for the homeserver for client-server connections. + example: https://matrix.example.com required: - base_url diff --git a/api/client-server/definitions/wellknown/identity_server.yaml b/api/client-server/definitions/wellknown/identity_server.yaml index eb0e0baf..a8f7c31c 100644 --- a/api/client-server/definitions/wellknown/identity_server.yaml +++ b/api/client-server/definitions/wellknown/identity_server.yaml @@ -16,8 +16,9 @@ description: |- Used by clients to discover identity server information. type: object properties: - base_url: - type: string - description: The base URL for the identity server for client-server connections. + base_url: + type: string + description: The base URL for the identity server for client-server connections. + example: https://identity.example.com required: - base_url diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml index 8d19f38a..24e190f9 100644 --- a/api/client-server/wellknown.yaml +++ b/api/client-server/wellknown.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Client-Server server discovery API" + title: "Matrix Client-Server Server Discovery API" version: "1.0.0" host: localhost:8008 schemes: @@ -26,7 +26,7 @@ paths: get: summary: Gets Matrix server discovery information about the domain. description: |- - Gets discovery information about the domain. The file may include + Gets discovery information about the domain. The file may include additional keys, which MUST follow the Java package naming convention, e.g. ``com.example.myapp.property``. This ensures property names are suitably namespaced for each application and reduces the risk of @@ -37,7 +37,7 @@ paths: operationId: getWellknown responses: 200: - description: Server discovery information + description: Server discovery information. examples: application/json: { "m.homeserver": { @@ -61,6 +61,6 @@ paths: required: - m.homeserver 404: - description: No server discovery information available + description: No server discovery information available. tags: - Server administration diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6d564524..d2b7aa61 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -219,12 +219,12 @@ Well-known URI ++++++++++++++ The ``.well-known`` method uses a JSON file at a predetermined location to -specify parameter values. The flow for this method is as follows: +specify parameter values. The flow for this method is as follows: 1. Extract the server name from the user's Matrix ID by splitting the Matrix ID at the first colon. -2. Extract the DNS name from the server name. -3. Make a GET request to ``https://dns_name/.well-known/matrix/client``. +2. Extract the hostname from the server name. +3. Make a GET request to ``https://hostname/.well-known/matrix/client``. a. If the returned status code is 404, then ``IGNORE``. b. If the returned status code is not 200, or the response body is empty, @@ -233,17 +233,17 @@ specify parameter values. The flow for this method is as follows: i. If the content cannot be parsed, then ``FAIL_PROMPT``. - d. Extract the ``base_url`` value from the ``m.homeserver`` property. This + d. Extract the ``base_url`` value from the ``m.homeserver`` property. This value is to be used as the base URL of the homeserver. i. If this value is not provided, then ``FAIL_PROMPT``. e. Validate the homeserver base URL: - i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. + i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. ii. Clients SHOULD validate that the URL points to a valid homeserver before accepting it by connecting to the ``/_matrix/client/versions`` - endpoint, and parsing and validating the data. If any step in the + endpoint, and parsing and validating the data. If any step in the validation fails, then ``FAIL_ERROR``. Validation is done as a simple check against configuration errors, before sending sensitive information such as a user's password to the server. @@ -251,7 +251,7 @@ specify parameter values. The flow for this method is as follows: f. If the ``m.identity_server`` property is present, extract the ``base_url`` value for use as the base URL of the identity server. Validation for this URL is done as in the step above, but using - ``/_matrix/identity/api/v1`` as the endpoint to connect to. If the + ``/_matrix/identity/api/v1`` as the endpoint to connect to. If the ``m.identity_server`` property is present, but does not have a ``base_url`` value, then ``FAIL_ERROR``. From a264120b387a52d8506057148b681d1faf938c1c Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 14 Aug 2018 18:06:03 -0400 Subject: [PATCH 5/6] put server discovery as its own section --- specification/client_server_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index d2b7aa61..d775f2c0 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -183,7 +183,7 @@ headers to be returned by servers on all requests are: Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization Server Discovery -~~~~~~~~~~~~~~~~ +---------------- In order to allow users to connect to a Matrix server without needing to explicitly specify the homeserver's URL or other parameters, clients SHOULD use @@ -216,7 +216,7 @@ In this section, the following terms are used with specific meanings: what to do next. Well-known URI -++++++++++++++ +~~~~~~~~~~~~~~ The ``.well-known`` method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows: From 6612dbecf182399af05403bc60097819382476ab Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 17 Aug 2018 11:54:14 -0400 Subject: [PATCH 6/6] tweak wording for validation --- specification/client_server_api.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index d775f2c0..1a566aa0 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -242,11 +242,13 @@ specify parameter values. The flow for this method is as follows: i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``. ii. Clients SHOULD validate that the URL points to a valid homeserver - before accepting it by connecting to the ``/_matrix/client/versions`` - endpoint, and parsing and validating the data. If any step in the - validation fails, then ``FAIL_ERROR``. Validation is done as a simple - check against configuration errors, before sending sensitive - information such as a user's password to the server. + before accepting it by connecting to the |/_matrix/client/versions|_ + endpoint, ensuring that it does not return an error, and parsing and + validating that the data conforms with the expected response + format. If any step in the validation fails, then + ``FAIL_ERROR``. Validation is done as a simple check against + configuration errors, in order to ensure that the discovered address + points to a valid homeserver. f. If the ``m.identity_server`` property is present, extract the ``base_url`` value for use as the base URL of the identity server. @@ -1649,5 +1651,8 @@ have to wait in milliseconds before they can try again. .. |/user//account_data/| replace:: ``/user//account_data/`` .. _/user//account_data/: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type +.. |/_matrix/client/versions| replace:: ``/_matrix/client/versions`` +.. _/_matrix/client/versions: #get-matrix-client-versions + .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types