Specify MSC3882: Using an existing session to log in another (#1530)
* Specify MSC3882: Using an existing session to log in another MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/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>pull/1534/head
Travis Ralston
1 year ago
committed by
GitHub
parent
cad4f78711
commit
6496d374d2
@ -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).
|
||||
@ -0,0 +1 @@
|
||||
[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
|
||||
@ -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": "<opaque string>",
|
||||
"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
|
||||
Loading…
Reference in New Issue