mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-26 13:04:10 +01:00
Specify MSC3882: Using an existing session to log in another
MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/3882
This commit is contained in:
Travis Ralston
parent
4fabef1c97
commit
c695328d99
|
|
@ -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" %}}
|
||||
|
|
|
|||
|
|
@ -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": "<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 a new issue