MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix #2966

sandhose · 2021-01-14T17:12:16Z

Rendered

Dependencies:

MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC #3861

SCT stuff:

checklist

FCP tickyboxes

proposals/2966-oauth2-dynamic-registration.md

…tration

- makes some metadata optional - better explain how each metadata field is used - better explain what the restrictions on redirect_uris are - remove the signed metadata part - mention the client metadata JSON document alternative

Co-authored-by: Tonkku <[email protected]>

turt2live

overall this looks good, though I think it needs implementations to be able to move to FCP. I'll document those requirements in a separate review.

proposals/2966-oauth2-dynamic-registration.md

turt2live · 2025-01-22T01:00:49Z

proposals/2966-oauth2-dynamic-registration.md

Implementation requirements:

Client using web flow

Client using native flow

Server supporting both flows (may be two different servers)

Known working clients with the web flow:

Element Web

Known working clients with the native flow:

Element Desktop

Element X iOS

Element X Android

Server supporting both:

Synapse with Matrix Authentication Service

Dendrite with Matrix Authentication Service (PR)

I haven't dug too far to find all the PRs or original implementations, but did find these points of evidence:

Allow specifying more OIDC client metadata for dynamic registration matrix-js-sdk#4070 (for Element Web via Improve client metadata used for OIDC dynamic registration matrix-react-sdk#12257 )

Add support for io.element.desktop scheme for OIDC element-hq/element-desktop#1662

feat(bindings): OIDC in AuthenticationService. matrix-rust-sdk#2412

The dendrite PR above

proposals/2966-oauth2-dynamic-registration.md

turt2live · 2025-01-25T23:55:57Z

MSCs proposed for Final Comment Period (FCP) should meet the requirements outlined in the checklist prior to being accepted into the spec. This checklist is a bit long, but aims to reduce the number of follow-on MSCs after a feature lands.

SCT members: please check off things you check for, and raise a concern against FCP if the checklist is incomplete. If an item doesn't apply, prefer to check it rather than remove it. Unchecking items is encouraged where applicable.

Checklist:

turt2live · 2025-01-25T23:56:43Z

@mscbot fcp merge

mscbot · 2025-01-25T23:56:46Z

zecakeh · 2025-01-27T22:21:40Z

proposals/2966-oauth2-dynamic-registration.md

+**Note**: in this example, the server has not registered the locale-specific values for `client_name`, `tos_uri`, and `policy_uri`, which is why they are not present in the response. The server also does not support the `urn:ietf:params:oauth:grant-type:token-exchange` grant type, which is why it is not present in the response.
+
+The client MUST store the `client_id` for future use.
+It SHOULD reuse the `client_id` for all future authorization requests done against the same homeserver.


So to be clear, the client should associate the client_id to the server name of the homeserver? The issuer field from RFC8414 is ignored, since it doesn't appear to be mentioned in any MSC?

Won't that complicate the migration of current implementations that should have associated their client_id to the issuer?

richvdh · 2025-01-28T16:32:39Z

proposals/2966-oauth2-dynamic-registration.md

+#### Localizable metadata
+


This section appears to be empty?

richvdh · 2025-01-28T16:34:47Z

proposals/2966-oauth2-dynamic-registration.md

+#### Redirect URI validation
+
+The redirect URI plays a critical role in validating the authenticity of the client.
+The client 'proves' its identity by demonstrating that it controls the redirect URI.
+This is why it is critical to have strict validation of the redirect URI.
+
+The `application_type` metadata is used to determine the type of client.
+It defaults to `web` if not present, and can be set to `native` to indicate that the client is a native application.
+
+In all cases, the redirect URI MUST not have a fragment component.
+
+#### Web clients
+
+`web` clients can use redirect URIs that:
+
+ - MUST use the `https` scheme
+ - MUST omit the port (to use the default port for https: 443)
+ - MUST not use a user or password in the authority component of the URI
+ - MUST use the client URI as a common base for the authority component
+
+Examples of valid redirect URIs (with `https://example.com/` as the client URI):
+
+ - `https://example.com/callback`
+ - `https://app.example.com/callback`
+ - `https://example.com/?query=value`
+
+Examples of invalid redirect URIs (with `https://example.com/` as the client URI):
+
+ - `https://example.com/callback#fragment`
+ - `https://example.com:8080/callback`
+ - `http://example.com/callback`
+ - `http://localhost/`
+
+#### Native clients
+
+`native` clients can use three types of redirect URIs:
+
+ 1. Private-Use URI Scheme:
+    - the scheme MUST be prefixed with the client URI hostname in reverse-DNS notation. For example, if the client URI is `https://example.com/`, then a valid custom URI scheme would be `com.example.app:/`.
+    - the URI MUST not have an authority component. This means that it MUST have either a single slash or none immediately following the scheme, with no hostname, username, or port.
+ 2. "http" URIs on the loopback interface:
+    - it MUST use the `http` scheme
+    - the host part MUST be `localhost`, `127.0.0.1`, or `[::1]`
+    - it MUST have no port registered. The homeserver MUST then accept any port number during the authorization flow.
+ 3. Claimed "https" Scheme URI:
+    - some operating systems allow apps to claim "https" scheme URIs in the domains they control
+    - when the browser encounters a claimed URI, instead of the page being loaded in the browser, the native app is launched with the URI supplied as a launch parameter
+    - the same rules as for `web` clients apply
+
+These restrictions are the same as defined by [RFC8252 sec. 7](https://tools.ietf.org/html/rfc8252#section-7).
+
+Examples of valid redirect URIs (with `https://example.com/` as the client URI):
+
+ - `com.example.app:/callback`
+ - `com.example:/`
+ - `com.example:callback`
+ - `http://localhost/callback`
+ - `http://127.0.0.1/callback`
+ - `http://[::1]/callback`
+
+Examples of invalid redirect URIs (with `https://example.com/` as the client URI):
+
+ - `example:/callback`
+ - `com.example.app://callback`
+ - `https://localhost/callback`
+ - `http://localhost:1234/callback`


If these three sections are all about redirect URIs, it would be really helpful to say so. I was expecting a section called "Web clients" to be more general.

richvdh · 2025-01-28T16:44:12Z

proposals/2966-oauth2-dynamic-registration.md

+This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861).
+
+This MSC specifies how Matrix clients SHOULD leverage the OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://tools.ietf.org/html/rfc7591)) to register themselves before initiating an authorization flow.
+


I'd find it really helpful to give a one-line summary of how this MSC fits in with the others, and also explain, to those of us less familiar with RFC7591, how often we expect clients to hit this endpoint.

Suggested change

In brief, once a client has obtained the homeserver's OAuth 2.0 metadata per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965), and before it can initiate an authorization request per [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964), the client must register itself with that homeserver to obtain a `client_id`.

It stores this `client_id` and uses it for all future authorization requests against the homeserver.

(There is something to this effect in the "client metadata" section, but it feels a bit lost in there, given that's just one of three h3-level sections in the proposal)

richvdh · 2025-01-28T16:48:03Z

proposals/2966-oauth2-dynamic-registration.md

+### Dynamic client registration
+
+Before initiating an authorization flow, the client MUST advertise its metadata to the homeserver to get back a `client_id`.
+
+This is done through the `registration_endpoint` as described by [RFC7591 sec. 3](https://tools.ietf.org/html/rfc7591#section-3).
+
+To register, the client sends an HTTP POST to the `registration_endpoint` with its metadata as JSON in the body.
+For example, the client could send the following registration request:
+
+```http
+POST /register HTTP/1.1
+Content-Type: application/json
+Accept: application/json
+Server: auth.example.com
+```
+
+```json
+{
+  "client_name": "My App",
+  "client_name#fr": "Mon application",
+  "client_uri": "https://example.com/",
+  "logo_uri": "https://example.com/logo.png",
+  "tos_uri": "https://example.com/tos.html",
+  "tos_uri#fr": "https://example.com/fr/tos.html",
+  "policy_uri": "https://example.com/policy.html",
+  "policy_uri#fr": "https://example.com/fr/policy.html",
+  "redirect_uris": ["https://app.example.com/callback"],
+  "token_endpoint_auth_method": "none",
+  "response_types": ["code"],
+  "grant_types": [
+    "authorization_code",
+    "refresh_token",
+    "urn:ietf:params:oauth:grant-type:token-exchange"
+  ],
+  "application_type": "web"
+}
+```
+
+The server replies with a JSON object containing the `client_id` allocated, as well as all the metadata values that the server registered.
+It MUST ignore fields, `grant_types` and `response_types` that are not understood by the server.
+
+With the previous registration request, the server would reply with:
+
+```json
+{
+  "client_id": "s6BhdRkqt3",
+  "client_name": "My App",
+  "client_uri": "https://example.com/",
+  "logo_uri": "https://example.com/logo.png",
+  "tos_uri": "https://example.com/tos.html",
+  "policy_uri": "https://example.com/policy.html",
+  "redirect_uris": ["https://app.example.com/callback"],
+  "response_types": ["code"],
+  "grant_types": ["authorization_code", "refresh_token"],
+  "application_type": "web"
+}
+```
+
+**Note**: in this example, the server has not registered the locale-specific values for `client_name`, `tos_uri`, and `policy_uri`, which is why they are not present in the response. The server also does not support the `urn:ietf:params:oauth:grant-type:token-exchange` grant type, which is why it is not present in the response.
+
+The client MUST store the `client_id` for future use.
+It SHOULD reuse the `client_id` for all future authorization requests done against the same homeserver.


Personally, I'd find this proposal way easier to grok if the API was defined before the relevant metadata (with words like: "the client MUST advertise its metadata to the homeserver to get back a client_id. The metadata is as descripted under 'Client metadata' below").

Otherwise I have to read all through the "metadata" section before I get an answer to "ok, but what is all this stuff actually for?"

Not insisting on a change here, but just thinking it might help future readers.

richvdh · 2025-01-28T16:55:01Z

proposals/2966-oauth2-dynamic-registration.md

+With the previous registration request, the server would reply with:
+
+```json
+{
+  "client_id": "s6BhdRkqt3",
+  "client_name": "My App",
+  "client_uri": "https://example.com/",
+  "logo_uri": "https://example.com/logo.png",
+  "tos_uri": "https://example.com/tos.html",
+  "policy_uri": "https://example.com/policy.html",
+  "redirect_uris": ["https://app.example.com/callback"],
+  "response_types": ["code"],
+  "grant_types": ["authorization_code", "refresh_token"],
+  "application_type": "web"
+}
+```


I notice that RFC7591 specifies client_secret as an optional field here. Do we want to allow matrix homeservers to return a client_secret and expect clients to know what to do with it? I guess the answer is yes, given RFC7591 says so, but it wouldn't hurt to be explicit.

richvdh · 2025-01-28T17:13:40Z

proposals/2966-oauth2-dynamic-registration.md

+#### `client_uri` and relationship with other URIs
+
+Per [RFC 7591](https://tools.ietf.org/html/rfc7591), the `client_uri` MUST be a valid URL that SHOULD give the user more information about the client.
+This URL SHOULD NOT require authentication to access.


is client_uri required?

If not, some "If present" wording would be helpful, and explain how the constraints on the other URIs work when it is absent.

If it is required, call it out explicitly, and maybe say what should happen if it's not there?

richvdh · 2025-01-28T17:19:44Z

proposals/2966-oauth2-dynamic-registration.md

+The `application_type` metadata is used to determine the type of client.
+It defaults to `web` if not present, and can be set to `native` to indicate that the client is a native application.
+
+In all cases, the redirect URI MUST not have a fragment component.


Suggested change

In all cases, the redirect URI MUST not have a fragment component.

In all cases, the redirect URI MUST NOT have a fragment component.

richvdh · 2025-01-28T17:20:28Z

proposals/2966-oauth2-dynamic-registration.md

+
+ 1. Private-Use URI Scheme:
+    - the scheme MUST be prefixed with the client URI hostname in reverse-DNS notation. For example, if the client URI is `https://example.com/`, then a valid custom URI scheme would be `com.example.app:/`.
+    - the URI MUST not have an authority component. This means that it MUST have either a single slash or none immediately following the scheme, with no hostname, username, or port.


Suggested change

- the URI MUST not have an authority component. This means that it MUST have either a single slash or none immediately following the scheme, with no hostname, username, or port.

- the URI MUST NOT have an authority component. This means that it MUST have either a single slash or none immediately following the scheme, with no hostname, username, or port.

richvdh · 2025-01-28T17:21:34Z

proposals/2966-oauth2-dynamic-registration.md

+ 2. "http" URIs on the loopback interface:
+    - it MUST use the `http` scheme
+    - the host part MUST be `localhost`, `127.0.0.1`, or `[::1]`
+    - it MUST have no port registered. The homeserver MUST then accept any port number during the authorization flow.


Suggested change

- it MUST have no port registered. The homeserver MUST then accept any port number during the authorization flow.

- it (the registered redirect URI) MUST NOT contain a port number. The homeserver MUST then accept any port number during the authorization flow.

richvdh · 2025-01-28T17:23:57Z

proposals/2966-oauth2-dynamic-registration.md

+## Alternatives
+
+An alternative approach would be to have the client host a JSON file containing its metadata and use that URL as the `client_id`.
+This is what the following [*OAuth Client ID Metadata Document* draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document) proposes.


Suggested change

This is what the following [*OAuth Client ID Metadata Document* draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document) proposes.

This is what the [*OAuth Client ID Metadata Document* draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document) proposes.

or:

Suggested change

This is what the following [*OAuth Client ID Metadata Document* draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document) proposes.

This is what the following document proposes: [*OAuth Client ID Metadata Document* draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document).

OAuth 2.0 Dynamic Registration MSC

1b1bcdd

turt2live changed the title ~~MSC2966: [WIP] Usage of OAuth 2.0 Dynamic Client Registration in Matrix~~ [WIP] MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix Jan 14, 2021

turt2live marked this pull request as draft January 14, 2021 17:28

turt2live added kind:feature MSC for not-core and not-maintenance stuff proposal A matrix spec change proposal labels Jan 14, 2021

sandhose mentioned this pull request Jan 15, 2021

MSC2964: Usage of OAuth 2.0 authorization code grant and refresh token grant #2964

Open

9 tasks

richvdh reviewed Feb 4, 2021

View reviewed changes

proposals/2966-oauth2-dynamic-registration.md Outdated Show resolved Hide resolved

richvdh reviewed Feb 13, 2021

View reviewed changes

proposals/2966-oauth2-dynamic-registration.md Outdated Show resolved Hide resolved

turt2live added the needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. label Jun 8, 2021

turt2live force-pushed the old_master branch from e895827 to dca99ee Compare August 30, 2021 22:34

sandhose mentioned this pull request Jan 17, 2022

Support dynamic client registration matrix-org/matrix-authentication-service#17

Closed

39 tasks

hughns mentioned this pull request Aug 4, 2022

MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC #3861

Open

deepbluev7 reviewed Feb 24, 2023

View reviewed changes

turt2live added the matrix-2.0 Required for Matrix 2.0 label Mar 3, 2023

zecakeh reviewed Aug 4, 2023

View reviewed changes

proposals/2966-oauth2-dynamic-registration.md Outdated Show resolved Hide resolved

contacts is required non-empty

d923a45

This was referenced Sep 7, 2023

Required MSC2966 contacts field is missing from OIDC client registration element-hq/element-x-ios#1653

Closed

Required MSC2966 contacts field is missing from OIDC client registration element-hq/element-x-android#1250

Closed

Make client_uri mandatory

2bdcc4a

sandhose mentioned this pull request Feb 7, 2024

OAUTH: how does a client manage multiple version of its metadata at the same time? bluesky-social/proposals#51

Open

Merge branch 'matrix-org:main' into msc/sandhose/oauth2-dynamic-regis…

d4caa5a

…tration

sandhose closed this Sep 3, 2024

sandhose deleted the msc/sandhose/oauth2-dynamic-registration branch September 3, 2024 10:23

sandhose restored the msc/sandhose/oauth2-dynamic-registration branch September 3, 2024 10:24

sandhose reopened this Sep 3, 2024

sandhose changed the base branch from old_master to main September 3, 2024 10:25

matrixbot mentioned this pull request Sep 9, 2024

Support dynamic client registration element-hq/matrix-authentication-service#17

Closed

39 tasks

Rework MSC

32c9ead

- makes some metadata optional - better explain how each metadata field is used - better explain what the restrictions on redirect_uris are - remove the signed metadata part - mention the client metadata JSON document alternative

sandhose changed the title ~~[WIP] MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix~~ MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix Sep 13, 2024

sandhose marked this pull request as ready for review September 13, 2024 15:41

sandhose and others added 7 commits December 9, 2024 09:56

Mention the token_endpoint_auth_method client metadata

1ba6ce9

Update proposals/2966-oauth2-dynamic-registration.md

6eb5fdf

Co-authored-by: Tonkku <[email protected]>

State that the homeserver should display the tos_uri and policy_uri

a67a2e8

Make the wording for the refresh token clearer

d9fd175

Clarify that native callbacks with no slashes are allowed

a7ddac2

Give an example where the server ignores an unsupported grant type

4deb3c8

Add security considerations

0e2f0f1

sandhose force-pushed the msc/sandhose/oauth2-dynamic-registration branch from 85d1958 to 0e2f0f1 Compare January 17, 2025 09:14

turt2live requested changes Jan 22, 2025

View reviewed changes

turt2live reviewed Jan 22, 2025

View reviewed changes

turt2live added needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. and removed implementation-needs-checking The MSC has an implementation, but the SCT has not yet checked it. labels Jan 22, 2025

turt2live reviewed Jan 22, 2025

View reviewed changes

proposals/2966-oauth2-dynamic-registration.md Show resolved Hide resolved

sandhose added 3 commits January 22, 2025 13:46

must -> MUST, should -> SHOULD, may -> MAY

2a20e6d

Clarify the client should store the client_id

c7e55ec

Simplify definition of client_uri, already covered by the RFC

fe4ef69

sandhose requested a review from turt2live January 22, 2025 14:37

turt2live removed the needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. label Jan 25, 2025

turt2live approved these changes Jan 25, 2025

View reviewed changes

mscbot added proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period. disposition-merge labels Jan 25, 2025

zecakeh reviewed Jan 27, 2025

View reviewed changes

richvdh reviewed Jan 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix #2966

MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix #2966

sandhose commented Jan 14, 2021 •

edited by turt2live

Loading

turt2live left a comment

turt2live Jan 22, 2025

sandhose Jan 22, 2025

turt2live Jan 25, 2025

turt2live commented Jan 25, 2025

turt2live commented Jan 25, 2025

mscbot commented Jan 25, 2025

zecakeh Jan 27, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

richvdh Jan 28, 2025

		This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861).

		This MSC specifies how Matrix clients SHOULD leverage the OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://tools.ietf.org/html/rfc7591)) to register themselves before initiating an authorization flow.



	In brief, once a client has obtained the homeserver's OAuth 2.0 metadata per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965), and before it can initiate an authorization request per [MSC2964](https://github.com/matrix-org/matrix-spec-proposals/pull/2964), the client must register itself with that homeserver to obtain a `client_id`.
	It stores this `client_id` and uses it for all future authorization requests against the homeserver.

	In all cases, the redirect URI MUST not have a fragment component.
	In all cases, the redirect URI MUST NOT have a fragment component.

	- the URI MUST not have an authority component. This means that it MUST have either a single slash or none immediately following the scheme, with no hostname, username, or port.
	- the URI MUST NOT have an authority component. This means that it MUST have either a single slash or none immediately following the scheme, with no hostname, username, or port.

	- it MUST have no port registered. The homeserver MUST then accept any port number during the authorization flow.
	- it (the registered redirect URI) MUST NOT contain a port number. The homeserver MUST then accept any port number during the authorization flow.

	This is what the following [OAuth Client ID Metadata Document draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document) proposes.
	This is what the [OAuth Client ID Metadata Document draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document) proposes.

	This is what the following [OAuth Client ID Metadata Document draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document) proposes.
	This is what the following document proposes: [OAuth Client ID Metadata Document draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document).

MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix #2966

Are you sure you want to change the base?

MSC2966: Usage of OAuth 2.0 Dynamic Client Registration in Matrix #2966

Conversation

sandhose commented Jan 14, 2021 • edited by turt2live Loading

turt2live left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

turt2live commented Jan 25, 2025

turt2live commented Jan 25, 2025

mscbot commented Jan 25, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sandhose commented Jan 14, 2021 •

edited by turt2live

Loading