|
| 1 | +# MSC4191: Account management for OAuth 2.0 API |
| 2 | + |
| 3 | +This proposal builds on the [OAuth 2.0 API](https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api) that was |
| 4 | +added in v1.15 of the spec. |
| 5 | + |
| 6 | +The current spec makes reference to the "homeserver's web UI" in several places without defining how that is discovered |
| 7 | +nor what you can use it for. |
| 8 | + |
| 9 | +This proposal defines how that discovery happens and a way to deep-link to the account management capabilities of the |
| 10 | +homeserver to allow the user to complete the account management operations in a browser independently of the client. |
| 11 | + |
| 12 | +In doing so, this proposal also resolves the issue that there is currently no specced way to delete devices using the |
| 13 | +OAuth 2.0 API (because the API endpoints to delete devices are not supported when using the OAuth 2.0 API). |
| 14 | + |
| 15 | +## Proposal |
| 16 | + |
| 17 | +### Additional authentication server metadata |
| 18 | + |
| 19 | +This proposal introduces two new optional fields in the authentication |
| 20 | +[server metadata discovery](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery): |
| 21 | + |
| 22 | +- `account_management_uri`: the URL where the user is able to access the account management capabilities of the |
| 23 | + homeserver. This is what is currently referred to as the "homeserver's web UI" |
| 24 | +- `account_management_actions_supported`: a JSON array of actions that the account management URL supports |
| 25 | + |
| 26 | +Note that the intent of this proposal is for these values to potentially end up in a OpenID Connect specification, or at |
| 27 | +least formally registered in the |
| 28 | +[IANA Registry for Server Metadata](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata). |
| 29 | +This is why the metadata fields are not prefixed with `org.matrix.`, but the actions themselves are. |
| 30 | + |
| 31 | +### Account management URL parameters |
| 32 | + |
| 33 | +The account management URL (as provided above) may accept the following additional query parameters: |
| 34 | + |
| 35 | +- `action` - Can be used to indicate the action that the user wishes to take, as defined below. |
| 36 | +- `device_id` - This can be used to identify a particular session for `org.matrix.device_view` and |
| 37 | + `org.matrix.device_delete`. This is the Matrix device ID. |
| 38 | + |
| 39 | +For example, if a user wishes to sign out a session for the device `ABCDEFGH` where the advertised |
| 40 | +`account_management_uri` was `https://account.example.com/myaccount` the client could open a link to |
| 41 | +`https://account.example.com/myaccount?action=org.matrix.device_delete&device_id=ABCDEFGH`. |
| 42 | + |
| 43 | +Not all actions need to be supported by the account management URL, and the client should only use the actions |
| 44 | +advertised in the `account_management_actions_supported` array from above. |
| 45 | + |
| 46 | +If the `org.matrix.device_view` or `org.matrix.device_delete` are advertised as supported by the |
| 47 | +server then the server should support the `device_id` parameter. |
| 48 | + |
| 49 | +### Possible actions |
| 50 | + |
| 51 | +The following account management actions are defined by this MSC: |
| 52 | + |
| 53 | +- `org.matrix.profile` - The user wishes to view/edit their profile (name, avatar, contact details). |
| 54 | +- `org.matrix.devices_list` - The user wishes to view a list of their devices. |
| 55 | +- `org.matrix.device_view` - The user wishes to view the details of a specific device. |
| 56 | +- `org.matrix.device_delete` - The user wishes to delete/logout a specific device. |
| 57 | +- `org.matrix.account_deactivate` - The user wishes to deactivate their account. |
| 58 | +- `org.matrix.cross_signing_reset` - The user wishes to reset their cross-signing identity. See |
| 59 | + [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/blob/ea0aef0aa32ee979b4db14bb869938a597777346/proposals/4312-x-signing-reset-with-nextgen-auth.md?plain=1#L55-L58) |
| 60 | + for additional details on this. |
| 61 | + |
| 62 | +Subsequent MSCs may extend this list. |
| 63 | + |
| 64 | +These actions are prefixed with the full `org.matrix.` (rather than the more compact `m.`) because |
| 65 | +if the IANA registration/OIDC adoption goes ahead then these values would be more clearly namespaced |
| 66 | +to Matrix. |
| 67 | + |
| 68 | +## Alternatives |
| 69 | + |
| 70 | +### Add UIA support to OAuth 2.0 API so that the existing delete devices endpoints can be used |
| 71 | + |
| 72 | +n.b. This isn't a complete alternative to this full MSC and instead just considers an alternative way for device |
| 73 | +deletion to happen. |
| 74 | + |
| 75 | +The following endpoints are currently not supported when using the OAuth 2.0 API: |
| 76 | + |
| 77 | +- [`POST /_matrix/client/v3/delete_devices`](https://spec.matrix.org/v1.16/client-server-api/#post_matrixclientv3delete_devices) |
| 78 | +- [`DELETE /_matrix/client/v3/devices/{deviceId}`](https://spec.matrix.org/v1.16/client-server-api/#delete_matrixclientv3devicesdeviceid) |
| 79 | + |
| 80 | +The reason given in the spec is: |
| 81 | + |
| 82 | +> **WARNING**: Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token |
| 83 | +> was obtained via the OAuth 2.0 API. |
| 84 | +
|
| 85 | +As an alternative to the proposed `org.matrix.device_delete` action the above device deletion endpoints could be instead |
| 86 | +be used *if* the [User-interactive API](https://spec.matrix.org/v1.15/client-server-api/#user-interactive-api-in-the-rest-api) |
| 87 | +was compatible with the OAuth 2.0 API. |
| 88 | + |
| 89 | +### Advertise the account management capabilities in the well-known discovery |
| 90 | + |
| 91 | +An earlier iteration of [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965) (which formed part of |
| 92 | +the current OAuth 2.0 API) proposed using a |
| 93 | +[well-known style discovery mechanism](https://github.com/sandhose/matrix-spec-proposals/blob/msc/sandhose/oidc-discovery/proposals/2965-auth-metadata.md#discovery-via-existing-well-known-mechanism) |
| 94 | +for the account management URL. |
| 95 | + |
| 96 | +For consistency it is proposed that the |
| 97 | +[server metadata discovery](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery) API is used |
| 98 | +instead. |
| 99 | + |
| 100 | +### Advertise the account management capabilities in a C-S API endpoint |
| 101 | + |
| 102 | +The metadata could be advertised in a metadata endpoint separate to the |
| 103 | +[server metadata discovery](https://spec.matrix.org/v1.15/client-server-api/#server-metadata-discovery) mechanism. |
| 104 | + |
| 105 | +## Security considerations |
| 106 | + |
| 107 | +For the `org.matrix.device_delete` action the |
| 108 | +[security considerations](https://spec.matrix.org/v1.15/client-server-api/#security-considerations-6) that are already |
| 109 | +stated for device management apply. |
| 110 | + |
| 111 | +Consequently for the destructive `org.matrix.device_delete` and `org.matrix.account_deactivate` actions the server SHOULD |
| 112 | +require re-authentication (or authentication through an additional factor) before allowing the user to complete the |
| 113 | +action. |
| 114 | + |
| 115 | +Because the format of these links are public and the device IDs are visible to other Matrix users it is trivial for an |
| 116 | +attacker to craft a "malicious" link that targets a destructive action. To mitigate this risk, for the destructive |
| 117 | +actions (`org.matrix.device_delete` and `org.matrix.account_deactivate`) the server MUST inform the user of what the |
| 118 | +action is prior to it being executed (in addition to any re-authentication as above). |
| 119 | + |
| 120 | +## Unstable prefixes |
| 121 | + |
| 122 | +Whilst in development the fields in the server metadata discovery should be prefixed as follows: |
| 123 | + |
| 124 | +- `org.matrix.msc4191.account_management_uri` instead of `account_management_uri` |
| 125 | +- `org.matrix.msc4191.account_management_actions_supported` instead of `account_management_actions_supported` |
| 126 | + |
| 127 | +For future reference, the following unstable action values are known to have been used in prototype |
| 128 | +implementations: |
| 129 | + |
| 130 | +- `org.matrix.profile`: `profile` |
| 131 | +- `org.matrix.devices_list`: `sessions_list`, `org.matrix.sessions_list` |
| 132 | +- `org.matrix.device_view`: `session_view`, `org.matrix.session_view` |
| 133 | +- `org.matrix.device_delete` - `session_end`, `org.matrix.session_end` |
0 commit comments