From f92925ed456d51c71dd064ee30b93bad40f1fe44 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Wed, 6 Mar 2019 11:32:28 +0000 Subject: [PATCH 1/6] Add a 3PID unbind API --- .../1915-unbind-identity-server-param.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 proposals/1915-unbind-identity-server-param.md diff --git a/proposals/1915-unbind-identity-server-param.md b/proposals/1915-unbind-identity-server-param.md new file mode 100644 index 00000000..f018d261 --- /dev/null +++ b/proposals/1915-unbind-identity-server-param.md @@ -0,0 +1,97 @@ +# MSC 1915 - Add unbind 3PID APIs + +Note that this is a simplified version of MSC1194. + + +## Motivation + +Currently we do not have a reasonable route for a user to unbind/remove a 3PID +from their account, particularly when deactivating their account. Users have an +expectation to be able to do this, and thus we should have an API to provide it. + +This is meant as a simple extension to the current APIs, and so this explicitly +does not try and solve any existing usability concerns. + + +## New APIs + +### Client-Server API + +Add `POST /_matrix/client/r0/account/3pid/delete` API, which expects a JSON body +with `medium`, `address` and `id_server` fields (as per existing APIs). + +The `id_server` parameter is optional and if missing the server will attempt to +unbind from a suitable identity server (e.g. its default identity server or the +server used when originally binding the 3pid). + +The 200 response is a JSON object with an `id_server_unbind_result` field whose +value is either `success` or `no-support`, where the latter indicates that the +identity server (IS) does not support unbinding 3PIDs directly. + +Example: + +``` +POST /_matrix/client/r0/account/3pid/delete HTTP/1.1 + +{ + "medium": "email", + "address": "foobar@example.com", + "id_server": "https://matrix.org +} + +HTTP/1.1 200 OK +{ + "id_server_unbind_result": "success" +} +``` + + +### Identity Server API + +Add `POST /_matrix/identity/api/v1/unbind` with `mxid` and `threepid` fields. +The `mxid` is the user's `user_id` and `threepid` is a dict with the usual +`medium` and `address` fields. + +If the server returns a 400, 404 or 501 HTTP error code then the homeserver +should assume that the identity server doesn't support the `/unbind` API, unless +it returns a specific matrix error response (i.e. the body is a JSON object with +`error` and `errcode` fields). + +The identity server should accept any request to unbind a 3PID for a `user_id` from +the homeserver controlling that user ID. + +Example: + +``` +POST /_matrix/identity/api/v1/unbind HTTP/1.1 + +{ + "mxid": "@foobar:example.com", + "threepid": { + "medium": "email", + "address": "foobar@example.com" + } +} + +HTTP/1.1 200 OK + +{} +``` + +# Trade-offs + +A homeserver can unbind any 3PID associated with one of its users, and +specifically does not require a re-validation of control of the 3PID. This means +that users have to trust that their homeserver will not arbitrarily remove valid +3PIDs, however users must already trust their homeserver to a large extent. The +flip side is that this provides a mechanism for homeservers and users to remove +3PIDs directed at their user IDs that they no longer (or never did) have control +over. + +Removing a 3PID does not require user interactive auth (UIA), which opens a +potential attack whereby a logged in device can remove all associated 3PIDs and +then log out all devices. If the user has forgotten their password they would no +longer be able to reset their password via a 3PID (e.g. email), resulting in +losing access to their account. However, given that clients and servers have +implemented these APIs in the wild this is considered a sufficient edge case +that adding UIA is unlikely to be worthwhile. From ee6513d608cf8004f67a9fbae1b69d02477719dd Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 7 Mar 2019 16:52:58 +0000 Subject: [PATCH 2/6] Add alternative sid/client_secret authentication --- proposals/1915-unbind-identity-server-param.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/1915-unbind-identity-server-param.md b/proposals/1915-unbind-identity-server-param.md index f018d261..1dc2d833 100644 --- a/proposals/1915-unbind-identity-server-param.md +++ b/proposals/1915-unbind-identity-server-param.md @@ -57,8 +57,11 @@ should assume that the identity server doesn't support the `/unbind` API, unless it returns a specific matrix error response (i.e. the body is a JSON object with `error` and `errcode` fields). -The identity server should accept any request to unbind a 3PID for a `user_id` from -the homeserver controlling that user ID. +The identity server should authenticate the request in one of two ways: + +1. The request is signed by the homeserver which controls the `user_id`. +2. The request includes the `sid` and `client_server` params (as per `/bind`), + which proves ownership of the given 3PID. Example: From 77110b46df7000d0ea78f2cdd4778c2122b7de73 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 8 Mar 2019 12:14:08 +0000 Subject: [PATCH 3/6] Update proposals/1915-unbind-identity-server-param.md Co-Authored-By: erikjohnston --- proposals/1915-unbind-identity-server-param.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1915-unbind-identity-server-param.md b/proposals/1915-unbind-identity-server-param.md index 1dc2d833..9ffb99b3 100644 --- a/proposals/1915-unbind-identity-server-param.md +++ b/proposals/1915-unbind-identity-server-param.md @@ -60,7 +60,7 @@ it returns a specific matrix error response (i.e. the body is a JSON object with The identity server should authenticate the request in one of two ways: 1. The request is signed by the homeserver which controls the `user_id`. -2. The request includes the `sid` and `client_server` params (as per `/bind`), +2. The request includes the `sid` and `client_secret` params (as per `/bind`), which proves ownership of the given 3PID. Example: From 60f1cf79de80221029234949483b0643f246df43 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 12 Mar 2019 14:20:37 +0000 Subject: [PATCH 4/6] Update wording and add deactivate account API --- .../1915-unbind-identity-server-param.md | 22 ++++++++++++------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/proposals/1915-unbind-identity-server-param.md b/proposals/1915-unbind-identity-server-param.md index 9ffb99b3..8dbfe2e6 100644 --- a/proposals/1915-unbind-identity-server-param.md +++ b/proposals/1915-unbind-identity-server-param.md @@ -13,16 +13,16 @@ This is meant as a simple extension to the current APIs, and so this explicitly does not try and solve any existing usability concerns. -## New APIs +## API Changes -### Client-Server API +### Client-Server 3PID Delete API -Add `POST /_matrix/client/r0/account/3pid/delete` API, which expects a JSON body -with `medium`, `address` and `id_server` fields (as per existing APIs). +Add an `id_server` param to `POST /_matrix/client/r0/account/3pid/delete` API, +which matches the 3PID creation APIs. -The `id_server` parameter is optional and if missing the server will attempt to -unbind from a suitable identity server (e.g. its default identity server or the -server used when originally binding the 3pid). +The new `id_server` parameter is optional and if missing the server will attempt +to unbind from a suitable identity server (e.g. its default identity server or +the server used when originally binding the 3pid). The 200 response is a JSON object with an `id_server_unbind_result` field whose value is either `success` or `no-support`, where the latter indicates that the @@ -45,8 +45,14 @@ HTTP/1.1 200 OK } ``` +### Client-Server Deactivate account API -### Identity Server API +Add an `id_server` param to `POST /_matrix/client/r0/account/deactivate` API, +with the same semantics as above. This is used to unbind any bound threepids +from the given identity server. + + +### Identity Server 3PID Unbind API Add `POST /_matrix/identity/api/v1/unbind` with `mxid` and `threepid` fields. The `mxid` is the user's `user_id` and `threepid` is a dict with the usual From bd4fab7a15e9086473714fd9d54656b396212467 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 18 Mar 2019 09:28:46 +0000 Subject: [PATCH 5/6] Be more explicit identity server selection and errors --- proposals/1915-unbind-identity-server-param.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/1915-unbind-identity-server-param.md b/proposals/1915-unbind-identity-server-param.md index 8dbfe2e6..438dfa44 100644 --- a/proposals/1915-unbind-identity-server-param.md +++ b/proposals/1915-unbind-identity-server-param.md @@ -21,12 +21,13 @@ Add an `id_server` param to `POST /_matrix/client/r0/account/3pid/delete` API, which matches the 3PID creation APIs. The new `id_server` parameter is optional and if missing the server will attempt -to unbind from a suitable identity server (e.g. its default identity server or -the server used when originally binding the 3pid). +to unbind from the identity server used when originally binding the 3pid (if +known by the homeserver). The 200 response is a JSON object with an `id_server_unbind_result` field whose value is either `success` or `no-support`, where the latter indicates that the -identity server (IS) does not support unbinding 3PIDs directly. +identity server (IS) does not support unbinding 3PIDs directly. If the identity +server returns an error than that should be returned to the client. Example: From 410a5dbbff6dc37132ee22ce2e0bf4df3aaa51a6 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 18 Mar 2019 09:36:01 +0000 Subject: [PATCH 6/6] Update proposals/1915-unbind-identity-server-param.md Co-Authored-By: erikjohnston --- proposals/1915-unbind-identity-server-param.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1915-unbind-identity-server-param.md b/proposals/1915-unbind-identity-server-param.md index 438dfa44..053552f6 100644 --- a/proposals/1915-unbind-identity-server-param.md +++ b/proposals/1915-unbind-identity-server-param.md @@ -27,7 +27,7 @@ known by the homeserver). The 200 response is a JSON object with an `id_server_unbind_result` field whose value is either `success` or `no-support`, where the latter indicates that the identity server (IS) does not support unbinding 3PIDs directly. If the identity -server returns an error than that should be returned to the client. +server returns an error then that should be returned to the client. Example: