MSC2965: OAuth 2.0 Authorization Server Metadata discovery

[sandhose]

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]

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]

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

[sandhose]

@Tachi107 This is a really good point! Unfortunately, the RFC states that applications must not use the general .well-known/oauth-authorization-server endpoint but rather set their own well-known document.

I've reworked the MSC to instead expose the authorization metadata directly as a C-S API endpoint

[turt2live]

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

[turt2live]

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:

• Are appropriate implementation(s)
  specified in the MSC’s PR description?
• Are all MSCs that this MSC depends on already accepted?
• For each new endpoint that is introduced:
  • Have authentication requirements been specified?
  • Have rate-limiting requirements been specified?
  • Have guest access requirements been specified?
  • Are error responses specified?
    • Does each error case have a specified errcode (e.g. M_FORBIDDEN) and HTTP status code?
      • If a new errcode is introduced, is it clear that it is new?
• Will the MSC require a new room version, and if so, has that been made clear?
  • Is the reason for a new room version clearly stated? For example,
    modifying the set of redacted fields changes how event IDs are calculated,
    thus requiring a new room version.
• Are backwards-compatibility concerns appropriately addressed?
• Are the endpoint conventions honoured?
  • Do HTTP endpoints use_underscores_like_this?
  • Will the endpoint return unbounded data? If so, has pagination been considered?
  • If the endpoint utilises pagination, is it consistent with
    the appendices?
• An introduction exists and clearly outlines the problem being solved.
  Ideally, the first paragraph should be understandable by a non-technical audience.
• All outstanding threads are resolved
  • All feedback is incorporated into the proposal text itself, either as a fix or noted as an alternative
• While the exact sections do not need to be present,
  the details implied by the proposal template are covered. Namely:
  • Introduction
  • Proposal text
  • Potential issues
  • Alternatives
  • Dependencies
• Stable identifiers are used throughout the proposal, except for the unstable prefix section
  • Unstable prefixes consider the awkward accepted-but-not-merged state
  • Chosen unstable prefixes do not pollute any global namespace (use “org.matrix.mscXXXX”, not “org.matrix”).
• Changes have applicable Sign Off from all authors/editors/contributors
• There is a dedicated "Security Considerations" section which detail
  any possible attacks/vulnerabilities this proposal may introduce, even if this is "None.".
  See RFC3552 for things to think about,
  but in particular pay attention to the OWASP Top Ten.

[turt2live]

Implementation lgtm. Concerns are relatively minor as well:

@mscbot fcp merge

[mscbot]

Team member @mscbot has proposed to merge this. The next step is review by the rest of the tagged people:

• @clokep
• @dbkr
• @uhoreg
• @turt2live
• @ara4n
• @anoadragon453
• @richvdh
• @tulir
• @erikjohnston
• @KitsuneRal

Concerns:

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

Once at least 75% of reviewers approve (and there are no outstanding concerns), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for information about what commands tagged team members can give me.

[turt2live]

@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

[turt2live]

read-up-to marker

(thanks for keeping these updated)

[turt2live]

@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]

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.