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). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 8f8092b5..15799230 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -645,7 +645,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 @@ -2271,6 +2271,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.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 +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..ab02e0b0 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.18" + 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_actions_supported: + x-addedInMatrixVersion: "1.18" + 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