Merge pull request #2328 from matrix-org/travis/spec/2290-new-bind

Spec MSC2290: 3PID binding split

api/client-server/administrative_contact.yaml

@@ -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,111 @@ 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.
+              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 +417,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
+        the |/register/email/requestToken|_ endpoint. The homeserver should validate
-        choice of validating the email address itself, or proxying the request
+        the email itself, either by sending a validation email itself or by using
-        to the ``/validate/email/requestToken`` Identity Service API as
+        a service it has control over.
-        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.
       operationId: requestTokenTo3PIDEmail
       parameters:
         - in: body
@@ -361,12 +467,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
+        the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate
-        choice of validating the phone number itself, or proxying the request
+        the phone number itself, either by sending a validation message itself or by using
-        to the ``/validate/msisdn/requestToken`` Identity Service API as
+        a service it has control over.
-        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.
       operationId: requestTokenTo3PIDMSISDN
       parameters:
         - in: body

api/client-server/registration.yaml

@@ -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
+        should validate the email itself, either by sending a validation email
-        request to the ``/validate/email/requestToken`` Identity Service API. The
+        itself or by using a service it has control over.
-        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.
       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
+        should validate the phone number itself, either by sending a validation
-        request to the ``/validate/msisdn/requestToken`` Identity Service API. The
+        message itself or by using a service it has control over.
-        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.
       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,
+        The homeserver should validate the email itself, either by sending a
-        or proxying the request to the ``/validate/email/requestToken``
+        validation email itself or by using a service it has control over.
-        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.
 
 
         .. |/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
+        The homeserver should validate the phone number itself, either by sending a
-        proxying the request to the ``/validate/msisdn/requestToken`` Identity
+        validation message itself or by using a service it has control over.
-        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.
 
         .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
 

specification/client_server_api.rst

@@ -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}}