From 8350b88a3dee942769603c5599521ac081aed4f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 16 Dec 2025 20:39:06 +0100 Subject: [PATCH 1/4] Spec Account management for OAuth 2.0 API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC4191. Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 52 ++++++++++++++++++- .../client-server/oauth_server_metadata.yaml | 26 ++++++++++ 2 files changed, 77 insertions(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2460776f..63308090 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -640,7 +640,7 @@ manage their account like [changing their password](#password-management), [deactivating their account](#account-deactivation). With the OAuth 2.0 API, all account management is done via the homeserver's web -UI. +UI that can be accessed by users via the [account management URL](#oauth-20-account-management). ### Legacy API @@ -2262,6 +2262,56 @@ The server SHOULD return one of the following responses: - For other errors, the server returns a `400 Bad Request` response with error details +#### Account management {id="oauth-20-account-management"} + +{{% added-in v="1.17" %}} + +All account management is done via the homeserver’s web UI as all endpoints that +require User-Interactive Authentication are unsupported by this authentication +API. + +This specification defines extensions to the [OAuth Authorization Server +Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata) +to offer clients a way to deep-link to the account management capabilities of +the homeserver to allow the user to complete the account management operations +in a browser. + +##### Account management URL discovery + +The [OAuth 2.0 authorization server metadata](#server-metadata-discovery) is +extended to include the following fields: + +| Field | Description | +|----------------------------------------|-------------------------------------------------------------------------------------------------| +| `account_management_uri` | The URL where the user is able to access the account management capabilities of the homeserver. | +| `account_management_actions_supported` | An array of actions that the account management URL supports, as defined below. | + +##### Account management URL parameters + +The account management URL MAY accept the following query parameters: + +| Parameter | Description | +|-------------|---------------------------------------------------------------------------------------------------------------------------------------| +| `action` | **Optional**. The action that the user wishes to take. Must match one of the actions in `account_management_actions_supported` above. | +| `device_id` | **Optional**. Identifies a particular Matrix device ID for actions that support it. | + +If the `org.matrix.device_view` or `org.matrix.device_delete` actions are +advertised as supported by the server then the server SHOULD support the +`device_id` parameter. + +##### Account management URL actions + +The following account management actions are defined: + +| Action | Description | +|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| `org.matrix.profile` | The user wishes to view/edit their profile (name, avatar, contact details). | +| `org.matrix.devices_list` | The user wishes to view a list of their devices. | +| `org.matrix.device_view` | The user wishes to view the details of a specific device. A `device_id` should be provided. | +| `org.matrix.device_delete` | The user wishes to delete/log out a specific device. A `device_id` should be provided. | +| `org.matrix.account_deactivate` | The user wishes to deactivate their account. | +| `org.matrix.cross_signing_reset` | The user wishes to reset their cross-signing identity. Servers SHOULD use this action in the URL of the [`m.oauth`](#oauth-authentication) UIA type. | + ### Account moderation #### Account locking diff --git a/data/api/client-server/oauth_server_metadata.yaml b/data/api/client-server/oauth_server_metadata.yaml index 4cdb3aa6..fb976c56 100644 --- a/data/api/client-server/oauth_server_metadata.yaml +++ b/data/api/client-server/oauth_server_metadata.yaml @@ -139,6 +139,32 @@ paths: items: type: string description: A prompt value that the server supports. + account_management_uri: + x-addedInMatrixVersion: "1.17" + type: string + format: uri + description: |- + The URL where the user is able to access the account management capabilities + of the homeserver. + + This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management). + account_management_uri_supported: + x-addedInMatrixVersion: "1.17" + type: array + description: |- + List of actions that the account management URL supports. + + This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management). + items: + type: string + enum: + - "org.matrix.profile" + - "org.matrix.devices_list" + - "org.matrix.device_view" + - "org.matrix.device_delete" + - "org.matrix.account_deactivate" + - "org.matrix.cross_signing_reset" + description: An action that the account management URL supports. required: - issuer - authorization_endpoint From 80c6ffd1d845822f9ba93a163133de23a6a63456 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 16 Dec 2025 20:42:27 +0100 Subject: [PATCH 2/4] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/2270.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2270.feature diff --git a/changelogs/client_server/newsfragments/2270.feature b/changelogs/client_server/newsfragments/2270.feature new file mode 100644 index 00000000..b675c947 --- /dev/null +++ b/changelogs/client_server/newsfragments/2270.feature @@ -0,0 +1 @@ +Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191). From 293012d12f9cf21cdc0312115f8436376d0a53db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 17 Dec 2025 12:12:44 +0100 Subject: [PATCH 3/4] Fix field name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/oauth_server_metadata.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/oauth_server_metadata.yaml b/data/api/client-server/oauth_server_metadata.yaml index fb976c56..a122ef30 100644 --- a/data/api/client-server/oauth_server_metadata.yaml +++ b/data/api/client-server/oauth_server_metadata.yaml @@ -148,7 +148,7 @@ paths: of the homeserver. This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management). - account_management_uri_supported: + account_management_actions_supported: x-addedInMatrixVersion: "1.17" type: array description: |- From 70d20057436b4e8d326e30cfaab928a852450bd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Fri, 19 Dec 2025 10:37:39 +0100 Subject: [PATCH 4/4] Bump Matrix version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 2 +- data/api/client-server/oauth_server_metadata.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 63308090..49482cbb 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2264,7 +2264,7 @@ The server SHOULD return one of the following responses: #### Account management {id="oauth-20-account-management"} -{{% added-in v="1.17" %}} +{{% added-in v="1.18" %}} All account management is done via the homeserver’s web UI as all endpoints that require User-Interactive Authentication are unsupported by this authentication diff --git a/data/api/client-server/oauth_server_metadata.yaml b/data/api/client-server/oauth_server_metadata.yaml index a122ef30..ab02e0b0 100644 --- a/data/api/client-server/oauth_server_metadata.yaml +++ b/data/api/client-server/oauth_server_metadata.yaml @@ -140,7 +140,7 @@ paths: type: string description: A prompt value that the server supports. account_management_uri: - x-addedInMatrixVersion: "1.17" + x-addedInMatrixVersion: "1.18" type: string format: uri description: |- @@ -149,7 +149,7 @@ paths: This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management). account_management_actions_supported: - x-addedInMatrixVersion: "1.17" + x-addedInMatrixVersion: "1.18" type: array description: |- List of actions that the account management URL supports.