Spec 3PID unbind API
As per [MSC1915](https://github.com/matrix-org/matrix-doc/pull/1915) Implementation proof: * https://github.com/matrix-org/synapse/pull/4982 * https://github.com/matrix-org/sydent/pull/160 The only alteration made which differs from the proposal is clarity on how to handle homeservers not knowing the `id_server`. All other differences are unintentional.
This commit is contained in:
Travis Ralston
parent
76829ad988
commit
0463084924
6 changed files with 142 additions and 4 deletions
|
|
@ -163,6 +163,14 @@ paths:
|
|||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind from. If not provided, the homeserver
|
||||
MUST use the ``id_server`` the identifier was added through. If the
|
||||
homeserver does not know the original ``id_server``, it MUST return
|
||||
a ``id_server_unbind_result`` of ``no-support``.
|
||||
example: "example.org"
|
||||
medium:
|
||||
type: string
|
||||
description: The medium of the third party identifier being removed.
|
||||
|
|
@ -180,7 +188,24 @@ paths:
|
|||
user.
|
||||
schema:
|
||||
type: object
|
||||
properties: {}
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
# XXX: I don't know why, but the order matters here so that "no-support"
|
||||
# doesn't become "no- support" by the renderer.
|
||||
- "no-support"
|
||||
- "success"
|
||||
description: |-
|
||||
An indicator as to whether or not the homeserver was able to unbind
|
||||
the 3PID from the identity server. ``success`` indicates that the
|
||||
indentity server has unbound the identifier whereas ``no-support``
|
||||
indicates that the identity server refuses to support the request
|
||||
or the homeserver was not able to determine an identity server to
|
||||
unbind from.
|
||||
example: "success"
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
tags:
|
||||
- User data
|
||||
"/account/3pid/email/requestToken":
|
||||
|
|
|
|||
|
|
@ -524,13 +524,39 @@ paths:
|
|||
description: |-
|
||||
Additional authentication information for the user-interactive authentication API.
|
||||
"$ref": "definitions/auth_data.yaml"
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind all of the user's 3PIDs from.
|
||||
If not provided, the homeserver MUST use the ``id_server``
|
||||
that was originally use to bind each identifier. If the
|
||||
homeserver does not know which ``id_server`` that was,
|
||||
it must return an ``id_server_unbind_result`` of
|
||||
``no-support``.
|
||||
example: "example.org"
|
||||
responses:
|
||||
200:
|
||||
description: The account has been deactivated.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
- "success"
|
||||
- "no-support"
|
||||
description: |-
|
||||
An indicator as to whether or not the homeserver was able to unbind
|
||||
the user's 3PIDs from the identity server(s). ``success`` indicates
|
||||
that all identifiers have been unbound from the identity server while
|
||||
``no-support`` indicates that one or more identifiers failed to unbind
|
||||
due to the identity server refusing the request or the homeserver
|
||||
being unable to determine an identity server to unbind from. This
|
||||
must be ``success`` if the homeserver has no identifiers to unbind
|
||||
for the user.
|
||||
example: "success"
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
401:
|
||||
description: |-
|
||||
The homeserver requires additional authentication information.
|
||||
|
|
|
|||
|
|
@ -201,3 +201,86 @@ paths:
|
|||
}
|
||||
schema:
|
||||
$ref: "../client-server/definitions/errors/error.yaml"
|
||||
"/3pid/unbind":
|
||||
post:
|
||||
summary: Remove an association between a session and a Matrix user ID.
|
||||
description: |-
|
||||
Remove an association between a session and a Matrix user ID.
|
||||
|
||||
Future calls to ``/lookup`` for any of the session's 3pids will not
|
||||
return the removed association.
|
||||
|
||||
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_secret`` parameters,
|
||||
as per ``/3pid/bind``, which proves ownership of the 3PID.
|
||||
|
||||
If this endpoint returns a JSON Matrix error, that error should be passed
|
||||
through to the client requesting an unbind through a homeserver, if the
|
||||
homeserver is acting on behalf of a client.
|
||||
operationId: unbind
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"sid": "1234",
|
||||
"client_secret": "monkeys_are_GREAT",
|
||||
"mxid": "@ears:example.org",
|
||||
"threepid": {
|
||||
"medium": "email",
|
||||
"address": "monkeys_have_ears@example.org"
|
||||
}
|
||||
}
|
||||
properties:
|
||||
sid:
|
||||
type: string
|
||||
description: The Session ID generated by the ``requestToken`` call.
|
||||
client_secret:
|
||||
type: string
|
||||
description: The client secret passed to the ``requestToken`` call.
|
||||
mxid:
|
||||
type: string
|
||||
description: The Matrix user ID to remove from the 3pids.
|
||||
threepid:
|
||||
type: object
|
||||
title: 3PID
|
||||
description: |-
|
||||
The 3PID to remove. Must match the 3PID used to generate the session
|
||||
if using ``sid`` and ``client_secret`` to authenticate this request.
|
||||
properties:
|
||||
medium:
|
||||
type: string
|
||||
description: |-
|
||||
A medium from the `3PID Types`_ Appendix, matching the medium
|
||||
of the identifier to unbind.
|
||||
address:
|
||||
type: string
|
||||
description: The 3PID address to remove.
|
||||
required: ['medium', 'address']
|
||||
required: ["threepid", "mxid"]
|
||||
responses:
|
||||
200:
|
||||
description: The association was successfully removed.
|
||||
examples:
|
||||
application/json: {}
|
||||
schema:
|
||||
type: object
|
||||
400:
|
||||
description: |-
|
||||
If the response body is not a JSON Matrix error, the identity server
|
||||
does not support unbinds. If a JSON Matrix error is in the response
|
||||
body, the requesting party should respect the error.
|
||||
404:
|
||||
description: |-
|
||||
If the response body is not a JSON Matrix error, the identity server
|
||||
does not support unbinds. If a JSON Matrix error is in the response
|
||||
body, the requesting party should respect the error.
|
||||
501:
|
||||
description: |-
|
||||
If the response body is not a JSON Matrix error, the identity server
|
||||
does not support unbinds. If a JSON Matrix error is in the response
|
||||
body, the requesting party should respect the error.
|
||||
|
|
|
|||
1
changelogs/client_server/newsfragments/2046.feature
Normal file
1
changelogs/client_server/newsfragments/2046.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server.
|
||||
1
changelogs/identity_service/newsfragments/2046.new
Normal file
1
changelogs/identity_service/newsfragments/2046.new
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add ``/3pid/unbind`` for removing 3PIDs.
|
||||
|
|
@ -27,7 +27,9 @@ 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 then that should be returned to the client.
|
||||
server returns an error then that should be returned to the client. If the homeserver
|
||||
is unable to determine an `id_server` to use, it should return `no-support` for
|
||||
the `id_server_unbind_result`.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue