wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Spec MSC2290: 3PID binding split

Browse source
This commit is contained in:
Travis Ralston 2019-10-08 15:31:06 +01:00
parent 6274a66ae5
commit f5f12a29e0
3 changed files with 144 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

149
api/client-server/administrative_contact.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -89,8 +90,19 @@ paths:
- User data
post:
summary: Adds contact information to the user's account.
description: Adds contact information to the user's account.
description: |-
Adds contact information to the user's account.
This endpoint is deprecated in favour of the more specific ``/3pid/add``
and ``/3pid/bind`` endpoints.
.. Note::
Previously this endpoint supported a ``bind`` parameter. This parameter
has been removed, making this endpoint behave as though it was ``false``.
This results in this endpoint being an equivalent to ``/3pid/bind`` rather
than dual-purpose.
operationId: post3PIDs
deprecated: true
security:
- accessToken: []
parameters:
@ -120,13 +132,6 @@ paths:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
bind:
type: boolean
description: |-
Whether the homeserver should also bind this third party
identifier to the account's Matrix ID with the passed identity
server. Default: ``false``.
x-example: true
required: ["three_pid_creds"]
example: {
"three_pid_creds": {
@ -134,8 +139,7 @@ paths:
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
},
"bind": false
}
}
responses:
200:
@ -173,6 +177,113 @@ paths:
"$ref": "definitions/errors/error.yaml"
tags:
- User data
"/account/3pid/add":
post:
summary: Adds contact information to the user's account.
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
Adds contact information to the user's account. Homeservers should use 3PIDs added
through this endpoint for password resets instead of relying on the identity server.
Homeservers should prevent the caller from adding a 3PID to their account if it has
already been added to another user's account on the homeserver.
operationId: add3PID
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
$ref: "definitions/auth_data.yaml"
client_secret:
type: string
description: The client secret used in the session with the homeserver.
sid:
type: string
description: The session identifier given by the homeserver.
required: ["client_secret", "sid"]
example: {
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
}
responses:
200:
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
"/account/3pid/bind":
post:
summary: Binds a 3PID to the user's account through an Identity Service.
description: |-
Binds a 3PID to the user's account through the specified identity server.
Homeservers should not prevent this request from succeeding if another user
has bound the 3PID. Homeservers should simply proxy any errors received by
the identity server to the caller.
Homeservers should track successful binds so they can be unbound later.
operationId: bind3PID
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
}
responses:
200:
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/account/3pid/delete":
post:
summary: Deletes a third party identifier from the user's account
@ -308,12 +419,9 @@ paths:
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding an email address to an
account. This API's parameters and response are identical to that of
the |/register/email/requestToken|_ endpoint. The homeserver has the
choice of validating the email address itself, or proxying the request
to the ``/validate/email/requestToken`` Identity Service API as
identified by ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
the |/register/email/requestToken|_ endpoint. The homeserver should validate
the email itself, either by sending a validation email itself or by using
a service it has control over.
operationId: requestTokenTo3PIDEmail
parameters:
- in: body
@ -361,12 +469,9 @@ paths:
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding a phone number to an
account. This API's parameters and response are identical to that of
the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
choice of validating the phone number itself, or proxying the request
to the ``/validate/msisdn/requestToken`` Identity Service API as
identified by ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate
the phone number itself, either by sending a validation message itself or by using
a service it has control over.
operationId: requestTokenTo3PIDMSISDN
parameters:
- in: body

30
api/client-server/registration.yaml
View file

@ -219,11 +219,8 @@ paths:
description: |-
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. The homeserver
has the choice of validating the email address itself, or proxying the
request to the ``/validate/email/requestToken`` Identity Service API. The
request should be proxied to the domain that is sent by the client in
the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts.
should validate the email itself, either by sending a validation email
itself or by using a service it has control over.
operationId: requestTokenToRegisterEmail
parameters:
- in: body
@ -272,11 +269,8 @@ paths:
description: |-
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. The homeserver
has the choice of validating the phone number itself, or proxying the
request to the ``/validate/msisdn/requestToken`` Identity Service API. The
request should be proxied to the domain that is sent by the client in
the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts.
should validate the phone number itself, either by sending a validation
message itself or by using a service it has control over.
operationId: requestTokenToRegisterMSISDN
parameters:
- in: body
@ -388,12 +382,8 @@ paths:
email to the given address prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the email address itself,
or proxying the request to the ``/validate/email/requestToken``
Identity Service API. The request should be proxied to the domain that
is sent by the client in the ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
The homeserver should validate the email itself, either by sending a
validation email itself or by using a service it has control over.
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
@ -451,12 +441,8 @@ paths:
to the given phone number prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the phone number itself, or
proxying the request to the ``/validate/msisdn/requestToken`` Identity
Service API. The request should be proxied to the domain that is sent
by the client in the ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
The homeserver should validate the phone number itself, either by sending a
validation message itself or by using a service it has control over.
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``

10
specification/client_server_api.rst
View file

@ -1138,7 +1138,15 @@ Adding Account Administrative Contact Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A homeserver may keep some contact information for administrative use.
This is independent of any information kept by any identity servers.
This is independent of any information kept by any identity servers, though
can be proxied (bound) to the identity server in many cases.
.. Note::
This section deals with two terms: "add" and "bind". Where "add" (or "remove")
is used, it is speaking about an identifier that was not bound to an identity
server. As a result, "bind" (or "unbind") references an identifier that is found
in an identity server. Note that an identifer can be added and bound at the same
time, depending on context.
{{administrative_contact_cs_http_api}}