document new login identifier object (#1390)

api/client-server/definitions/user_identifier.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+title: User identifier
+description: |-
+  Identification information for a user
+type: object
+properties:
+  type:
+    type: string
+    description: The type of identification.  See `Identifier types`_ for supported values and additional property descriptions.
+required:
+  - type
+additionalProperties: true

api/client-server/login.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -85,7 +86,10 @@ paths:
             type: object
             example: {
                 "type": "m.login.password",
-                "user": "cheeky_monkey",
+                "identifier": {
+                  "type": "m.id.user",
+                  "user": "cheeky_monkey"
+                },
                 "password": "ilovebananas",
                 "initial_device_display_name": "Jungle Phone"
               }
@@ -94,15 +98,18 @@ paths:
                 type: string
                 enum: ["m.login.password", "m.login.token"]
                 description: The login type being used.
+              identifier:
+                description: Identification information for the user.
+                "$ref": "definitions/user_identifier.yaml"
               user:
                 type: string
-                description: The fully qualified user ID or just local part of the user ID, to log in.
+                description: The fully qualified user ID or just local part of the user ID, to log in.  Deprecated in favour of ``identifier``.
               medium:
                 type: string
-                description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'.
+                description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'.  Deprecated in favour of ``identifier``.
               address:
                 type: string
-                description: Third party identifier for the user.
+                description: Third party identifier for the user.  Deprecated in favour of ``identifier``.
               password:
                 type: string
                 description: |-

changelogs/client_server/newsfragments/1390.feature

@@ -0,0 +1 @@
+Add new user identifier object for logging in

specification/client_server_api.rst

@@ -461,7 +461,7 @@ Password-based
 :Type:
   ``m.login.password``
 :Description:
-  The client submits a username and secret password, both sent in plain-text.
+  The client submits an identifier and secret password, both sent in plain-text.
 
 To use this authentication type, clients should submit an auth dict as follows:
 
@@ -469,7 +469,26 @@ To use this authentication type, clients should submit an auth dict as follows:
 
   {
     "type": "m.login.password",
-    "user": "<user_id or user localpart>",
+    "identifier": {
+      ...
+    },
+    "password": "<password>",
+    "session": "<session ID>"
+  }
+
+where the ``identifier`` property is a user identifier object, as described in
+`Identifier types`_.
+
+For example, to authenticate using the user's Matrix ID, clients whould submit:
+
+.. code:: json
+
+  {
+    "type": "m.login.password",
+    "identifier": {
+      "type": "m.id.user",
+      "user": "<user_id or user localpart>"
+    },
     "password": "<password>",
     "session": "<session ID>"
   }
@@ -482,8 +501,11 @@ follows:
 
   {
     "type": "m.login.password",
-    "medium": "<The medium of the third party identifier. Must be 'email'>",
-    "address": "<The third party address of the user>",
+    "identifier": {
+      "type": "m.id.thirdparty",
+      "medium": "<The medium of the third party identifier.>",
+      "address": "<The third party address of the user>"
+    },
     "password": "<password>",
     "session": "<session ID>"
   }
@@ -714,6 +736,78 @@ handle unknown login types:
   }
 
 
+Identifier types
+++++++++++++++++
+
+Some authentication mechanisms use a user identifier object to identify a
+user.  The user identifier object has a ``type`` field to indicate the type of
+identifier being used, and depending on the type, has other fields giving the
+information required to identify the user as described below.
+
+This specification defines the following identifier types:
+ - ``m.id.user``
+ - ``m.id.thirdparty``
+ - ``m.id.phone``
+
+Matrix User ID
+<<<<<<<<<<<<<<
+:Type:
+  ``m.id.user``
+:Description:
+  The user is identified by their Matrix ID.
+
+A client can identify a user using their Matrix ID.  This can either be the
+fully qualified Matrix user ID, or just the localpart of the user ID.
+
+.. code:: json
+
+  "identifier": {
+    "type": "m.id.user",
+    "user": "<user_id or user localpart>"
+  }
+
+Third-party ID
+<<<<<<<<<<<<<<
+:Type:
+  ``m.id.thirdparty``
+:Description:
+  The user is identified by a third-party identifer in canonicalised form.
+
+A client can identify a user using a 3pid associated with the user's account on
+the homeserver, where the 3pid was previously associated using the
+|/account/3pid|_ API.  See the `3PID Types`_ Appendix for a list of Third-party
+ID media.
+
+.. code:: json
+
+  "identifier": {
+    "type": "m.id.thirdparty",
+    "medium": "<The medium of the third party identifier>",
+    "address": "<The canonicalised third party address of the user>"
+  }
+
+Phone number
+<<<<<<<<<<<<
+:Type:
+  ``m.id.phone``
+:Description:
+  The user is identified by a phone number.
+
+A client can identify a user using a phone number associated with the user's
+account, where the phone number was previously associated using the
+|/account/3pid|_ API.  The phone number can be passed in as entered by the
+user; the homeserver will be responsible for canonicalising it.  If the client
+wishes to canonicalise the phone number, then it can use the
+``m.id.thirdparty`` identifier type with a ``medium`` of ``msisdn`` instead.
+
+.. code:: json
+
+  "identifier": {
+    "type": "m.id.phone",
+    "country": "<The country that the phone number is from>",
+    "phone": "<The phone number>"
+  }
+
 Login
 ~~~~~
 
@@ -729,7 +823,10 @@ request as follows:
 
   {
     "type": "m.login.password",
-    "user": "<user_id or user localpart>",
+    "identifier": {
+      "type": "m.id.user",
+      "user": "<user_id or user localpart>"
+    },
     "password": "<password>"
   }
 
@@ -741,8 +838,10 @@ explicitly, as follows:
 
   {
     "type": "m.login.password",
-    "medium": "<The medium of the third party identifier. Must be 'email'>",
-    "address": "<The third party address of the user>",
+    "identifier": {
+      "medium": "<The medium of the third party identifier>",
+      "address": "<The canonicalised third party address of the user>"
+    },
     "password": "<password>"
   }
 
@@ -1477,3 +1576,4 @@ have to wait in milliseconds before they can try again.
 .. _/user/<user_id>/account_data/<type>: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type
 
 .. _`Unpadded Base64`:  ../appendices.html#unpadded-base64
+.. _`3PID Types`:  ../appendices.html#pid-types