From c7b4b0c7819887c1cfa1e5cd896069fb872545d5 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Thu, 12 Sep 2024 13:34:32 +0200 Subject: [PATCH 1/6] Device management for application services --- proposals/4190-as-device-management.md | 48 ++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 proposals/4190-as-device-management.md diff --git a/proposals/4190-as-device-management.md b/proposals/4190-as-device-management.md new file mode 100644 index 00000000000..22a0ddfa1e6 --- /dev/null +++ b/proposals/4190-as-device-management.md @@ -0,0 +1,48 @@ +# 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` query parameter on C-S API requests, which eliminates the need to maintain individual access tokens for each application service user. + +However, application services don't have an endpoint to create devices for their users, which means that, in practice, encrypted application services still use `/login` with the `m.login.application_service` login type to create devices for their users. + +Consequently, such application services leave many unused but active access tokens for those users. + +Furthermore, if [MSC3861] were adopted, the `/login` endpoint would no longer be available for application services to use. + +This MSC proposes a dedicated API endpoint for application services to create and delete devices for users, addressing the existing gap to enable encrypted application services without `/login`. + +## Proposal + +This MSC proposes to extend existing endpoints to allow application services to create and delete devices for their users without relying on the `/login` and `/logout` mechanisms. + +### **`PUT /_matrix/client/v3/devices/{deviceId}`** + +This endpoint is updated to allow the creation of a new device for a user, if the device ID does not exist. +This behavior is only available to application services. + +This endpoint will use the 201 status code to indicate that a new device was created, in addition to the existing 200 status code for existing devices. + +### **`DELETE /_matrix/client/v3/devices/{deviceId}`** + +This endpoint no longer requires User-Interactive Authentication for application services. + +### **`POST /_matrix/client/v3/delete_devices`** + +This endpoint no longer requires User-Interactive Authentication for application services. + +### **`POST /_matrix/client/v3/register`** + +This endpoint no longer generates a new access token, as if `inhibit_login` was set to `true` in the request by default. + +## Alternatives + +A new set of endpoints dedicated to application services could be added to the specification, like `GET|PUT|DELETE /_matrix/client/v3/appservices/{appId}/devices/{deviceId}`. + +This would have the advantage of not changing the behavior of existing endpoints. + +## Unstable prefix + +Until this MSC is stable, application services must opt-in to the new behavior by setting the `mscxxx_device_management` flag to `true` in their registration file. + +[MSC3202]: https://github.com/matrix-org/matrix-spec-proposals/pull/3202 +[MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 From 4761dfc4a51e4e81e31bf374c1d62a9ab5661a27 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Thu, 12 Sep 2024 13:37:21 +0200 Subject: [PATCH 2/6] Update the MSC number --- proposals/4190-as-device-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4190-as-device-management.md b/proposals/4190-as-device-management.md index 22a0ddfa1e6..ef927968e4d 100644 --- a/proposals/4190-as-device-management.md +++ b/proposals/4190-as-device-management.md @@ -42,7 +42,7 @@ This would have the advantage of not changing the behavior of existing endpoints ## Unstable prefix -Until this MSC is stable, application services must opt-in to the new behavior by setting the `mscxxx_device_management` flag to `true` in their registration file. +Until this MSC is stable, application services must opt-in to the new behavior by setting the `msc4190_device_management` flag to `true` in their registration file. [MSC3202]: https://github.com/matrix-org/matrix-spec-proposals/pull/3202 [MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 From 791fbfacf4a07233664d97ed865a9c2e50012eb3 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Thu, 12 Sep 2024 14:02:14 +0200 Subject: [PATCH 3/6] Rename the unstable registration flag --- proposals/4190-as-device-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4190-as-device-management.md b/proposals/4190-as-device-management.md index ef927968e4d..de2214fba55 100644 --- a/proposals/4190-as-device-management.md +++ b/proposals/4190-as-device-management.md @@ -42,7 +42,7 @@ This would have the advantage of not changing the behavior of existing endpoints ## Unstable prefix -Until this MSC is stable, application services must opt-in to the new behavior by setting the `msc4190_device_management` flag to `true` in their registration file. +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. [MSC3202]: https://github.com/matrix-org/matrix-spec-proposals/pull/3202 [MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 From 96ec9ba062a1af641dc866eff806d29255f6e43b Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 5 Apr 2025 16:39:57 +0300 Subject: [PATCH 4/6] Wrap lines --- proposals/4190-as-device-management.md | 40 ++++++++++++++++++-------- 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/proposals/4190-as-device-management.md b/proposals/4190-as-device-management.md index de2214fba55..a75f14eb3dc 100644 --- a/proposals/4190-as-device-management.md +++ b/proposals/4190-as-device-management.md @@ -1,26 +1,39 @@ # 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` query parameter on C-S API requests, which eliminates the need to maintain individual access tokens for each application service user. +One part of [MSC3202] is the ability to masquerade devices using the `device_id` +query parameter on C-S API requests, which eliminates the need to maintain +individual access tokens for each application service user. -However, application services don't have an endpoint to create devices for their users, which means that, in practice, encrypted application services still use `/login` with the `m.login.application_service` login type to create devices for their users. +However, application services don't have an endpoint to create devices for their +users, which means that, in practice, encrypted application services still use +`/login` with the `m.login.application_service` login type to create devices for +their users. -Consequently, such application services leave many unused but active access tokens for those users. +Consequently, such application services leave many unused but active access +tokens for those users. -Furthermore, if [MSC3861] were adopted, the `/login` endpoint would no longer be available for application services to use. +Furthermore, if [MSC3861] were adopted, the `/login` endpoint would no longer be +available for application services to use. -This MSC proposes a dedicated API endpoint for application services to create and delete devices for users, addressing the existing gap to enable encrypted application services without `/login`. +This MSC proposes a dedicated API endpoint for application services to create +and delete devices for users, addressing the existing gap to enable encrypted +application services without `/login`. ## Proposal -This MSC proposes to extend existing endpoints to allow application services to create and delete devices for their users without relying on the `/login` and `/logout` mechanisms. +This MSC proposes to extend existing endpoints to allow application services to +create and delete devices for their users without relying on the `/login` and +`/logout` mechanisms. ### **`PUT /_matrix/client/v3/devices/{deviceId}`** -This endpoint is updated to allow the creation of a new device for a user, if the device ID does not exist. -This behavior is only available to application services. +This endpoint is updated to allow the creation of a new device for a user, if +the device ID does not exist. This behavior is only available to application +services. -This endpoint will use the 201 status code to indicate that a new device was created, in addition to the existing 200 status code for existing devices. +This endpoint will use the 201 status code to indicate that a new device was +created, in addition to the existing 200 status code for existing devices. ### **`DELETE /_matrix/client/v3/devices/{deviceId}`** @@ -32,17 +45,20 @@ This endpoint no longer requires User-Interactive Authentication for application ### **`POST /_matrix/client/v3/register`** -This endpoint no longer generates a new access token, as if `inhibit_login` was set to `true` in the request by default. +This endpoint no longer generates a new access token, as if `inhibit_login` was +set to `true` in the request by default. ## Alternatives -A new set of endpoints dedicated to application services could be added to the specification, like `GET|PUT|DELETE /_matrix/client/v3/appservices/{appId}/devices/{deviceId}`. +A new set of endpoints dedicated to application services could be added to the +specification, like `GET|PUT|DELETE /_matrix/client/v3/appservices/{appId}/devices/{deviceId}`. This would have the advantage of not changing the behavior of existing endpoints. ## Unstable prefix -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. +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. [MSC3202]: https://github.com/matrix-org/matrix-spec-proposals/pull/3202 [MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 From cffcff9ce51b93dd707ff03d877a57706ce36fef Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 5 Apr 2025 16:52:10 +0300 Subject: [PATCH 5/6] Add words to cover checklist and /register breaking change --- proposals/4190-as-device-management.md | 28 ++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/proposals/4190-as-device-management.md b/proposals/4190-as-device-management.md index a75f14eb3dc..e3b5b147472 100644 --- a/proposals/4190-as-device-management.md +++ b/proposals/4190-as-device-management.md @@ -26,6 +26,9 @@ This MSC proposes to extend existing endpoints to allow application services to create and delete devices for their users without relying on the `/login` and `/logout` mechanisms. +As all changes here only apply to application services, guest access is not +relevant. + ### **`PUT /_matrix/client/v3/devices/{deviceId}`** This endpoint is updated to allow the creation of a new device for a user, if @@ -35,6 +38,10 @@ services. This endpoint will use the 201 status code to indicate that a new device was created, in addition to the existing 200 status code for existing devices. +The endpoint is rate limited. Servers may want to use login rate limits for +device creation, although in most cases application services will disable all +rate limits anyway. + ### **`DELETE /_matrix/client/v3/devices/{deviceId}`** This endpoint no longer requires User-Interactive Authentication for application services. @@ -45,8 +52,21 @@ This endpoint no longer requires User-Interactive Authentication for application ### **`POST /_matrix/client/v3/register`** -This endpoint no longer generates a new access token, as if `inhibit_login` was -set to `true` in the request by default. +This endpoint no longer generates a new access token for application services, +as if `inhibit_login` was set to `true` in the request by default. + +## Potential issues + +The change to `/v3/register` is technically backwards-incompatible. However, +most application services likely ignore the returned access token, and next-gen +auth will break the token generation anyway. It's better to stop returning a +token than break the endpoint entirely by returning an error. + +## Security considerations + +This MSC lets application services delete devices without the usual +re-authentication requirement. It is considered an acceptable risk, as +application services have to be registered by the server admin. ## Alternatives @@ -55,6 +75,10 @@ specification, like `GET|PUT|DELETE /_matrix/client/v3/appservices/{appId}/devic This would have the advantage of not changing the behavior of existing endpoints. +## Dependencies + +None. While this MSC is meant for next-gen auth, it can be used independently. + ## Unstable prefix Until this MSC is stable, application services must opt-in to the new behavior From ff0c786190a31feb96fef97ae3a80e7485a6d749 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 5 Apr 2025 21:58:25 +0300 Subject: [PATCH 6/6] Return an error in /register --- proposals/4190-as-device-management.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/proposals/4190-as-device-management.md b/proposals/4190-as-device-management.md index e3b5b147472..639fcf56cea 100644 --- a/proposals/4190-as-device-management.md +++ b/proposals/4190-as-device-management.md @@ -52,15 +52,20 @@ This endpoint no longer requires User-Interactive Authentication for application ### **`POST /_matrix/client/v3/register`** -This endpoint no longer generates a new access token for application services, -as if `inhibit_login` was set to `true` in the request by default. +Application services will no longer receive access tokens or device IDs and +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. ## Potential issues -The change to `/v3/register` is technically backwards-incompatible. However, -most application services likely ignore the returned access token, and next-gen -auth will break the token generation anyway. It's better to stop returning a -token than break the endpoint entirely by returning an error. +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. + +The endpoint could just stop returning access tokens to avoid breaking existing +appservices that don't read that field, but an explicit error was chosen to +avoid silent breakage of appservices that do depend on the field. ## Security considerations