matrix-spec-proposals/proposals/4191-account-deeplink.md

MSC4191: Account management for OAuth 2.0 API

This proposal builds on the OAuth 2.0 API that was added in v1.15 of the spec.

The current spec makes reference to the "homeserver's web UI" in several places without defining how that is discovered nor what you can use it for.

This proposal defines how that discovery happens and 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 independently of the client.

In doing so, this proposal also resolves the issue that there is currently no specced way to delete devices using the OAuth 2.0 API (because the API endpoints to delete devices are not supported when using the OAuth 2.0 API).

Proposal

Additional authentication server metadata

This proposal introduces two new optional fields in the authentication server metadata discovery:

• account_management_uri: the URL where the user is able to access the account management capabilities of the homeserver. This is what is currently referred to as the "homeserver's web UI"
• account_management_actions_supported: a JSON array of actions that the account management URL supports

Note that the intent of this proposal is for these values to potentially end up in a OpenID Connect specification, or at least formally registered in the IANA Registry for Server Metadata. This is why the metadata fields are not prefixed with org.matrix., but the actions themselves are.

Account management URL parameters

The account management URL (as provided above) may accept the following additional query parameters:

• action - Can be used to indicate the action that the user wishes to take, as defined below.
• device_id - This can be used to identify a particular session for org.matrix.device_view and org.matrix.device_delete. This is the Matrix device ID.

For example, if a user wishes to sign out a session for the device ABCDEFGH where the advertised account_management_uri was https://account.example.com/myaccount the client could open a link to https://account.example.com/myaccount?action=org.matrix.device_delete&device_id=ABCDEFGH.

Not all actions need to be supported by the account management URL, and the client should only use the actions advertised in the account_management_actions_supported array from above.

If the org.matrix.device_view or org.matrix.device_delete are advertised as supported by the server then the server should support the device_id parameter.

Possible actions

The following account management actions are defined by this MSC:

• 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.
• org.matrix.device_delete - The user wishes to delete/logout a specific device.
• 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. See MSC4312 for additional details on this.

Subsequent MSCs may extend this list.

These actions are prefixed with the full org.matrix. (rather than the more compact m.) because if the IANA registration/OIDC adoption goes ahead then these values would be more clearly namespaced to Matrix.

Alternatives

Add UIA support to OAuth 2.0 API so that the existing delete devices endpoints can be used

n.b. This isn't a complete alternative to this full MSC and instead just considers an alternative way for device deletion to happen.

The following endpoints are currently not supported when using the OAuth 2.0 API:

• POST /_matrix/client/v3/delete_devices
• DELETE /_matrix/client/v3/devices/{deviceId}

The reason given in the spec is:

WARNING: Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained via the OAuth 2.0 API.

As an alternative to the proposed org.matrix.device_delete action the above device deletion endpoints could be instead be used if the User-interactive API was compatible with the OAuth 2.0 API.

Advertise the account management capabilities in the well-known discovery

An earlier iteration of MSC2965 (which formed part of the current OAuth 2.0 API) proposed using a well-known style discovery mechanism for the account management URL.

For consistency it is proposed that the server metadata discovery API is used instead.

Advertise the account management capabilities in a C-S API endpoint

The metadata could be advertised in a metadata endpoint separate to the server metadata discovery mechanism.

Security considerations

For the org.matrix.device_delete action the security considerations that are already stated for device management apply.

Consequently for the destructive org.matrix.device_delete and org.matrix.account_deactivate actions the server SHOULD require re-authentication (or authentication through an additional factor) before allowing the user to complete the action.

Because the format of these links are public and the device IDs are visible to other Matrix users it is trivial for an attacker to craft a "malicious" link that targets a destructive action. To mitigate this risk, for the destructive actions (org.matrix.device_delete and org.matrix.account_deactivate) the server MUST inform the user of what the action is prior to it being executed (in addition to any re-authentication as above).

Unstable prefixes

Whilst in development the fields in the server metadata discovery should be prefixed as follows:

• org.matrix.msc4191.account_management_uri instead of account_management_uri
• org.matrix.msc4191.account_management_actions_supported instead of account_management_actions_supported

For future reference, the following unstable action values are known to have been used in prototype implementations:

• org.matrix.profile: profile
• org.matrix.devices_list: sessions_list, org.matrix.sessions_list
• org.matrix.device_view: session_view, org.matrix.session_view
• org.matrix.device_delete - session_end, org.matrix.session_end