MSC4190: Device management for application services #4190

sandhose · 2024-09-12T11:35:32Z

Rendered

Homeserver implementations:

Appservice implementations:

In line with matrix-org/matrix-spec#1700, the following disclosure applies:

I am a Software Engineer at Element. This proposal was written and published as an Element employee.

SCT stuff:

checklist

FCP tickyboxes

proposals/4190-as-device-management.md

anoadragon453

Overall lgtm, just a couple sticking points.

proposals/4190-as-device-management.md

This release contains the security fixes from [v1.120.2](https://github.com/element-hq/synapse/releases/tag/v1.120.2). - Fix release process to not create duplicate releases. ([\#18025](element-hq/synapse#18025)) - Support for [MSC4190](matrix-org/matrix-spec-proposals#4190): device management for Application Services. ([\#17705](element-hq/synapse#17705)) - Update [MSC4186](matrix-org/matrix-spec-proposals#4186) Sliding Sync to include invite, ban, kick, targets when `$LAZY`-loading room members. ([\#17947](element-hq/synapse#17947)) - Use stable `M_USER_LOCKED` error code for locked accounts, as per [Matrix 1.12](https://spec.matrix.org/v1.12/client-server-api/#account-locking). ([\#17965](element-hq/synapse#17965)) - [MSC4076](matrix-org/matrix-spec-proposals#4076): Add `disable_badge_count` to pusher configuration. ([\#17975](element-hq/synapse#17975)) - Fix long-standing bug where read receipts could get overly delayed being sent over federation. ([\#17933](element-hq/synapse#17933)) - Add OIDC example configuration for Forgejo (fork of Gitea). ([\#17872](element-hq/synapse#17872)) - Link to element-docker-demo from contrib/docker*. ([\#17953](element-hq/synapse#17953)) - [MSC4108](matrix-org/matrix-spec-proposals#4108): Add a `Content-Type` header on the `PUT` response to work around a faulty behavior in some caching reverse proxies. ([\#17253](element-hq/synapse#17253)) - Fix incorrect comment in new schema delta. ([\#17936](element-hq/synapse#17936)) - Raise setuptools_rust version cap to 1.10.2. ([\#17944](element-hq/synapse#17944)) - Enable encrypted appservice related experimental features in the complement docker image. ([\#17945](element-hq/synapse#17945)) - Return whether the user is suspended when querying the user account in the Admin API. ([\#17952](element-hq/synapse#17952)) - Fix new scheduled tasks jumping the queue. ([\#17962](element-hq/synapse#17962)) - Bump pyo3 and dependencies to v0.23.2. ([\#17966](element-hq/synapse#17966)) - Update setuptools-rust and fix building abi3 wheels in latest version. ([\#17969](element-hq/synapse#17969)) - Consolidate SSO redirects through `/_matrix/client/v3/login/sso/redirect(/{idpId})`. ([\#17972](element-hq/synapse#17972)) - Fix Docker and Complement config to be able to use `public_baseurl`. ([\#17986](element-hq/synapse#17986)) - Fix building wheels for MacOS which was temporarily disabled in Synapse 1.120.2. ([\#17993](element-hq/synapse#17993)) - Fix release process to not create duplicate releases. ([\#17970](element-hq/synapse#17970), [\#17995](element-hq/synapse#17995)) * Bump bytes from 1.8.0 to 1.9.0. ([\#17982](element-hq/synapse#17982)) * Bump pysaml2 from 7.3.1 to 7.5.0. ([\#17978](element-hq/synapse#17978)) * Bump serde_json from 1.0.132 to 1.0.133. ([\#17939](element-hq/synapse#17939)) * Bump tomli from 2.0.2 to 2.1.0. ([\#17959](element-hq/synapse#17959)) * Bump tomli from 2.1.0 to 2.2.1. ([\#17979](element-hq/synapse#17979)) * Bump tornado from 6.4.1 to 6.4.2. ([\#17955](element-hq/synapse#17955))

tulir · 2025-04-02T16:05:30Z

tulir · 2025-04-02T16:08:15Z

This is implemented in Synapse and most mautrix bridges. It'd be nice if it was in the same spec release as the rest of next-gen auth

@mscbot fcp merge

mscbot · 2025-04-02T16:08:18Z

tulir · 2025-04-02T16:08:40Z

@mscbot concern checklist not complete

tulir · 2025-04-05T13:56:14Z

@mscbot resolve checklist not complete

proposals/4190-as-device-management.md

turt2live · 2025-04-05T18:46:45Z

@mscbot concern Breaking change on register endpoint

proposals/4190-as-device-management.md

tulir · 2025-05-10T08:49:05Z

@mscbot concern This actually depends on MSC3202 device masquerading to be useful

proposals/4190-as-device-management.md

turt2live · 2025-08-12T04:10:46Z

@mscbot resolve Breaking change on register endpoint

turt2live

I guess I should press this button too

richvdh

could do with some updates now that MSC3861 is done, and some clarifications around compatibility

richvdh · 2025-08-26T14:21:55Z

proposals/4190-as-device-management.md

+# MSC4190: Device management for application services
+
+[MSC3202] allows application services to handle and send encrypted events.
+One part of [MSC3202] is the ability to masquerade devices using the `device_id`


these links are broken

richvdh · 2025-08-26T14:22:34Z

proposals/4190-as-device-management.md

+As all changes here only apply to application services, guest access is not
+relevant.
+
+### **`PUT /_matrix/client/v3/devices/{deviceId}`**


it would be helpful to link to the existing specs for existing endpoints, so we can see what's changing.

richvdh · 2025-08-26T14:27:30Z

proposals/4190-as-device-management.md

+Furthermore, if [MSC3861] were adopted, the `/login` endpoint would no longer be
+available for application services to use.


MSC3861 has been adopted, so this sentence is outdated.

richvdh · 2025-08-26T14:28:06Z

proposals/4190-as-device-management.md

+Currently, the default behavior for `/register` is to create a new device and
+access token (i.e. login) in addition to creating the user. Similar to `/login`,
+creating an access token would no longer be possible with [MSC3861]. However,


This bit has also been overtaken by the events of MSC3861.

richvdh · 2025-08-26T14:32:17Z

proposals/4190-as-device-management.md

+Therefore, application services MUST call the endpoint with `inhibit_login=true`.
+Calls without the parameter, or with a different value than `true`, will return
+HTTP 400 with a new `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.


I don't see this in the sample implementation, and it feels like an unnecessary breaking change. Are you sure it is necessary to break compatibility with existing app services? Has this been tested in an implementation?

An explicit error rather than silently forcing inhibit_login was added following @turt2live's concern about silent breakage. Looks like it's missing implementation though, so that needs to be fixed in synapse

richvdh · 2025-08-26T14:33:42Z

proposals/4190-as-device-management.md

+The change to `/v3/register` is technically backwards-incompatible, but it will
+break when switching to next-gen auth in any case, so a new endpoint version
+would not be useful.


ah, so it is already broken on those servers that have switched to next-gen auth?

Yeah, the endpoint has silently stopped returning access tokens and device ids regardless of whether inhibit_login is set

Actually looks like synapse doesn't have code for that case (MAS enabled + no MSC4190 + no inhibit_login) 🤔 I wonder if it's just exploding or returning broken access tokens instead

I would definitely like to see this compatibility story clarified in the MSC.

richvdh · 2025-08-26T14:35:57Z

proposals/4190-as-device-management.md

+Until this MSC is stable, application services must opt-in to the new behavior
+by setting the `io.element.msc4190` flag to `true` in their registration file.


why is opting in necessary?

I think it opts into disabling /login and requiring inhibit_login on /register so it can be tested even without MAS? Not entirely sure, but it says it's only opt-in until the MSC is stable, so probably doesn't matter

It does matter, because the fact that there is an opt-in implies that someone is worried it will cause breakage on existing applications, and that logic still applies after the MSC is stable.

richvdh · 2025-08-27T08:03:43Z

@mscbot concern lack of clarity over backwards compatibility

sandhose added 2 commits September 12, 2024 13:34

Device management for application services

c7b4b0c

Update the MSC number

4761dfc

sandhose changed the title ~~Device management for application services~~ MSC4190: Device management for application services Sep 12, 2024

Rename the unstable registration flag

791fbfa

sandhose marked this pull request as ready for review September 12, 2024 13:17

turt2live added proposal A matrix spec change proposal application services kind:core MSC which is critical to the protocol's success needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. labels Sep 12, 2024

turt2live reviewed Sep 12, 2024

View reviewed changes

proposals/4190-as-device-management.md Show resolved Hide resolved

This was referenced Sep 13, 2024

Use MSC4190 to provision devices for E2EE element-hq/matrix-bot-sdk#48

Draft

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

Merged

This was referenced Sep 20, 2024

client,bridgev2: Add support for MSC4190 mautrix/go#288

Closed

End2end encrypted mautrix-signal bridge fails with "Matrix connector: homeserver does not support appservice" element-hq/matrix-authentication-service#3206

Open

MTRNord mentioned this pull request Sep 28, 2024

MSC4203: Sending to-device events to appservices #4203

Open

spantaleev mentioned this pull request Oct 22, 2024

Unable to deploy hookshot bridge with MAS enabled spantaleev/matrix-docker-ansible-deploy#3658

Closed

tulir added implementation-needs-checking The MSC has an implementation, but the SCT has not yet checked it. and removed needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. labels Nov 13, 2024

anoadragon453 reviewed Dec 2, 2024

View reviewed changes

proposals/4190-as-device-management.md Outdated Show resolved Hide resolved

proposals/4190-as-device-management.md Show resolved Hide resolved

TheOneWithTheBraid mentioned this pull request Feb 10, 2025

BREAKING: implement Native OIDC as per MSC 3861 famedly/matrix-dart-sdk#2024

Open

14 tasks

tulir removed the implementation-needs-checking The MSC has an implementation, but the SCT has not yet checked it. label Mar 13, 2025

mscbot added proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period. disposition-merge labels Apr 2, 2025

mscbot added the unresolved-concerns This proposal has at least one outstanding concern label Apr 2, 2025

turt2live self-requested a review April 2, 2025 16:29

turt2live added this to Spec Core Team Workflow Apr 2, 2025

github-project-automation bot moved this to Needs idea feedback / initial review in Spec Core Team Workflow Apr 2, 2025

turt2live moved this from Needs idea feedback / initial review to Ready for FCP ticks in Spec Core Team Workflow Apr 2, 2025

tulir added 2 commits April 5, 2025 16:39

Wrap lines

96ec9ba

Add words to cover checklist and /register breaking change

cffcff9

mscbot removed the unresolved-concerns This proposal has at least one outstanding concern label Apr 5, 2025

turt2live requested changes Apr 5, 2025

View reviewed changes

proposals/4190-as-device-management.md Outdated Show resolved Hide resolved

mscbot added the unresolved-concerns This proposal has at least one outstanding concern label Apr 5, 2025

Return an error in /register

ff0c786

tulir requested a review from turt2live April 8, 2025 10:33

onestacked mentioned this pull request Apr 16, 2025

Add matrix_bridges_msc4190_enabled flag for using msc4190 on supported mautrix bridges. flag for using msc4190 on supported mautrix bridges. spantaleev/matrix-docker-ansible-deploy#4258

Merged

tulir reviewed May 10, 2025

View reviewed changes

proposals/4190-as-device-management.md Outdated Show resolved Hide resolved

dbkr reviewed Jun 24, 2025

View reviewed changes

proposals/4190-as-device-management.md Show resolved Hide resolved

tulir added 2 commits June 25, 2025 14:55

Clarify why /register is changing

ed1ec80

Declare MSC3202 dependency

e66f4d2

turt2live moved this from Ready for FCP ticks to Proposed-FCP at risk in Spec Core Team Workflow Jul 8, 2025

turt2live moved this from Proposed-FCP at risk to Ready for FCP ticks in Spec Core Team Workflow Jul 8, 2025

turt2live mentioned this pull request Aug 12, 2025

MSC4326: Device masquerading for appservices #4326

Open

Point to new MSC for device ID masquerading

2be9161

turt2live approved these changes Aug 12, 2025

View reviewed changes

noelportillo approved these changes Aug 14, 2025

View reviewed changes

richvdh requested changes Aug 26, 2025

View reviewed changes

		Furthermore, if [MSC3861] were adopted, the `/login` endpoint would no longer be
		available for application services to use.

		Until this MSC is stable, application services must opt-in to the new behavior
		by setting the `io.element.msc4190` flag to `true` in their registration file.

MSC4190: Device management for application services #4190

Are you sure you want to change the base?

MSC4190: Device management for application services #4190

Conversation

sandhose commented Sep 12, 2024 • edited by tulir Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

anoadragon453 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tulir commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tulir commented Apr 2, 2025

Uh oh!

mscbot commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tulir commented Apr 2, 2025

Uh oh!

tulir commented Apr 5, 2025

Uh oh!

Uh oh!

turt2live commented Apr 5, 2025

Uh oh!

Uh oh!

tulir commented May 10, 2025

Uh oh!

Uh oh!

turt2live commented Aug 12, 2025

Uh oh!

turt2live left a comment

Choose a reason for hiding this comment

Uh oh!

richvdh left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richvdh commented Aug 27, 2025

Uh oh!

Uh oh!

sandhose commented Sep 12, 2024 •

edited by tulir

Loading

tulir commented Apr 2, 2025 •

edited

Loading

mscbot commented Apr 2, 2025 •

edited

Loading