MSC2965: OAuth 2.0 Authorization Server Metadata discovery #2965

sandhose · 2021-01-14T17:11:39Z

Rendered

Status:

Spec is feature complete
Reviewed for consistency with MSC3861
Implementations believed to be complete enough

Dependencies:

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

Clients and homeservers currently implement an older version of this proposal, and need to be updated:

Synapse/Matrix Authentication Service: Support the new /auth_metadata endpoint defined in MSC2965. element-hq/synapse#18093
matrix-rust-sdk: Update support of MSC2965 OAuth 2.0 Authorization Server Metadata discovery matrix-rust-sdk#4550
Element X Android
Element X iOS
matrix-js-sdk: Switch OIDC primarily to new /auth_metadata API matrix-js-sdk#4626
Element Web

SCT:

tickyboxes
checklist

erlend-sh · 2022-08-09T16:45:25Z

Keycloak in OIDC Playground

Are any other examples planned?

I’m using Ory for several apps that I’d like to also connect together with Matrix. It also strikes me as a conveniently lightweight example for Matrix, which also aligns well with Dendrite since it’s in Go.

hughns · 2022-08-14T20:55:08Z

@erlend-sh Good suggestion, thank you - I've added element-hq/oidc-playground#3 to track this.

proposals/2965-oidc-discovery.md

proposals/2965-auth-metadata.md

turt2live

overall looks good to me - just a few (hopefully) easily correctable concerns

proposals/2965-auth-metadata.md

turt2live · 2025-01-22T00:34:20Z

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-22T00:38:24Z

Implementation lgtm. Concerns are relatively minor as well:

@mscbot fcp merge

mscbot · 2025-01-22T00:38:26Z

turt2live · 2025-01-22T00:39:20Z

@mscbot concern Error codes for not using OIDC
@mscbot concern Include rationale for Client-Server API endpoint over .well-known
@mscbot concern Checklist is incomplete

Co-authored-by: Travis Ralston <travpc@gmail.com>

turt2live

read-up-to marker

(thanks for keeping these updated)

turt2live · 2025-01-25T23:39:13Z

@mscbot resolve Error codes for not using OIDC
@mscbot resolve Include rationale for Client-Server API endpoint over .well-known
@mscbot resolve Checklist is incomplete

erikjohnston · 2025-01-28T11:11:24Z

proposals/2965-auth-metadata.md

+
+## Proposal
+
+This introduces a new Client-Server API endpoint to discover the authorization server metadata used by the homeserver.


Can we include a rationale for why we don't hardcode the endpoint URLs to be under a /_matrix/oauth2 scheme? We still need the metdata discovery for other fields, so to an extent there is a question as to "why not", but still.

richvdh · 2025-02-04T12:41:30Z

proposals/2965-auth-metadata.md

+
+If the homeserver does not offer next-generation authentication as described in [MSC3861], this endpoint should return a 404 with the `M_UNRECOGNIZED` error code.
+
+In this case, clients should fall back to using the User-Interactive Authentication flows instead to authenticate the user.


richvdh · 2025-02-04T12:45:47Z

proposals/2965-auth-metadata.md

+
+In this case, clients should fall back to using the User-Interactive Authentication flows instead to authenticate the user.
+
+## Rationale for not using a `.well-known` document


Editorial nit: put this under the corresponding "Alternatives" entry, rather than making it its own h2 heading?

Yes -- it is really confusing to present this before the alternative of using well-known.

richvdh · 2025-02-04T13:19:26Z

proposals/2965-auth-metadata.md

+However, the RFC states that an application leveraging this standard should define its own application-specific endpoint, e.g. `/.well-known/matrix-authorization-server`, and _not_ use the `.well-known/oauth-authorization-server` endpoint.
+To avoid confusion with the existing `.well-known/matrix/*` documents, this proposal suggests defining a new C-S API endpoint instead.
+
+### Discovery via the well-known client discovery


Nit: it's server discovery rather than client discovery, if anything.

maybe:

Suggested change

### Discovery via the well-known client discovery

### Discovery via existing `.well-known` mechanism

richvdh · 2025-02-04T13:21:20Z

proposals/2965-auth-metadata.md

+A previous version of this proposal suggested using the well-known client discovery mechanism to discover the authentication server.
+Clients already discover the homeserver when doing a server discovery via the well-known document.
+
+A new `m.authentication` field is added to this document to support OpenID Connect Provider (OP) discovery.


Suggested change

A previous version of this proposal suggested using the well-known client discovery mechanism to discover the authentication server.

Clients already discover the homeserver when doing a server discovery via the well-known document.

A new `m.authentication` field is added to this document to support OpenID Connect Provider (OP) discovery.

A previous version of this proposal suggested using the existing [homeserver discovery mechanism](https://spec.matrix.org/v1.13/client-server-api/#server-discovery) to discover the authentication server.

A new `m.authentication` field is added to the `.well-known` document to support OpenID Connect Provider (OP) discovery.

clokep · 2025-02-04T15:34:39Z

proposals/2965-auth-metadata.md

+The first option would require making well-known documents mandatory on the server name domain, with a document that may need to be updated more frequently than existing ones.
+This isn't practical for some server deployments, and clients may find it challenging to consistently perform this discovery.
+
+The second option is also impractical, as all other Matrix APIs on this domain are prefixed with `/_matrix`, and it could easily be confused with the set of well-known documents hosted on the server name domain.


I don't understand this -- I think the thread (https://github.com/matrix-org/matrix-spec-proposals/pull/2965/files#r1924524746) talks about before/after finding the client API. That rationale seems to be missing here.

Frankly to me, I'd expect this to be under well-known.

tonkku107 · 2025-02-06T18:44:42Z

proposals/2965-auth-metadata.md

+}
+```
+
+**Note**: The fields required for the main flow outlined by [MSC3861] and its sub-proposals are:


Here we define some required fields for the matrix proposals but I think some clarity is needed on whether requirements from RFC8414 also apply.

This is the method to get the server metadata in the latest draft of [MSC2965](matrix-org/matrix-spec-proposals#2965). We still keep the old behavior with `GET /auth_issuer` as fallback for now because it has wider server support. There are some pre-main commit cleanups to simplify the main commit. This can be reviewed commit by commit. The changes were tested with the oidc_cli example on beta.matrix.org. Closes #4550. --------- Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

OIDC discovery MSC

ef474ee

turt2live changed the title ~~MSC2965: [WIP] OIDC Provider discovery~~ [WIP] MSC2965: OIDC Provider discovery Jan 14, 2021

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

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

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

hughns added 2 commits May 2, 2022 15:09

Add account field

4d9345c

Add id_token_hint to account management URL

4a24cf6

This was referenced Jun 22, 2022

Implementation of MSC3824 to make the client OIDC-aware matrix-org/matrix-react-sdk#8681

Merged

Implementation of MSC3824 to make the client OIDC-aware element-hq/element-android#6367

Closed

hughns mentioned this pull request Aug 4, 2022

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

Open

Add reference to MSC3861

f5b54bf

hughns mentioned this pull request Aug 14, 2022

Test Ory as OIDC Provider element-hq/oidc-playground#3

Open

Add missing heading

1cc4976

hughns changed the title ~~[WIP] MSC2965: OIDC Provider discovery~~ MSC2965: OIDC Provider discovery Sep 22, 2022

hughns marked this pull request as ready for review September 22, 2022 16:08

hughns mentioned this pull request Jan 9, 2023

Implementation of MSC3824 to make the client OIDC-aware element-hq/element-android#7920

Merged

20 tasks

Fix reference to MSC3861

6455b1f

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

clokep reviewed May 16, 2023

View reviewed changes

proposals/2965-oidc-discovery.md Outdated Show resolved Hide resolved

clokep reviewed May 16, 2023

View reviewed changes

proposals/2965-oidc-discovery.md Outdated Show resolved Hide resolved

clokep reviewed May 16, 2023

View reviewed changes

proposals/2965-oidc-discovery.md Outdated Show resolved Hide resolved

clokep reviewed May 16, 2023

View reviewed changes

proposals/2965-oidc-discovery.md Outdated Show resolved Hide resolved

clokep reviewed May 16, 2023

View reviewed changes

proposals/2965-oidc-discovery.md Outdated Show resolved Hide resolved

clokep reviewed May 16, 2023

View reviewed changes

proposals/2965-oidc-discovery.md Outdated Show resolved Hide resolved

clokep reviewed May 16, 2023

View reviewed changes

proposals/2965-oidc-discovery.md Outdated Show resolved Hide resolved

zecakeh mentioned this pull request Jan 18, 2025

client-api: Add support for authorization server metadata endpoint ruma/ruma#1997

Merged

tonkku107 reviewed Jan 20, 2025

View reviewed changes

proposals/2965-auth-metadata.md Show resolved Hide resolved

turt2live requested changes Jan 22, 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 22, 2025

turt2live removed the implementation-needs-checking The MSC has an implementation, but the SCT has not yet checked it. label Jan 22, 2025

mscbot added the unresolved-concerns This proposal has at least one outstanding concern label Jan 22, 2025

sandhose and others added 5 commits January 22, 2025 14:10

Clarify auth & rate limiting requirements

0e7cea0

Co-authored-by: Travis Ralston <travpc@gmail.com>

Mention the MSCs using each metadata value

2aed234

Explain what to do when next-gen auth is not available

93d1b09

Add rationale for not using a .well-known endpoint

ee1c23d

Reformat with prettier

885a50f

sandhose requested a review from turt2live January 22, 2025 16:17

turt2live approved these changes Jan 25, 2025

View reviewed changes

mscbot removed the unresolved-concerns This proposal has at least one outstanding concern label Jan 25, 2025

erikjohnston reviewed Jan 28, 2025

View reviewed changes

richvdh reviewed Feb 4, 2025

View reviewed changes

clokep reviewed Feb 4, 2025

View reviewed changes

tonkku107 reviewed Feb 6, 2025

View reviewed changes

TheOneWithTheBraid mentioned this pull request Feb 7, 2025

BREAKING: implement Native OIDC as per MSC 3861 famedly/matrix-dart-sdk#2024

Open

14 tasks

zecakeh mentioned this pull request Feb 15, 2025

refactor(oidc): Use the GET /auth_metadata Matrix endpoint matrix-org/matrix-rust-sdk#4673

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MSC2965: OAuth 2.0 Authorization Server Metadata discovery #2965

MSC2965: OAuth 2.0 Authorization Server Metadata discovery #2965

sandhose commented Jan 14, 2021 •

edited

Loading

erlend-sh commented Aug 9, 2022 •

edited

Loading

hughns commented Aug 14, 2022

turt2live left a comment

turt2live commented Jan 22, 2025 •

edited

Loading

turt2live commented Jan 22, 2025

mscbot commented Jan 22, 2025 •

edited by richvdh

Loading

turt2live commented Jan 22, 2025

turt2live left a comment

turt2live commented Jan 25, 2025

erikjohnston Jan 28, 2025

richvdh Feb 4, 2025

richvdh Feb 4, 2025

clokep Feb 4, 2025

richvdh Feb 4, 2025

richvdh Feb 4, 2025

clokep Feb 4, 2025

tonkku107 Feb 6, 2025


		## Proposal

		This introduces a new Client-Server API endpoint to discover the authorization server metadata used by the homeserver.


		If the homeserver does not offer next-generation authentication as described in [MSC3861], this endpoint should return a 404 with the `M_UNRECOGNIZED` error code.

		In this case, clients should fall back to using the User-Interactive Authentication flows instead to authenticate the user.


		In this case, clients should fall back to using the User-Interactive Authentication flows instead to authenticate the user.

		## Rationale for not using a `.well-known` document

	### Discovery via the well-known client discovery
	### Discovery via existing `.well-known` mechanism

MSC2965: OAuth 2.0 Authorization Server Metadata discovery #2965

Are you sure you want to change the base?

MSC2965: OAuth 2.0 Authorization Server Metadata discovery #2965

Conversation

sandhose commented Jan 14, 2021 • edited Loading

erlend-sh commented Aug 9, 2022 • edited Loading

hughns commented Aug 14, 2022

turt2live left a comment

Choose a reason for hiding this comment

turt2live commented Jan 22, 2025 • edited Loading

turt2live commented Jan 22, 2025

mscbot commented Jan 22, 2025 • edited by richvdh Loading

turt2live commented Jan 22, 2025

turt2live left a comment

Choose a reason for hiding this comment

turt2live 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

sandhose commented Jan 14, 2021 •

edited

Loading

erlend-sh commented Aug 9, 2022 •

edited

Loading

turt2live commented Jan 22, 2025 •

edited

Loading

mscbot commented Jan 22, 2025 •

edited by richvdh

Loading