matrix-spec-proposals/proposals/3882-login-token-request.md

MSC3882: Allow an existing session to sign in a new session

In MSC3906 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

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

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 "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/1.1 200 OK
Content-Type: application/json

{
    "login_token": "<login token>",
    "expires_in_ms": 120000
}

This token can then be used as per the existing Login spec as follows:

POST /_matrix/client/v3/login HTTP/1.1
Content-Type: application/json

{
  "type": "m.login.token",
  "token": "<login token>"
}

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

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 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:

{
  "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 advertised by the homeserver.

The unauthenticated client can also determine whether the new API endpoint is available via the capability 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:

{
  "capabilities": {
    "m.get_login_token": {
      "enabled": true
    }
  }
}

Potential issues

None identified.

Alternatives

If Matrix was already using OIDC as per MSC3861 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. 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 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. 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.

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:

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

While this feature is in development the following unstable prefixes should be used:

• 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 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.

Dependencies

None.