From 6532fed38c9d57566f8a402fd057edbe74268f9d Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 5 Sep 2022 17:28:42 +0100 Subject: [PATCH 01/17] Allow an existing session to sign in a new session --- proposals/xxxx-login-token-request.md | 49 +++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 proposals/xxxx-login-token-request.md diff --git a/proposals/xxxx-login-token-request.md b/proposals/xxxx-login-token-request.md new file mode 100644 index 00000000000..29abacee024 --- /dev/null +++ b/proposals/xxxx-login-token-request.md @@ -0,0 +1,49 @@ +# MSCxxxx: Allow an existing session to sign in a new session + +todo + +## Proposal + +Add a new POST endpoint to the Client-Server API that issues a time limited `m.login.token` token: + +`POST /login/token` + +```json +{ + "login_token": "", + "expires_in": 3600 +} +``` + +This new endpoint MAY be protected by user interactive authentication. + +This token can then be used as per the existing Login spec of the Client-Server API as follows: + +`POST /login` + +```json +{ + "type": "m.login.token", + "token": "" +} +``` + +## Potential issues + +todo + +## Alternatives + +If Matrix was already using OIDC as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) then we could use the device authorization grant flow which allows for a new device to be signed in using an existing device. + +## Security considerations + +A malicious client could use the mechanism to spawn more than one session. For this reason the endpoint can be placed behind user interactive authentication. + +## Unstable prefix + +tbd + +## Dependencies + +None. From 3848ff60171a5fa6c0e5d0f72cc539503afe8010 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 5 Sep 2022 17:29:26 +0100 Subject: [PATCH 02/17] MSC3882 --- ...{xxxx-login-token-request.md => 3882-login-token-request.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-login-token-request.md => 3882-login-token-request.md} (94%) diff --git a/proposals/xxxx-login-token-request.md b/proposals/3882-login-token-request.md similarity index 94% rename from proposals/xxxx-login-token-request.md rename to proposals/3882-login-token-request.md index 29abacee024..342a25f3e02 100644 --- a/proposals/xxxx-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -1,4 +1,4 @@ -# MSCxxxx: Allow an existing session to sign in a new session +# MSC3882: Allow an existing session to sign in a new session todo From f5bc7901b4c21ed93c4ba188cab71a3b63035081 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 6 Sep 2022 09:48:58 +0100 Subject: [PATCH 03/17] Line length --- proposals/3882-login-token-request.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 342a25f3e02..9902279211b 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -34,11 +34,13 @@ todo ## Alternatives -If Matrix was already using OIDC as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) then we could use the device authorization grant flow which allows for a new device to be signed in using an existing device. +If Matrix was already using OIDC as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) then we +could use the device authorization grant flow which allows for a new device to be signed in using an existing device. ## Security considerations -A malicious client could use the mechanism to spawn more than one session. For this reason the endpoint can be placed behind user interactive authentication. +A malicious client could use the mechanism to spawn more than one session. For this reason the endpoint can be placed +behind user interactive authentication. ## Unstable prefix From a081662a0cfa0815a1c03591d23c72097cc57aa9 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 21 Sep 2022 15:47:48 +0100 Subject: [PATCH 04/17] Resolve TODOs --- proposals/3882-login-token-request.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 9902279211b..d4e112d9f7b 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -1,6 +1,11 @@ # MSC3882: Allow an existing session to sign in a new session -todo +In MSCyyyy (to be published) a proposal is made to allow a user to login on a new device using an existing device by means of scanning a +QR code. + +In order to support the above proposal a mechanism is needed where by the new device can obtain a new access token that it can use with the Client-Server API. + +It is proposed that the current `m.login.token` mechanism is extended to allow the issuance of a login token by an existing client session. ## Proposal @@ -30,7 +35,7 @@ This token can then be used as per the existing Login spec of the Client-Server ## Potential issues -todo +None identified. ## Alternatives @@ -44,7 +49,7 @@ behind user interactive authentication. ## Unstable prefix -tbd +None. ## Dependencies From 3682aa18dfcbd8f0117284b7fa2f0382ce2f7c81 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 22 Sep 2022 11:16:57 +0100 Subject: [PATCH 05/17] Document unstable prefixes --- proposals/3882-login-token-request.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index d4e112d9f7b..4d94eb0ece9 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -49,7 +49,22 @@ behind user interactive authentication. ## Unstable prefix -None. +While this feature is in development the new endpoint should be exposed using the following unstable prefix: + +- `/_matrix/client/unstable/org.matrix.msc3882/login/token` + +Additionally, the feature is to be advertised as unstable feature in the `GET /_matrix/client/versions` +response, with the key `org.matrix.msc3882` set to `true`. So, the response could look then as +following: + +```json +{ + "versions": ["r0.6.0"], + "unstable_features": { + "org.matrix.msc3882": true + } +} +``` ## Dependencies From 71294a378e26b90bdb90c5c398bde6f86bfa3f2d Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 23 Sep 2022 13:52:55 +0100 Subject: [PATCH 06/17] Add docs on data returned by request --- proposals/3882-login-token-request.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 4d94eb0ece9..e0e7270d54e 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -22,6 +22,11 @@ Add a new POST endpoint to the Client-Server API that issues a time limited `m.l This new endpoint MAY be protected by user interactive authentication. +The values returned are: + +- `login_token` - required, the token to use with `m.login.token` +- `expires_in` - required, the expiry time for the token in seconds + This token can then be used as per the existing Login spec of the Client-Server API as follows: `POST /login` From cafe8f6d8d8db0a288942f39eb2d31d9aadc1f04 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 13 Oct 2022 11:46:55 +0100 Subject: [PATCH 07/17] Reference to MSC3906 --- proposals/3882-login-token-request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index e0e7270d54e..a24e3441f1e 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -1,6 +1,6 @@ # MSC3882: Allow an existing session to sign in a new session -In MSCyyyy (to be published) a proposal is made to allow a user to login on a new device using an existing device by means of scanning a +In [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) a proposal is made to allow a user to login on a new device using an existing device by means of scanning a QR code. In order to support the above proposal a mechanism is needed where by the new device can obtain a new access token that it can use with the Client-Server API. From f6a0054bc3d7a4159c1bd8b574d753038a44b803 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 9 Mar 2023 22:45:16 +0000 Subject: [PATCH 08/17] Incorporate review feedback --- proposals/3882-login-token-request.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index a24e3441f1e..43312f9fd4b 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -1,11 +1,13 @@ # MSC3882: Allow an existing session to sign in a new session -In [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) a proposal is made to allow a user to login on a new device using an existing device by means of scanning a -QR code. +In [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) a proposal is made to allow a user to login +on a new device using an existing device by means of scanning a QR code. -In order to support the above proposal a mechanism is needed where by the new device can obtain a new access token that it can use with the Client-Server API. +In order to support the above proposal a mechanism is needed where by the new device can obtain a new access token that +it can use with the Client-Server API. -It is proposed that the current `m.login.token` mechanism is extended to allow the issuance of a login token by an existing client session. +It is proposed that the current `m.login.token` mechanism is extended to allow the issuance of a login token by an +existing client session. ## Proposal @@ -16,11 +18,12 @@ Add a new POST endpoint to the Client-Server API that issues a time limited `m.l ```json { "login_token": "", - "expires_in": 3600 + "expires_in": 120 } ``` -This new endpoint MAY be protected by user interactive authentication. +This new endpoint should be protected by user interactive authentication (UIA). However the the homeserver admin may +choose to disable UIA if they deem suitable alternative protections are in place. The values returned are: @@ -49,8 +52,8 @@ could use the device authorization grant flow which allows for a new device to b ## Security considerations -A malicious client could use the mechanism to spawn more than one session. For this reason the endpoint can be placed -behind user interactive authentication. +A malicious client could use the mechanism to spawn more than one session. For this reason the endpoint should by default +be placed behind user interactive authentication. ## Unstable prefix From 02df2bc5f856f57884062722a858aef13915f6bc Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 15 Mar 2023 17:16:01 -0400 Subject: [PATCH 09/17] Apply suggestions from code review Co-authored-by: Travis Ralston --- proposals/3882-login-token-request.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 43312f9fd4b..1b1f62cc8de 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -28,9 +28,9 @@ choose to disable UIA if they deem suitable alternative protections are in place The values returned are: - `login_token` - required, the token to use with `m.login.token` -- `expires_in` - required, the expiry time for the token in seconds +- `expires_in` - required, how long until the token expires in seconds -This token can then be used as per the existing Login spec of the Client-Server API as follows: +This token can then be used as per the existing [Login spec](https://spec.matrix.org/v1.6/client-server-api/#login) as follows: `POST /login` From 3c47a8f973171c034c03f3e7b911352b431b355c Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 15 Mar 2023 17:23:34 -0400 Subject: [PATCH 10/17] Add note on rate limiting --- proposals/3882-login-token-request.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 1b1f62cc8de..872b45833dc 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -25,6 +25,10 @@ Add a new POST endpoint to the Client-Server API that issues a time limited `m.l This new endpoint should be protected by user interactive authentication (UIA). However the the homeserver admin may choose to disable UIA if they deem suitable alternative protections are in place. +It should also be protected by rate-limiting in accordance with the existing +[spec](https://spec.matrix.org/v1.6/client-server-api/#rate-limiting). It may be appropriate for the homeserver admin to +to configure a low limit ("low" relative to other enforced limits). For example, a rate of once per minute could be appropriate. + The values returned are: - `login_token` - required, the token to use with `m.login.token` From d4aea453e9cf54205fc92b16b544f9e853b15aec Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 22 Mar 2023 11:55:38 -0400 Subject: [PATCH 11/17] Revision 1 of proposal - /_matrix/client/v3/login/token => /_matrix/client/v1/login/get_token - expires_in => expires_in_ms - Security clarifications --- proposals/3882-login-token-request.md | 107 ++++++++++++++++++++------ 1 file changed, 84 insertions(+), 23 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 872b45833dc..6f9c8945950 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -11,32 +11,42 @@ existing client session. ## Proposal -Add a new POST endpoint to the Client-Server API that issues a time limited `m.login.token` token: +Add a new POST endpoint to the Client-Server API that issues a single-use, time-limited `m.login.token` token: -`POST /login/token` +`POST /_matrix/client/v1/login/get_token` + +The client should send an empty JSON body for the `POST` request. + +As detailed in the security selection below, this new endpoint should be protected by user interactive authentication +(UIA) as detailed in the existing +["User-interactive API in the REST API"](https://spec.matrix.org/v1.5/client-server-api/#user-interactive-api-in-the-rest-api) +section of the spec. + +Once UIA has been completed a `200` response with JSON body is returned. The body contains the following fields: + +- `login_token` - required, the token to use with `m.login.token` +- `expires_in_ms` - required, how long until the token expires in milliseconds + +An example response is as follows: + +```http +HTTP/1.1 200 OK +Content-Type: application/json +``` ```json { "login_token": "", - "expires_in": 120 + "expires_in_ms": 120000 } ``` -This new endpoint should be protected by user interactive authentication (UIA). However the the homeserver admin may -choose to disable UIA if they deem suitable alternative protections are in place. - -It should also be protected by rate-limiting in accordance with the existing -[spec](https://spec.matrix.org/v1.6/client-server-api/#rate-limiting). It may be appropriate for the homeserver admin to -to configure a low limit ("low" relative to other enforced limits). For example, a rate of once per minute could be appropriate. - -The values returned are: - -- `login_token` - required, the token to use with `m.login.token` -- `expires_in` - required, how long until the token expires in seconds - This token can then be used as per the existing [Login spec](https://spec.matrix.org/v1.6/client-server-api/#login) as follows: -`POST /login` +```http +POST /_matrix/client/v3/login HTTP/1.1 +Content-Type: application/json +``` ```json { @@ -56,28 +66,79 @@ could use the device authorization grant flow which allows for a new device to b ## Security considerations -A malicious client could use the mechanism to spawn more than one session. For this reason the endpoint should by default -be placed behind user interactive authentication. +A malicious client could use the mechanism to spawn more than one session. The following mitigations should be applied: + +1. The homeserver must only allow the token to be used for a single login. If the user wishes to sign in multiple + additional clients a token must be issued for each client. + +2. The homeserver should enforce +[user interactive authentication](https://spec.matrix.org/v1.6/client-server-api/#user-interactive-authentication-api) +by default for the new endpoint. The purpose being that consent is obtained from the user for each additional client. + +3. The homeserver should enforce rate-limiting in accordance with the existing +[spec](https://spec.matrix.org/v1.6/client-server-api/#rate-limiting). It may be appropriate for the homeserver admin to +to configure a low limit ("low" relative to other enforced limits). For example, a rate of once per minute could be appropriate. + +If a homeserver admin deems that they have a suitable alternative to UIA in place, they can make use of +["dummy auth"](https://spec.matrix.org/v1.6/client-server-api/#dummy-auth) and have the homeserver respond with a response similar to: + +```http +HTTP/1.1 401 Unauthorized +Content-Type: application/json +``` + +```json +{ + "flows": [ + { + "stages": ["m.login.dummy"] + } + ], + "params": {}, + "session": "xxxxxx" +} +``` + +The client can then complete UIA without requiring action from the user by sending the following JSON request body: + +```http +POST /_matrix/client/v1/login/get_token HTTP/1.1 +Content-Type: application/json +``` + +```json +{ + "auth": { + "type": "m.login.dummy", + "session": "xxxxxx" + } +} +``` ## Unstable prefix While this feature is in development the new endpoint should be exposed using the following unstable prefix: -- `/_matrix/client/unstable/org.matrix.msc3882/login/token` +- `/_matrix/client/unstable/org.matrix.msc3882/login/get_token` -Additionally, the feature is to be advertised as unstable feature in the `GET /_matrix/client/versions` -response, with the key `org.matrix.msc3882` set to `true`. So, the response could look then as -following: +Additionally, the feature is to be advertised as unstable feature in the `GET /_matrix/client/versions` response, with +the key `org.matrix.msc3882.r1` set to `true`. (The `r1` in the feature name is used to indicate that the server implements the first revision of this proposal) + +So, the response could look then as following: ```json { "versions": ["r0.6.0"], "unstable_features": { - "org.matrix.msc3882": true + "org.matrix.msc3882.r1": true } } ``` +For reference - an earlier iteration of this proposal used an unstable prefix of +`/_matrix/client/unstable/org.matrix.msc3882/login/token` with an unstable feature advertised as `org.matrix.msc3882` +set to `true`. + ## Dependencies None. From 3a44d2940318314f88e7de7c9a45fada3b5b0f44 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 22 Mar 2023 13:55:06 -0400 Subject: [PATCH 12/17] Update proposals/3882-login-token-request.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3882-login-token-request.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 6f9c8945950..057f707ec58 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -15,7 +15,8 @@ Add a new POST endpoint to the Client-Server API that issues a single-use, time- `POST /_matrix/client/v1/login/get_token` -The client should send an empty JSON body for the `POST` request. +The client should send an empty JSON object for the body of the `POST` request (apart from +the `auth` property used in user-interactive authentication). As detailed in the security selection below, this new endpoint should be protected by user interactive authentication (UIA) as detailed in the existing From 07ca77093cf970aac35dbac6d92f51e0602df074 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 22 Mar 2023 13:55:41 -0400 Subject: [PATCH 13/17] Refer to spec about not requiring auth --- proposals/3882-login-token-request.md | 39 ++++----------------------- 1 file changed, 5 insertions(+), 34 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 6f9c8945950..0aeb1bd81c4 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -79,41 +79,12 @@ by default for the new endpoint. The purpose being that consent is obtained from [spec](https://spec.matrix.org/v1.6/client-server-api/#rate-limiting). It may be appropriate for the homeserver admin to to configure a low limit ("low" relative to other enforced limits). For example, a rate of once per minute could be appropriate. -If a homeserver admin deems that they have a suitable alternative to UIA in place, they can make use of -["dummy auth"](https://spec.matrix.org/v1.6/client-server-api/#dummy-auth) and have the homeserver respond with a response similar to: +n.b. A homeserver admin may deem that they have suitable protections in place and offer the endpoint without UIA auth as described +in the existing spec: -```http -HTTP/1.1 401 Unauthorized -Content-Type: application/json -``` - -```json -{ - "flows": [ - { - "stages": ["m.login.dummy"] - } - ], - "params": {}, - "session": "xxxxxx" -} -``` - -The client can then complete UIA without requiring action from the user by sending the following JSON request body: - -```http -POST /_matrix/client/v1/login/get_token HTTP/1.1 -Content-Type: application/json -``` - -```json -{ - "auth": { - "type": "m.login.dummy", - "session": "xxxxxx" - } -} -``` +> A request to an endpoint that uses User-Interactive Authentication never succeeds without auth. Homeservers may allow requests +> that don’t require auth by offering a stage with only the m.login.dummy auth type, but they must still give a 401 response to +> requests with no auth data. ## Unstable prefix From 090efd8417cd4a098bbec2642e6e9f149deaa3fc Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 23 Mar 2023 17:33:32 +0000 Subject: [PATCH 14/17] Expose availability via capabilities --- proposals/3882-login-token-request.md | 38 ++++++++++++++++----------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 591e189fa61..e35d0713ab0 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -11,7 +11,7 @@ existing client session. ## Proposal -Add a new POST endpoint to the Client-Server API that issues a single-use, time-limited `m.login.token` token: +Add a new optional POST endpoint to the Client-Server API that issues a single-use, time-limited `m.login.token` token: `POST /_matrix/client/v1/login/get_token` @@ -56,6 +56,24 @@ Content-Type: application/json } ``` +The availability of the new API endpoint should be determined via a new `m.get_logintoken` +[capability](https://spec.matrix.org/v1.6/client-server-api/#capabilities-negotiation). + +This capability has a single flag, `enabled`, to denote whether the `/login/get_token` API is available or not. +Cases for disabling might include security restrictions imposed by the homeserver admin. + +An example of the capability API’s response for this capability is: + +```json +{ + "capabilities": { + "m.get_logintoken": { + "enabled": true + } + } +} +``` + ## Potential issues None identified. @@ -93,23 +111,13 @@ While this feature is in development the new endpoint should be exposed using th - `/_matrix/client/unstable/org.matrix.msc3882/login/get_token` -Additionally, the feature is to be advertised as unstable feature in the `GET /_matrix/client/versions` response, with -the key `org.matrix.msc3882.r1` set to `true`. (The `r1` in the feature name is used to indicate that the server implements the first revision of this proposal) - -So, the response could look then as following: +The capability should use the unstable prefix: -```json -{ - "versions": ["r0.6.0"], - "unstable_features": { - "org.matrix.msc3882.r1": true - } -} -``` +- `org.matrix.msc3882.get_logintoken` -For reference - an earlier iteration of this proposal used an unstable prefix of +For reference - an earlier revision of this proposal used an unstable prefix of `/_matrix/client/unstable/org.matrix.msc3882/login/token` with an unstable feature advertised as `org.matrix.msc3882` -set to `true`. +set to `true`. This may be referred to as "revision zero" in existing implementations. ## Dependencies From 1c8db5b7fe13de04b2d82fcdfdac6e8aee80bf18 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 24 Mar 2023 06:54:19 -0400 Subject: [PATCH 15/17] Update proposals/3882-login-token-request.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3882-login-token-request.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index e35d0713ab0..02046aa0c1f 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -116,7 +116,8 @@ The capability should use the unstable prefix: - `org.matrix.msc3882.get_logintoken` For reference - an earlier revision of this proposal used an unstable prefix of -`/_matrix/client/unstable/org.matrix.msc3882/login/token` with an unstable feature advertised as `org.matrix.msc3882` +`/_matrix/client/unstable/org.matrix.msc3882/login/token` with an unstable feature advertised +in the response to `GET /_matrix/client/versions` as `org.matrix.msc3882` set to `true`. This may be referred to as "revision zero" in existing implementations. ## Dependencies From b75b14f0eb3b6584ebb939244f2279bba068d285 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 31 Mar 2023 17:33:37 +0100 Subject: [PATCH 16/17] Use GET /login when unauthenticated --- proposals/3882-login-token-request.md | 74 +++++++++++++++++++++++---- 1 file changed, 63 insertions(+), 11 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 02046aa0c1f..4811495d39b 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -11,6 +11,8 @@ existing client session. ## Proposal +### New API endpoint POST /login/get_token + Add a new optional POST endpoint to the Client-Server API that issues a single-use, time-limited `m.login.token` token: `POST /_matrix/client/v1/login/get_token` @@ -56,18 +58,70 @@ Content-Type: application/json } ``` -The availability of the new API endpoint should be determined via a new `m.get_logintoken` -[capability](https://spec.matrix.org/v1.6/client-server-api/#capabilities-negotiation). +### Determining the availability of the new API endpoint + +As this new API endpoint is optional, clients should determine whether the endpoint is available +before prompting the user to try using it. + +There are two usage scenarios to consider: + +1. The user wishes to sign in on a Matrix client. +2. The user wishes to use an already signed in Matrix client to sign in another client. + +In scenario 2 the client is already authenticated. For scenario 1 the client is not yet authenticated. + +#### Scenario 1: The user wishes to sign in on a Matrix client -This capability has a single flag, `enabled`, to denote whether the `/login/get_token` API is available or not. -Cases for disabling might include security restrictions imposed by the homeserver admin. +The client wants to determine if it *may* be possible to sign in by getting a login token from an +existing session. + +It is proposed that the unauthenticated client can determine if the new API endpoint *may* be available +as part of the existing +[`GET /_matrix/client/v3/login`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientv3login) +API endpoint. + +As the `m.login.token` mechanism is used to redeem the login token, the client can first determine if the +`m.login.token` is advertised as a flow in the `GET /_matrix/client/v3/login` response. Then it can check a +new boolean field `get_login_token` to determine if the capability *may* be available. + +An example of the proposed `GET /_matrix/client/v3/login` response is: + +```json +{ + "flow": [ + { + "type": "m.login.token", + "get_login_token": true + } + ] +} +``` + +In this case the mechanism could be available and so the client could prompt the user to try using it. + +#### Scenario 2: The user wishes to use an already signed in Matrix client to sign in another client + +The client is already authenticated. The client can determine whether it is able and allowed to sign in +another client by checking the +[capabilities](https://spec.matrix.org/v1.6/client-server-api/#capabilities-negotiation) +advertised by the homeserver. + +Where the client is authenticated the client can determine whether the new API endpoint is available +via the [capability negotiation](https://spec.matrix.org/v1.6/client-server-api/#capabilities-negotiation) +mechanism. + +The homeserver can then decide on a per user basis if the capability is available or not. For example, +it could implement a policy based on some risk criteria around the user’s account, session, or device. + +A new capability `m.get_login_token` is proposed. This capability has a single boolean flag, `enabled`, to +denote whether the `/login/get_token` API is available or not. An example of the capability API’s response for this capability is: ```json { "capabilities": { - "m.get_logintoken": { + "m.get_login_token": { "enabled": true } } @@ -107,13 +161,11 @@ in the existing spec: ## Unstable prefix -While this feature is in development the new endpoint should be exposed using the following unstable prefix: - -- `/_matrix/client/unstable/org.matrix.msc3882/login/get_token` - -The capability should use the unstable prefix: +While this feature is in development the following unstable prefixes should be used: -- `org.matrix.msc3882.get_logintoken` +- API endpoint `/_matrix/client/v1/login/get_token` => `/_matrix/client/unstable/org.matrix.msc3882/login/get_token` +- capability `m.get_login_token` => `org.matrix.msc3882.get_login_token` +- login flow field `get_login_token` => `org.matrix.msc3882.get_login_token` For reference - an earlier revision of this proposal used an unstable prefix of `/_matrix/client/unstable/org.matrix.msc3882/login/token` with an unstable feature advertised From b9baebf05ce7ddd5586edcc69663e59a728412b4 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Tue, 25 Apr 2023 13:14:29 -0400 Subject: [PATCH 17/17] Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/3882-login-token-request.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3882-login-token-request.md b/proposals/3882-login-token-request.md index 4811495d39b..7372ad97c1d 100644 --- a/proposals/3882-login-token-request.md +++ b/proposals/3882-login-token-request.md @@ -106,7 +106,7 @@ another client by checking the [capabilities](https://spec.matrix.org/v1.6/client-server-api/#capabilities-negotiation) advertised by the homeserver. -Where the client is authenticated the client can determine whether the new API endpoint is available +The unauthenticated client can also determine whether the new API endpoint is available via the [capability negotiation](https://spec.matrix.org/v1.6/client-server-api/#capabilities-negotiation) mechanism. @@ -167,7 +167,7 @@ While this feature is in development the following unstable prefixes should be u - capability `m.get_login_token` => `org.matrix.msc3882.get_login_token` - login flow field `get_login_token` => `org.matrix.msc3882.get_login_token` -For reference - an earlier revision of this proposal used an unstable prefix of +For reference - an earlier revision of this proposal used an unstable endpoint of `/_matrix/client/unstable/org.matrix.msc3882/login/token` with an unstable feature advertised in the response to `GET /_matrix/client/versions` as `org.matrix.msc3882` set to `true`. This may be referred to as "revision zero" in existing implementations.