Skip to content

Commit 6496d37

Browse files
turt2liverichvdh
turt2live
and
richvdh
authored
Specify MSC3882: Using an existing session to log in another (#1530)
* Specify MSC3882: Using an existing session to log in another MSC: matrix-org/matrix-spec-proposals#3882 * Changelog entries * Update data/api/client-server/login.yaml Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Link to endpoint * Copy/paste `auth` dict definition * Move get_token API to the correct version prefix (v1, not v3) * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
1 parent cad4f78 commit 6496d37

File tree

5 files changed

+139
-1
lines changed

5 files changed

+139
-1
lines changed

‎changelogs/client_server/newsfragments/1530.feature

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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).

‎changelogs/client_server/newsfragments/1530.new

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).

‎content/client-server-api/_index.md

+6
Original file line numberDiff line numberDiff line change
@@ -1176,8 +1176,14 @@ client supports it, the client should redirect the user to the
11761176
is complete, the client will need to submit a `/login` request matching
11771177
`m.login.token`.
11781178

1179+
{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
1180+
a token for their user ID if supported by the homeserver using
1181+
[`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
1182+
11791183
{{% http-api spec="client-server" api="login" %}}
11801184

1185+
{{% http-api spec="client-server" api="login_token" %}}
1186+
11811187
{{% http-api spec="client-server" api="refresh" %}}
11821188

11831189
{{% http-api spec="client-server" api="logout" %}}

‎data/api/client-server/login.yaml

+13-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ paths:
4242
examples:
4343
application/json: {
4444
"flows": [
45-
{"type": "m.login.password"}
45+
{"type": "m.login.password"},
46+
{"type": "m.login.token", "get_login_token": true}
4647
]
4748
}
4849
schema:
@@ -54,12 +55,23 @@ paths:
5455
items:
5556
type: object
5657
title: LoginFlow
58+
required: ['type']
5759
properties:
5860
type:
5961
description: |-
6062
The login type. This is supplied as the `type` when
6163
logging in.
6264
type: string
65+
get_login_token:
66+
type: boolean
67+
x-addedInMatrixVersion: "1.7"
68+
description: |-
69+
If `type` is `m.login.token`, an optional field to indicate
70+
to the unauthenticated client that the homeserver supports
71+
the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token)
72+
endpoint. Note that supporting the endpoint does not
73+
necessarily indicate that the user attempting to log in will
74+
be able to generate such a token.
6375
429:
6476
description: This request was rate-limited.
6577
schema:

‎data/api/client-server/login_token.yaml

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Copyright 2023 The Matrix.org Foundation C.I.C.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
swagger: '2.0'
15+
info:
16+
title: "Matrix Client-Server Registration and Login API"
17+
version: "1.0.0"
18+
host: localhost:8008
19+
schemes:
20+
- https
21+
- http
22+
basePath: /_matrix/client/v1
23+
consumes:
24+
- application/json
25+
produces:
26+
- application/json
27+
securityDefinitions:
28+
$ref: definitions/security.yaml
29+
paths:
30+
"/login/get_token":
31+
post:
32+
summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token.
33+
description: |-
34+
Optional endpoint - the server is not required to implement this endpoint if it does not
35+
intend to use or support this functionality.
36+
37+
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
38+
39+
An already-authenticated client can call this endpoint to generate a single-use, time-limited,
40+
token for an unauthenticated client to log in with, becoming logged in as the same user which
41+
called this endpoint. The unauthenticated client uses the generated token in a `m.login.token`
42+
login flow with the homeserver.
43+
44+
Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes
45+
this feature if the server is not offering it. Authenticated clients can check for support on
46+
a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation),
47+
while unauthenticated clients can detect server support by looking for an `m.login.token` login
48+
flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login).
49+
50+
In v1.7 of the specification, transmission of the generated token to an unauthenticated client is
51+
left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906)
52+
might standarise a way to transmit the token between clients.
53+
54+
The generated token MUST only be valid for a single login, enforced by the server. Clients which
55+
intend to log in multiple devices must generate a token for each.
56+
57+
With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt
58+
for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt
59+
the user for verification to ensure explicit consent is gained for each additional client.
60+
61+
Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum
62+
of 1 request per minute.
63+
operationId: generateLoginToken
64+
x-addedInMatrixVersion: "1.7"
65+
security:
66+
- accessToken: []
67+
parameters:
68+
- in: body
69+
name: body
70+
required: true
71+
schema:
72+
type: object
73+
properties:
74+
auth:
75+
description: |-
76+
Additional authentication information for the user-interactive authentication API.
77+
allOf:
78+
- $ref: "definitions/auth_data.yaml"
79+
responses:
80+
200:
81+
description: The login token an unauthenticated client can use to log in as the requesting user.
82+
examples:
83+
application/json: {
84+
"login_token": "<opaque string>",
85+
"expires_in_ms": 120000
86+
}
87+
schema:
88+
type: object
89+
required: ["login_token", "expires_in_ms"]
90+
properties:
91+
login_token:
92+
type: string
93+
description: The login token for the `m.login.token` login flow.
94+
expires_in_ms:
95+
type: integer
96+
description: |-
97+
The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
98+
(2 minutes) is recommended as a default.
99+
400:
100+
description: |-
101+
The request was malformed, or the user does not have an ability to generate tokens for their devices,
102+
as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
103+
104+
Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token`
105+
[capability](/client-server-api/#capabilities-negotiation).
106+
schema:
107+
"$ref": "definitions/errors/error.yaml"
108+
401:
109+
description: |-
110+
The homeserver requires additional authentication information.
111+
schema:
112+
"$ref": "definitions/auth_response.yaml"
113+
429:
114+
description: This request was rate-limited.
115+
schema:
116+
"$ref": "definitions/errors/rate_limited.yaml"
117+
tags:
118+
- Session management

0 commit comments

Comments
 (0)