# MSC4108: Mechanism to allow OIDC sign in and E2EE set up via QR code
# MSC4108: Mechanism to allow OAuth sign in and E2EE set up via QR code
We propose a method to allow an existing authenticated Matrix client to sign in a new client by scanning a QR code. The
We propose a method to allow an existing authenticated Matrix client to sign in a new client by scanning a QR code. The
new client will be a fully bootstrapped Matrix cryptographic device, possessing all the necessary secrets, namely the
new client will be a fully bootstrapped Matrix cryptographic device, possessing all the necessary secrets, namely the
@ -7,7 +7,7 @@ cryptographic user identity ("cross-signing") and the server-side key backup dec
This MSC supersedes [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906),
This MSC supersedes [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906),
[MSC3903](https://github.com/matrix-org/matrix-spec-proposals/pull/3903) and
[MSC3903](https://github.com/matrix-org/matrix-spec-proposals/pull/3903) and
[MSC3886](https://github.com/matrix-org/matrix-spec-proposals/pull/3886) which achieved a similar feature but did not
[MSC3886](https://github.com/matrix-org/matrix-spec-proposals/pull/3886) which achieved a similar feature but did not
work with a homeserver using the delegated OIDC mechanism proposed by [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861).
work with a homeserver using [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api).
## Proposal
## Proposal
@ -24,7 +24,7 @@ This proposal is split into three parts:
1. An insecure rendezvous session API to allow the two devices to exchange the necessary data
1. An insecure rendezvous session API to allow the two devices to exchange the necessary data
2. A secure channel to protect the data exchanged over the rendezvous session
2. A secure channel to protect the data exchanged over the rendezvous session
3. The OIDC login part and set up of E2EE
3. The OAuth login part and set up of E2EE
### Insecure rendezvous session
### Insecure rendezvous session
@ -229,7 +229,7 @@ The server enforce a maximum payload size of 4KB.
The rendezvous session needs to persist for the duration of the login. So a timeout such as 60 seconds should be adequate.
The rendezvous session needs to persist for the duration of the login. So a timeout such as 60 seconds should be adequate.
It does need to allow the user another time to confirm that the secure channel has been established and complete any extra
It does need to allow the user another time to confirm that the secure channel has been established and complete any extra
OIDC Provider mandated login steps such as MFA.
homeserver mandated login steps such as MFA.
Clients should handle the case of the rendezvous session being cancelled or timed out by the server.
Clients should handle the case of the rendezvous session being cancelled or timed out by the server.
@ -673,11 +673,11 @@ own key.
- The attack is only thwarted in step 7, because Device S won't ever display the indicator of success to the user. The
- The attack is only thwarted in step 7, because Device S won't ever display the indicator of success to the user. The
user then must cancel the process on Device G, preventing it from sharing any sensitive material.
user then must cancel the process on Device G, preventing it from sharing any sensitive material.
### The OIDC login part and set up of E2EE
### The OAuth login part and set up of E2EE
Once the secure channel has been established, the two devices can then communicate securely.
Once the secure channel has been established, the two devices can then communicate securely.
#### Login via OIDC Device Authorization Grant
#### Login via OAuth Device Authorization Grant
In this section the sequence of steps depends on whether the new device generated or scanned the QR code.
In this section the sequence of steps depends on whether the new device generated or scanned the QR code.
@ -697,7 +697,7 @@ Otherwise the new device waits to be informed by receiving an `m.login.protocols
The existing device would need to determine which "protocols" are available for the new device to use.
The existing device would need to determine which "protocols" are available for the new device to use.
Currently this could only be device_authorization_grant meaning the OIDC Provider supports the
Currently this could only be device_authorization_grant meaning the homeserver supports the
`urn:ietf:params:oauth:grant-type:device_code` grant type.
`urn:ietf:params:oauth:grant-type:device_code` grant type.
If it is available then the existing device informs the new device by sending the `m.login.protocols` message with the
If it is available then the existing device informs the new device by sending the `m.login.protocols` message with the
@ -720,12 +720,12 @@ Once the existing device has determined the server name it then undertakes steps
The steps are as follows:
The steps are as follows:
- use [Server Discovery](https://spec.matrix.org/v1.10/client-server-api/#server-discovery) to determine the `base_url` from the well-known URI
- use [Server Discovery](https://spec.matrix.org/v1.10/client-server-api/#server-discovery) to determine the `base_url` from the well-known URI
- checks that the homeserver is using delegated OIDC by calling `GET /_matrix/client/v1/auth_issuer` from [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965):
- checks that the homeserver has the OAuth 2.0 API available by [`GET /_matrix/client/v1/auth_metadata`](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery)
*New device => Homeserver via HTTP*
*New device => Homeserver via HTTP*
```http
```http
GET /_matrix/client/v1/auth_issuer HTTP/1.1
GET /_matrix/client/v1/auth_metadata HTTP/1.1
Host: synapse-oidc.lab.element.dev
Host: synapse-oidc.lab.element.dev
Accept: application/json
Accept: application/json
```
```
@ -736,28 +736,6 @@ With response like:
200 OK
200 OK
Content-Type: application/json
Content-Type: application/json
{
"issuer": "https://auth-oidc.lab.element.dev/"
}
```
- parses the OIDC Provider (`issuer`) from the response
- fetches the OIDC Provider metadata as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965):
E->>UA: 5) Existing device opens <br>verification_uri_complete (with fallback to verification_uri)<br> in the system web browser/ASWebAuthenticationSession:
E->>UA: 5) Existing device opens <br>verification_uri_complete (with fallback to verification_uri)<br> in the system web browser/ASWebAuthenticationSession:
Note over E: n.b. in the case of a Web Browser the user needs to have<br> clicked a button in order for the navigation to happen
Note over E: n.b. in the case of a Web Browser the user needs to have<br> clicked a button in order for the navigation to happen
rect rgba(240,240,240,0.5)
rect rgba(240,240,240,0.5)
UA->>OP: GET https://id.matrix.org/device/abcde
UA->>HS: GET https://id.matrix.org/device/abcde
OP->>UA: <html/> consent screen showing the user_code
HS->>UA: <html/> consent screen showing the user_code
UA->>OP: POST /allow or /deny
UA->>HS: POST /allow or /deny
end
end
Note over UA: User closes browser
Note over UA: User closes browser
end
end
@ -1093,8 +1066,8 @@ Once the new device has logged in and obtained an access token it will want to o
end-to-end encryption on the device and make itself cross-signed.
end-to-end encryption on the device and make itself cross-signed.
Before sharing the end-to-end encryption secrets the existing device should validate that the new device has
Before sharing the end-to-end encryption secrets the existing device should validate that the new device has
successfully obtained an access token from the OIDC Provider. The purpose of this is so that, if the user or OIDC
successfully obtained an access token from the homeserver. The purpose of this is so that, if the user or homeserver
Provider has disallowed the login, the secrets are not leaked.
has disallowed the login, the secrets are not leaked.
If checked successfully then the existing device sends the following secrets to the new device:
If checked successfully then the existing device sends the following secrets to the new device:
@ -1180,7 +1153,6 @@ The sequence diagram for this would look as follows:
sequenceDiagram
sequenceDiagram
participant E as Existing device <br>already signed in
participant E as Existing device <br>already signed in
participant N as New device <br>wanting to sign in
participant N as New device <br>wanting to sign in
|`device_authorization_grant`|Required `object` where `protocol` is `device_authorization_grant`|These values are taken from the RFC8628 Device Authorization Response that the new device received from the OIDC Provider: <table><tr><td><strong>Field</strong></td><td><strong>Type</strong></td></tr><tr><td><code>verification_uri</code></td><td>required <code>string</code></td></tr><tr><td><code>verification_uri_complete</code></td><td><code>string</code></td></tr></table>|
|`device_authorization_grant`|Required `object` where `protocol` is `device_authorization_grant`|These values are taken from the RFC8628 Device Authorization Response that the new device received from the homeserver: <table><tr><td><strong>Field</strong></td><td><strong>Type</strong></td></tr><tr><td><code>verification_uri</code></td><td>required <code>string</code></td></tr><tr><td><code>verification_uri_complete</code></td><td><code>string</code></td></tr></table>|
|`device_id`|required `string`|The device ID that the new device will use|
|`device_id`|required `string`|The device ID that the new device will use|
Example:
Example:
@ -1460,13 +1432,13 @@ Before offering this capability it would make sense that the device can check th
Where the homeserver is known:
Where the homeserver is known:
1. Check if the homeserver has a rendezvous session API available (/versions) from this MSC
1. Check if the homeserver has a rendezvous session API available (/versions) from this MSC
1. Check that the homeserver is using the OIDC architecture (/auth_issuer) from MSC2965
1. Check that the homeserver is using the OAuth 2.0 API using [server metadata discovery](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery)
1. Check that the Device Authorization Grant is available on the OIDC Provider from MSC2965
1. Check that the Device Authorization Grant is available as per [MSC4341]
For a new device it would need to know the homeserver ahead of time in order to do these checks.
For a new device it would need to know the homeserver ahead of time in order to do these checks.
Additionally the new device needs to either have an existing (i.e. static) OIDC client registered with the OIDC Provider
Additionally the new device needs to either have an existing (i.e. static) OAuth client registered with the homeserver
already, or the OIDC Provider must support and allow dynamic client registration as described in [MSC2966](https://github.com/matrix-org/matrix-spec-proposals/pull/2966).
already, or the homeserver must support and allow dynamic client registration as described in the [spec](https://spec.matrix.org/v1.15/client-server-api/#client-registration).
The feature is also only available where a user has cross-signing set up and the existing device to be used has the
The feature is also only available where a user has cross-signing set up and the existing device to be used has the
Master Signing Key, Self Signing Key and User Signing Key stored locally so that they can be shared with the new device.
Master Signing Key, Self Signing Key and User Signing Key stored locally so that they can be shared with the new device.
@ -1542,8 +1514,8 @@ This proposed mechanism has been designed to protects users and their devices fr
- A malicious actor who can intercept and modify traffic on the application layer, even if protected by encryption like TLS.
- A malicious actor who can intercept and modify traffic on the application layer, even if protected by encryption like TLS.
- Both of the above at the same time.
- Both of the above at the same time.
Additionally, the OIDC Provider is able to define and enforce policies that can prevent a sign in on a new device.
Additionally, the homeserver is able to define and enforce policies that can prevent a sign in on a new device.
Such policies depend on the OIDC Provider in use and could include, but are not limited to, time of day, day of the week,
Such policies depend on the homeserver in use and could include, but are not limited to, time of day, day of the week,
source IP address and geolocation.
source IP address and geolocation.
A threat analysis has been done within each of the key layers in the proposal above.
A threat analysis has been done within each of the key layers in the proposal above.
@ -1588,5 +1560,6 @@ The server should send:
## Dependencies
## Dependencies
This MSC builds on [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) (and its dependencies) which
This MSC builds on [MSC4341] which proposes support for RFC 8628 Device Authorization Grant in Matrix.
proposes the adoption of OIDC for authentication in Matrix.
[MSC4341]: https://github.com/matrix-org/matrix-spec-proposals/pull/4341 "MSC4341 Support for RFC 8628 Device Authorization Grant"