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

[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)?

[ShadowJonathan]

Couldn't this be replaced with; the client requesting for a seperate token with only the required scope to perform this action, only for it to be dropped (deactivated) immidiately after?

Something about upgrading the same token doesn't sit well with me from a security perspective, it might be a deliberately locked-down token, and/or multiple actions at once could race to upgrade/downgrade the current token.

[kate-shine]

Having a separate token purely for one scope / set of scopes sounds like a really good idea, especially for race condition reasons. Races could be also avoided by introducing state on AS/OP side, but that is quite out of scope of oauth2 specification (if I'm not mistaken)

At the same time, it would make specification compatible with more possible OP implementations.

Making it single use would be easily doable using jti claim on that token.

[richvdh]

My understanding is that we no longer attempt to provide a replacement for UIA, so this thread is probably outdated too. @sandhose could you confirm?

[sandhose]

We gave alternatives to all of the operations currently protected by UIA with a deeplink to the account management UI through MSC4191

Longterm, the idea is to:

• define scopes for specific actions
• define a way to step-up authentication, temporarily or not

But for the sake of simplicity, this isn't in part of the proposal

[tonkku107]

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

[tonkku107]

Suggested change

	&redirect_uri=https://app.example.com/oauth2-callback
	&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth2-callback

URL encoding

[sandhose]

Same here, this is done for readability

[tonkku107]

Suggested change

	redirect_uri = https://app.example.com/oauth2-callback &
	scope = urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD &
	redirect_uri = https%3A%2F%2Fapp.example.com%2Foauth2-callback &
	scope = urn%3Amatrix%3Aclient%3Aapi%3A*+urn%3Amatrix%3Aclient%3Adevice%3AAAABBBCCCDDD &

These values would be URL encoded

[sandhose]

I kept this part simplified with no URL-encoding and extra spaces. It might be worth saying that, and give the actual url-encoded, with no space added URL in addition

[tonkku107]

The values are already listed above in their non-url-encoded format. The oauth specs also include line breaks in their examples but url-encode the values

[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. 👍