MSC4363: OAuth step up authentication by Johennes · Pull Request #4363 · matrix-org/matrix-spec-proposals

Johennes · 2025-09-30T11:02:42Z

Rendered

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

turt2live · 2025-09-30T21:32:31Z

Implementation requirements:

Client (ideally multiple)

Server

Server: Continuwuity

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

zecakeh

Just a couple of nits on the wording.

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>

Co-authored-by: Hugh Nimmo-Smith <hughns@users.noreply.github.com>

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

Johennes · 2025-10-31T14:01:04Z

+### Cross-signing key reset
+
+Implementations MAY use this proposal to replace UIA when the client has obtained its access token
+via the OAuth APIs. The only endpoint currently using UIA for which this is relevant is
+[/_matrix/client/v3/keys/device_signing/upload].


We could consider introducing a dedicated scope to support this. Though I think it is not strictly needed. The only advantage I can think of is that clients could request the scope ahead of hitting the endpoint.

hughns · 2025-11-03T14:40:28Z

+
+### Cross-signing key reset
+
+Implementations MAY use this proposal to replace UIA when the client has obtained its access token


Problem: when the homeserver receives a request to POST /_matrix/client/v3/keys/device_signing/upload, how does it know whether it should respond with the m.oauth flow stage from MSC4312, or the new M_INSUFFICIENT_USER_AUTHENTICATION errcode?

We would want the server to be backwards compatible with older clients, so I think the server needs to know what the client supports.

So, basically some kind of versioning:

query param?

body param?

/_matrix/client/v3/keys/device_signing/upload -> /_matrix/client/v4/keys/device_signing/upload?

There is also the possibility of returning both MSCs fields in the body of the response, since there are no conflicts with the keys.

A client that doesn't support this MSC should be able to handle the UIA fields, and a client that supports this MSC will prefer to handle these new fields.

gingershaped · 2026-09-06T00:49:41Z

+include any scopes, the client SHOULD use the same scopes it used during login on the authorization
+request.
+
+Following successful authorization, the client's previous access token SHOULD be invalidated and a


I can't figure out how the homeserver is supposed to tell that an existing client is authenticating again, and not a new client. Is the client supposed to supply its access token in the OAuth request somehow?

Hm, I think it technically doesn't need to because the client_id should identify the client? The AS should, however, be able to identify a possibly existing session based on cookies, I assume.

Hm, I think it technically doesn't need to because the client_id should identify the client?

The client_id may not be unique for each device. Continuwuity derives the client_id from a hash of the client registration to avoid filling the database up with thousands of identical registrations.

The AS should, however, be able to identify a possibly existing session based on cookies, I assume.

Continuwuity's session cookie only uniquely identifies a single login to the web dashboard; it doesn't have any relation to Matrix devices. The only thing that identifies a Matrix device is its access token.

I'm asking about this because MSC4484 needs some sort of temporary privilege escalation mechanism to be ergonomically usable by clients. Since registering a device is a hard requirement under the current OAuth scheme, a client that wants to use the server administration OAuth scope can't obtain a temporary privileged token without creating a useless new device. Therefore some way for the client to obtain more privileges on its existing token is necessary.

If it's necessary to track the device ID, then the homeserver could just add the urn:matrix:client:device:<device_id> scope token to the scope field in the error response. If there is no scope field in the error the MSC says that the client should use the same as during login so it should also include the device ID of the session in theory?

That would probably work for identifying the device, yes.

gingershaped · 2026-09-08T21:19:54Z

+include any scopes, the client SHOULD use the same scopes it used during login on the authorization
+request.
+
+Following successful authorization, the client's previous access token SHOULD be invalidated and a


Should a new refresh token be issued as well, or should the old one be reused?

Johennes changed the title ~~MSCXXXX: OAuth step up authentication~~ MSC4363: OAuth step up authentication Sep 30, 2025

MSC4363: OAuth step up authentication

fd17d14

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

Johennes force-pushed the johannes/oauth-step-up-authentication branch from 5769520 to fd17d14 Compare September 30, 2025 11:03

Johennes marked this pull request as ready for review September 30, 2025 11:04

Johennes mentioned this pull request Sep 30, 2025

MSC4312: Resetting cross-signing keys in the OAuth world #4312

Merged

4 tasks done

turt2live reviewed Sep 30, 2025

View reviewed changes

zecakeh reviewed Oct 1, 2025

View reviewed changes

Comment thread proposals/4363-oauth-step-up-authentication.md

Comment thread proposals/4363-oauth-step-up-authentication.md Outdated

Comment thread proposals/4363-oauth-step-up-authentication.md Outdated

Johennes added 2 commits October 1, 2025 16:24

Add WWW-Authenticate and insufficient_scope alternatives

4c716b6

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

Clarify which scopes to use when the challenge doesn't include any

d48b01d

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

zecakeh reviewed Oct 1, 2025

View reviewed changes

Comment thread proposals/4363-oauth-step-up-authentication.md Outdated

Johennes added 3 commits October 2, 2025 08:33

Don't distinguish homeservers and authorization servers

bbae0bb

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

Reify semantics of token issuance and use

8cdb9b6

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

Fix typos

4bf1cf0

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

zecakeh reviewed Oct 2, 2025

View reviewed changes

Comment thread proposals/4363-oauth-step-up-authentication.md Outdated

Comment thread proposals/4363-oauth-step-up-authentication.md Outdated

Johennes and others added 2 commits October 2, 2025 16:52

authentication -> authorization

e4c0b02

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>

Renewing -> Refreshing

5104f18

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>

hughns requested review from hughns and sandhose October 31, 2025 13:10

hughns reviewed Oct 31, 2025

View reviewed changes

Comment thread proposals/4363-oauth-step-up-authentication.md Outdated

Johennes and others added 2 commits October 31, 2025 14:31

Clarify type of error

91c8563

Co-authored-by: Hugh Nimmo-Smith <hughns@users.noreply.github.com>

Mention application of the mechanism for cross-signing key reset

f2bf39f

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

Johennes commented Oct 31, 2025

View reviewed changes

hughns reviewed Nov 3, 2025

View reviewed changes

Johennes mentioned this pull request Jun 1, 2026

MSC4484: Server Administration OAuth Scope #4484

Open

gingershaped reviewed Sep 6, 2026

View reviewed changes

gingershaped mentioned this pull request Sep 8, 2026

common: Add unstable support for MSC4363 ruma/ruma#2587

Merged

gingershaped reviewed Sep 8, 2026

View reviewed changes

chrislearn mentioned this pull request Oct 1, 2026

Support OAuth step-up authentication challenges (MSC4363) palpo-im/palpo#487

Open


		### Cross-signing key reset

		Implementations MAY use this proposal to replace UIA when the client has obtained its access token

Conversation

Johennes commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zecakeh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zecakeh Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gingershaped Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zecakeh Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Johennes commented Sep 30, 2025 •

edited

Loading

zecakeh Nov 5, 2025 •

edited

Loading

gingershaped Sep 8, 2026 •

edited

Loading

zecakeh Sep 8, 2026 •

edited

Loading