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

[sandhose]

Rendered

Related: matrix-org/matrix-spec#636

Status:

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

Part of the following proposal:

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

Implementations:

Homeservers

• Synapse implementation with Matrix Authentication Service

Clients

In OIDC-native mode:

• Element Web
• hydrogen
• files-sdk-demo
• Element X iOS
• Element X Android

---

SCT stuff:

checklist

FCP tickyboxes

[sandhose]

Related issue: matrix-org/matrix-spec#636

Related MSCs: #2965, #2966, #2967

---

In this MSC, there are a few areas that still need work.

First, it outlines different profiles of clients. One important client type that is not yet covered by it are CLI tools.
The natural fit for this would be the client credential grant, taking form of either a client_secret or a secret key for JWT signing.
The problem with this is that it authenticates as "the client", not a user. How users should delegate authorization to other clients is a bit unclear. Maybe RFC 8693 helps with that.

Second, there are the parts that we enforce.
For example, I chose to enforce PKCE for public clients. Since most of Matrix clients are public, I think it makes sense to enforce the current best practices here.
Another example would be credentials for confidential clients. Right now nothing is specified, but it might make sense to encourage the usage of keypairs instead of client secrets. If we encourage that, should it be enforced?
Last example, in the part about the request to the authz endpoint, I mention that the state parameter should be unpredictable. Some profiles go further than that to enforce a minimum entropy for this parameter.

Third there is device handling in general. MSC2967 talks a bit about this, but there will definitely be some changes to the device API.
An example of this is that we might want to surface client metadata when querying the devices instead of just an arbitrary name.
Another open question is should a device be deleted on logout? If so, how do we handle device that are used by multiple clients (which is technically possible with the solution proposed in #2967)?

[tonkku107]

Some nitpicky things things I noticed while reading through the updated version and suggested fixes

[Johennes]

OAuth also has Pushed Authorization Requests which attempt to alleviate some of the issues of query parameters (see e.g. the introduction of RFC9126). I wonder if it'd be worth to consider these from the outset here?

[sandhose]

This is a good point, although because most Matrix clients will be public clients, we wouldn't really gain from the cryptographic integrity or confidentiality advantages PAR gives us. It would help us in two other ways though:

• validating the authorisation request earlier, to possibly show a user-friendly error within the client
• large authorisation requests, if we start having fine-grained authorisations

This is why for now, I'd prefer leaving them out of the proposal for the sake of simplicity, and introduce them later (probably alongside RAR) when we actually need it

[Johennes]

Makes sense and sounds fair to me. 👍

[turt2live]

(it would be good to have this alternative documented in the MSC)

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

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

• FCP checklist 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 FCP checklist incomplete

[zecakeh]

Don't we also need code_challenge_methods_supported for the PKCE methods?

[zecakeh]

Since it seems that using the S256 method is required below, maybe it should be mentioned here?