From c695328d99dd75191f2412358ca3ba6361bce20e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 18 May 2023 22:06:52 -0600 Subject: [PATCH 1/7] Specify MSC3882: Using an existing session to log in another MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/3882 --- content/client-server-api/_index.md | 3 + data/api/client-server/login.yaml | 97 ++++++++++++++++++++++++++++- 2 files changed, 99 insertions(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 798835a00..6c6b874e9 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1176,6 +1176,9 @@ client supports it, the client should redirect the user to the is complete, the client will need to submit a `/login` request matching `m.login.token`. +{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate +a token for their user ID if supported by the homeserver using `POST /login/get_token`. + {{% http-api spec="client-server" api="login" %}} {{% http-api spec="client-server" api="refresh" %}} diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 7c33d1a4e..36b441538 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -42,7 +42,8 @@ paths: examples: application/json: { "flows": [ - {"type": "m.login.password"} + {"type": "m.login.password"}, + {"type": "m.login.token", "get_login_token": true} ] } schema: @@ -54,12 +55,22 @@ paths: items: type: object title: LoginFlow + required: ['type'] properties: type: description: |- The login type. This is supplied as the `type` when logging in. type: string + get_login_token: + type: boolean + x-addedInMatrixVersion: "1.7" + description: |- + If `type` is `m.login.token`, an optional field to indicate + to the unauthenticated client that the homeserver supports + the `POST /login/get_token` endpoint. Note that supporting + the endpoint does not necessarily indicate that the user + attempting to log in will be able to generate such a token. 429: description: This request was rate-limited. schema: @@ -240,3 +251,87 @@ paths: "$ref": "definitions/errors/rate_limited.yaml" tags: - Session management + "/login/get_token": + post: + summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token. + description: |- + Optional endpoint - the server is not required to implement this endpoint if it does not + intend to use or support this functionality. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + An already-authenticated client would call this endpoint to generate a single-use, time-limited, + token for an unauthenticated client to log in with, becoming logged in as the same user which + called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` + login flow with the homeserver. + + Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes + this feature if the server is not offering it. Authenticated clients can check for support on + a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), + while unauthenticated clients can detect server support by looking for an `m.login.token` login + flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). + + In v1.7 of the specification, transmission of the generated token to an unauthenticated client is + left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) + might standarise a way to transmit the token between clients. + + The generated token MUST only be valid for a single login, enforced by the server. Clients which + intend to log in multiple devices must generate a token for each. + + With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt + for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + the user for verification to ensure explicit consent is gained for each additional client. + + Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum + of 1 request per minute. + operationId: generateLoginToken + x-addedInMatrixVersion: "1.7" + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + description: An empty JSON object. + responses: + 200: + description: The login token an unauthenticated client can use to log in as the requesting user. + examples: + application/json: { + "login_token": "", + "expires_in_ms": 120000 + } + schema: + type: object + required: ["login_token", "expires_in_ms"] + properties: + login_token: + type: string + description: The login token for the `m.login.token` login flow. + expires_in_ms: + type: integer + description: |- + The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` + (2 minutes) is recommended as a default. + 400: + description: |- + The request was malformed, or the user does not have an ability to generate tokens for their devices, + as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` + [capability](/client-server-api/#capabilities-negotiation). + schema: + "$ref": "definitions/errors/error.yaml" + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Session management \ No newline at end of file From ce721cde8233c804cb62cdfcb1b85c8dd5131ef6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 18 May 2023 22:09:27 -0600 Subject: [PATCH 2/7] Changelog entries --- changelogs/client_server/newsfragments/1530.feature | 1 + changelogs/client_server/newsfragments/1530.new | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1530.feature create mode 100644 changelogs/client_server/newsfragments/1530.new diff --git a/changelogs/client_server/newsfragments/1530.feature b/changelogs/client_server/newsfragments/1530.feature new file mode 100644 index 000000000..901214391 --- /dev/null +++ b/changelogs/client_server/newsfragments/1530.feature @@ -0,0 +1 @@ +Add an ability to use an existing session to log in another, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new new file mode 100644 index 000000000..bc83260a2 --- /dev/null +++ b/changelogs/client_server/newsfragments/1530.new @@ -0,0 +1 @@ +[`POST /_matrix/client/v3/login/get_token`](/client-server-api/#post_matrixclientv3loginget_token). \ No newline at end of file From 53d0540adb513937558c097bbd14510108c03352 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 19 May 2023 08:20:33 -0600 Subject: [PATCH 3/7] Update data/api/client-server/login.yaml Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- data/api/client-server/login.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 36b441538..25f05d23e 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -260,7 +260,7 @@ paths: This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - An already-authenticated client would call this endpoint to generate a single-use, time-limited, + An already-authenticated client can call this endpoint to generate a single-use, time-limited, token for an unauthenticated client to log in with, becoming logged in as the same user which called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` login flow with the homeserver. From 8248da413c1f2b6b146c5080cc88c461ae322934 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 19 May 2023 12:33:14 -0600 Subject: [PATCH 4/7] Link to endpoint --- data/api/client-server/login.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 25f05d23e..252789f9e 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -68,9 +68,10 @@ paths: description: |- If `type` is `m.login.token`, an optional field to indicate to the unauthenticated client that the homeserver supports - the `POST /login/get_token` endpoint. Note that supporting - the endpoint does not necessarily indicate that the user - attempting to log in will be able to generate such a token. + the [`POST /login/get_token`](/client-server-api/#post_matrixclientv3loginget_token) + endpoint. Note that supporting the endpoint does not + necessarily indicate that the user attempting to log in will + be able to generate such a token. 429: description: This request was rate-limited. schema: From 224cd361614ef4cb5501f92940b6a9a922001cfb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 19 May 2023 12:34:37 -0600 Subject: [PATCH 5/7] Copy/paste `auth` dict definition --- data/api/client-server/login.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 252789f9e..7b5ae502d 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -295,7 +295,12 @@ paths: required: true schema: type: object - description: An empty JSON object. + properties: + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + allOf: + - $ref: "definitions/auth_data.yaml" responses: 200: description: The login token an unauthenticated client can use to log in as the requesting user. From d8888808227ed429c4115f465e5d6ceba033cfb5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 21 May 2023 22:04:38 -0600 Subject: [PATCH 6/7] Move get_token API to the correct version prefix (v1, not v3) --- .../client_server/newsfragments/1530.new | 2 +- content/client-server-api/_index.md | 2 + data/api/client-server/login.yaml | 91 +------------- data/api/client-server/login_token.yaml | 118 ++++++++++++++++++ 4 files changed, 122 insertions(+), 91 deletions(-) create mode 100644 data/api/client-server/login_token.yaml diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new index bc83260a2..6f7c9ebf5 100644 --- a/changelogs/client_server/newsfragments/1530.new +++ b/changelogs/client_server/newsfragments/1530.new @@ -1 +1 @@ -[`POST /_matrix/client/v3/login/get_token`](/client-server-api/#post_matrixclientv3loginget_token). \ No newline at end of file +[`POST /_matrix/client/v3/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 6c6b874e9..620c4b42b 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1181,6 +1181,8 @@ a token for their user ID if supported by the homeserver using `POST /login/get_ {{% http-api spec="client-server" api="login" %}} +{{% http-api spec="client-server" api="login_token" %}} + {{% http-api spec="client-server" api="refresh" %}} {{% http-api spec="client-server" api="logout" %}} diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 7b5ae502d..b62cf2d24 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -68,7 +68,7 @@ paths: description: |- If `type` is `m.login.token`, an optional field to indicate to the unauthenticated client that the homeserver supports - the [`POST /login/get_token`](/client-server-api/#post_matrixclientv3loginget_token) + the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) endpoint. Note that supporting the endpoint does not necessarily indicate that the user attempting to log in will be able to generate such a token. @@ -252,92 +252,3 @@ paths: "$ref": "definitions/errors/rate_limited.yaml" tags: - Session management - "/login/get_token": - post: - summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token. - description: |- - Optional endpoint - the server is not required to implement this endpoint if it does not - intend to use or support this functionality. - - This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - - An already-authenticated client can call this endpoint to generate a single-use, time-limited, - token for an unauthenticated client to log in with, becoming logged in as the same user which - called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` - login flow with the homeserver. - - Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes - this feature if the server is not offering it. Authenticated clients can check for support on - a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), - while unauthenticated clients can detect server support by looking for an `m.login.token` login - flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). - - In v1.7 of the specification, transmission of the generated token to an unauthenticated client is - left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) - might standarise a way to transmit the token between clients. - - The generated token MUST only be valid for a single login, enforced by the server. Clients which - intend to log in multiple devices must generate a token for each. - - With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt - for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt - the user for verification to ensure explicit consent is gained for each additional client. - - Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum - of 1 request per minute. - operationId: generateLoginToken - x-addedInMatrixVersion: "1.7" - security: - - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" - responses: - 200: - description: The login token an unauthenticated client can use to log in as the requesting user. - examples: - application/json: { - "login_token": "", - "expires_in_ms": 120000 - } - schema: - type: object - required: ["login_token", "expires_in_ms"] - properties: - login_token: - type: string - description: The login token for the `m.login.token` login flow. - expires_in_ms: - type: integer - description: |- - The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` - (2 minutes) is recommended as a default. - 400: - description: |- - The request was malformed, or the user does not have an ability to generate tokens for their devices, - as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - - Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` - [capability](/client-server-api/#capabilities-negotiation). - schema: - "$ref": "definitions/errors/error.yaml" - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: - description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - tags: - - Session management \ No newline at end of file diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml new file mode 100644 index 000000000..be0dca8b5 --- /dev/null +++ b/data/api/client-server/login_token.yaml @@ -0,0 +1,118 @@ +# Copyright 2023 The Matrix.org Foundation C.I.C. +# +# 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 Registration and Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/login/get_token": + post: + summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token. + description: |- + Optional endpoint - the server is not required to implement this endpoint if it does not + intend to use or support this functionality. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + An already-authenticated client can call this endpoint to generate a single-use, time-limited, + token for an unauthenticated client to log in with, becoming logged in as the same user which + called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` + login flow with the homeserver. + + Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes + this feature if the server is not offering it. Authenticated clients can check for support on + a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), + while unauthenticated clients can detect server support by looking for an `m.login.token` login + flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). + + In v1.7 of the specification, transmission of the generated token to an unauthenticated client is + left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) + might standarise a way to transmit the token between clients. + + The generated token MUST only be valid for a single login, enforced by the server. Clients which + intend to log in multiple devices must generate a token for each. + + With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt + for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + the user for verification to ensure explicit consent is gained for each additional client. + + Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum + of 1 request per minute. + operationId: generateLoginToken + x-addedInMatrixVersion: "1.7" + security: + - accessToken: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + allOf: + - $ref: "definitions/auth_data.yaml" + responses: + 200: + description: The login token an unauthenticated client can use to log in as the requesting user. + examples: + application/json: { + "login_token": "", + "expires_in_ms": 120000 + } + schema: + type: object + required: ["login_token", "expires_in_ms"] + properties: + login_token: + type: string + description: The login token for the `m.login.token` login flow. + expires_in_ms: + type: integer + description: |- + The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` + (2 minutes) is recommended as a default. + 400: + description: |- + The request was malformed, or the user does not have an ability to generate tokens for their devices, + as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` + [capability](/client-server-api/#capabilities-negotiation). + schema: + "$ref": "definitions/errors/error.yaml" + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Session management From 90a91732e1aeda418187ac4500faf68cef50a32d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 22 May 2023 22:36:59 -0600 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- changelogs/client_server/newsfragments/1530.new | 2 +- content/client-server-api/_index.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new index 6f7c9ebf5..ffe9abd91 100644 --- a/changelogs/client_server/newsfragments/1530.new +++ b/changelogs/client_server/newsfragments/1530.new @@ -1 +1 @@ -[`POST /_matrix/client/v3/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). \ No newline at end of file +[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 620c4b42b..8ebe8f711 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1177,7 +1177,8 @@ is complete, the client will need to submit a `/login` request matching `m.login.token`. {{< added-in v="1.7" >}} Already-authenticated clients can additionally generate -a token for their user ID if supported by the homeserver using `POST /login/get_token`. +a token for their user ID if supported by the homeserver using +[`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). {{% http-api spec="client-server" api="login" %}}