MSC2967: API scopes #2967

sandhose · 2021-01-14T17:13:01Z

Rendered

Spec is feature complete
- Device handling
- Allow for APIs other than Client-Server in the urn:matrix namespace
- Security considerations section
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

Implementations:

Homeservers

Homeservers:

Synapse with Matrix Authentication Service in OIDC Playground: https://auth-oidc.element.dev
- urn:matrix:client:api:*
- urn:matrix:client:device:XXXX

Clients

Clients need to request scopes appropriately.

SCT stuff:

checklist
FCP tickyboxes

proposals/2967-api-scopes.md

erkinalp

Don't use the word sudo as we do not have a concept of superusers or substitute users in Matrix.

proposals/2967-api-scopes.md

aaronraimist · 2021-03-01T23:39:21Z

Related: matrix-org/matrix-spec#725

clokep · 2023-05-16T14:11:15Z

proposals/2967-api-scopes.md

+
+#### Device ID handling
+
+Presently a device ID is typically generated by the homeserver and is associated with a specific access token. In OAuth 2.0 there is no such thing as a session and so a mapping cannot be handled using the same mechanism.


Is this still true after refresh tokens (MSC2918)? I thought we did a bunch of work in Synapse related to this recently, but maybe I'm confusing different types of tokens.

Technically yes, in practice no as MSC2918-style refresh tokens are almost not adopted by anyone. Is it worth clarifying here?

proposals/2967-api-scopes.md

erikjohnston · 2025-03-19T11:38:45Z

proposals/2967-api-scopes.md

+
+This MSC proposes that the Matrix client is responsible for generating/allocating a device ID.
+A client can create a new device ID by generating a random string and asking for its associated scope on login.
+A client can adopt and rehydrate an existing device ID by asking for its associated scope on login.


I think this needs some rationale for why we need/want to make this change?

I'm a bit hesitant moving the creation of IDs to clients, as it adds all sorts of edges cases that need to be addressed (clashes, incorrect grammar, etc) and means servers can't encode any information in the device ID (which we don't currently, but you could imagine would be useful).

Talked out of band last Friday morning, and there sounds like there is a bunch of historical context here (that has since become mostly outdated). Conclusion was for @sandhose to comment with the background and a bit or a rationale, and then we can make a final call on whether we want device IDs to be generated on the client or server.

Something that I didn't realise is that the spec currently allows clients to generate device IDs when they log in (mostly for bots and the like).

I've explained why the change isn't bad in practice, and the historical context why it is like that in 082625d

Is it possible for the homeserver to still generate a device ID if a urn:matrix:client:device:<device ID> scope is omitted? Or would that be odd behaviour in the OAuth 2.0 world?

Having the ability for the homeserver to generate the device ID does make very simple matrix clients even simpler (no need to randomly generate a string). But I don't feel strongly that this behaviour must remain; it's only a nice-to-have.

Similarly, I recognise that it's useful for the client to provide a device ID upon login (for device rehydration and other use cases). So I'm happy to see that's still supported.

Thanks for the explanation @sandhose. SCT had a discussion and I believe the conclusion was broadly that this is fine for now, there's not much reason to change it so late in the day.

erikjohnston · 2025-03-25T10:07:15Z

proposals/2967-api-scopes.md

+
+This MSC proposes that the Matrix client is responsible for generating/allocating a device ID.
+A client can create a new device ID by generating a random string and asking for its associated scope on login.
+A client can adopt and rehydrate an existing device ID by asking for its associated scope on login.


Talked out of band last Friday morning, and there sounds like there is a bunch of historical context here (that has since become mostly outdated). Conclusion was for @sandhose to comment with the background and a bit or a rationale, and then we can make a final call on whether we want device IDs to be generated on the client or server.

Something that I didn't realise is that the spec currently allows clients to generate device IDs when they log in (mostly for bots and the like).

proposals/2967-api-scopes.md

anoadragon453 · 2025-03-25T17:07:25Z

proposals/2967-api-scopes.md

+
+This MSC proposes that the Matrix client is responsible for generating/allocating a device ID.
+A client can create a new device ID by generating a random string and asking for its associated scope on login.
+A client can adopt and rehydrate an existing device ID by asking for its associated scope on login.


Is it possible for the homeserver to still generate a device ID if a urn:matrix:client:device:<device ID> scope is omitted? Or would that be odd behaviour in the OAuth 2.0 world?

Having the ability for the homeserver to generate the device ID does make very simple matrix clients even simpler (no need to randomly generate a string). But I don't feel strongly that this behaviour must remain; it's only a nice-to-have.

Similarly, I recognise that it's useful for the client to provide a device ID upon login (for device rehydration and other use cases). So I'm happy to see that's still supported.

proposals/2967-api-scopes.md

Co-authored-by: Andrew Morgan <[email protected]>

Co-authored-by: Patrick Cloke <[email protected]>

mscbot · 2025-03-31T16:01:56Z

🔔 This is now entering its final comment period, as per the review above. 🔔

mscbot · 2025-04-05T16:02:06Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

zecakeh · 2025-05-25T09:50:24Z

spec PR: matrix-org/matrix-spec#2149

richvdh · 2025-06-17T16:48:59Z

spec PR: matrix-org/matrix-spec#2149

Merged! 🎉

API Scopes MSC

a2e9656

turt2live changed the title ~~MSC2967: [WIP] API scope restriction~~ [WIP] MSC2967: API scope restriction Jan 14, 2021

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

turt2live added kind:feature MSC for not-core and not-maintenance stuff proposal A matrix spec change proposal labels Jan 14, 2021

This was referenced Jan 15, 2021

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

Merged

Ability to mint access_tokens with restricted scope. matrix-org/matrix-spec#725

Closed

kegsay reviewed Jan 15, 2021

View reviewed changes

proposals/2967-api-scopes.md Outdated Show resolved Hide resolved

erkinalp suggested changes Jan 31, 2021

View reviewed changes

proposals/2967-api-scopes.md Outdated Show resolved Hide resolved

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 16, 2022 16:30

Proposed insufficient privilege response format

544d75b

Remove realm as not required

d49f2d8

hughns mentioned this pull request May 25, 2022

Use something more secure than bearer tokens for auth matrix-org/matrix-spec#259

Open

zecakeh mentioned this pull request Jul 25, 2022

client-api: Add support for API scope restriction ruma/ruma#1249

Merged

hughns added 2 commits July 31, 2022 19:50

Clarifications + update on latest device management proposal

23c7638

Revised namespace structure + unstable prefixes

b609c2b

hughns changed the title ~~[WIP] MSC2967: API scope restriction~~ [WIP] MSC2967: API scopes Aug 3, 2022

Revise prefix for device ID

f07b466

hughns mentioned this pull request Aug 4, 2022

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

Merged

hughns added 3 commits August 5, 2022 10:08

Reference to MSC3861 + cleanup

1ce049e

Add scope for guest access and tidy up

5c57507

No need for UIA scope

5afb697

hughns changed the title ~~[WIP] MSC2967: API scopes~~ [WIP] MSC2967: OIDC API scopes Feb 28, 2023

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

clokep reviewed May 16, 2023

View reviewed changes

proposals/2967-api-scopes.md Outdated Show resolved Hide resolved

clokep reviewed May 16, 2023

View reviewed changes

proposals/2967-api-scopes.md Outdated Show resolved Hide resolved

kerryarchibald mentioned this pull request Jun 13, 2023

OIDC: Make authorization request element-hq/element-web#25574

Closed

Reword how the device ID is requested

abbae1e

erikjohnston reviewed Mar 19, 2025

View reviewed changes

erikjohnston requested changes Mar 25, 2025

View reviewed changes

Explain why we keep the device ID generation on the client

082625d

anoadragon453 reviewed Mar 25, 2025

View reviewed changes

clokep reviewed Mar 25, 2025

View reviewed changes

proposals/2967-api-scopes.md Outdated Show resolved Hide resolved

proposals/2967-api-scopes.md Outdated Show resolved Hide resolved

sandhose and others added 3 commits March 26, 2025 11:53

MSCXXXX is a better placeholder

089a789

Co-authored-by: Andrew Morgan <[email protected]>

The scope MUST have a device ID

858b7be

Clarify that device IDs are still unique per user

c9f8690

Co-authored-by: Patrick Cloke <[email protected]>

mscbot added final-comment-period This MSC has entered a final comment period in interest to approval, postpone, or delete in 5 days. and removed proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period. labels Mar 31, 2025

turt2live moved this from Ready for FCP ticks to In FCP in Spec Core Team Backlog Mar 31, 2025

mscbot added finished-final-comment-period and removed disposition-merge final-comment-period This MSC has entered a final comment period in interest to approval, postpone, or delete in 5 days. labels Apr 5, 2025

turt2live merged commit b2ea1a7 into matrix-org:main Apr 5, 2025
1 check passed

turt2live moved this from In FCP to Requires spec writing in Spec Core Team Backlog Apr 5, 2025

turt2live added spec-pr-missing Proposal has been implemented and is being used in the wild but hasn't yet been added to the spec and removed finished-final-comment-period labels Apr 5, 2025

NinekoTheCat mentioned this pull request Apr 18, 2025

Implement MSC2967 matrix-construct/tuwunel#16

Open

tulir added spec-pr-in-review A proposal which has been PR'd against the spec and is in review and removed spec-pr-missing Proposal has been implemented and is being used in the wild but hasn't yet been added to the spec labels May 25, 2025

turt2live moved this from Requires spec writing to Requires spec PR review in Spec Core Team Backlog Jun 10, 2025

richvdh added merged A proposal whose PR has merged into the spec! and removed spec-pr-in-review A proposal which has been PR'd against the spec and is in review labels Jun 17, 2025

turt2live moved this from Requires spec PR review to Done to some definition in Spec Core Team Backlog Jun 17, 2025


		#### Device ID handling

		Presently a device ID is typically generated by the homeserver and is associated with a specific access token. In OAuth 2.0 there is no such thing as a session and so a mapping cannot be handled using the same mechanism.

MSC2967: API scopes #2967

MSC2967: API scopes #2967

Uh oh!

Conversation

sandhose commented Jan 14, 2021 • edited by turt2live Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Homeservers

Clients

Uh oh!

Uh oh!

erkinalp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aaronraimist commented Mar 1, 2021 • edited by richvdh 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!

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!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mscbot commented Mar 31, 2025

Uh oh!

mscbot commented Apr 5, 2025

Uh oh!

Uh oh!

zecakeh commented May 25, 2025

Uh oh!

richvdh commented Jun 17, 2025

Uh oh!

Uh oh!

sandhose commented Jan 14, 2021 •

edited by turt2live

Loading

aaronraimist commented Mar 1, 2021 •

edited by richvdh

Loading