Let password auth providers handle arbitrary login types

Provide a hook where password auth providers can say they know about other
login types, and get passed the relevant parameters

docs/password_auth_providers.rst

@@ -30,22 +30,55 @@ Password auth provider classes must provide the following methods:
     and a ``synapse.handlers.auth._AccountHandler`` object which allows the
     password provider to check if accounts exist and/or create new ones.
 
-``someprovider.check_password``\(*user_id*, *password*)
-
-    This is the method that actually does the work. It is passed a qualified
-    ``@localpart:domain`` user id, and the password provided by the user.
-
-    The method should return a Twisted ``Deferred`` object, which resolves to
-    ``True`` if authentication is successful, and ``False`` if not.
-
 Optional methods
 ----------------
 
-Password provider classes may optionally provide the following methods.
+Password auth provider classes may optionally provide the following methods.
 
-*class* ``SomeProvider.get_db_schema_files()``
+*class* ``SomeProvider.get_db_schema_files``\()
 
     This method, if implemented, should return an Iterable of ``(name,
     stream)`` pairs of database schema files. Each file is applied in turn at
     initialisation, and a record is then made in the database so that it is
     not re-applied on the next start.
+
+``someprovider.get_supported_login_types``\()
+
+    This method, if implemented, should return a ``dict`` mapping from a login
+    type identifier (such as ``m.login.password``) to an iterable giving the
+    fields which must be provided by the user in the submission to the
+    ``/login`` api. These fields are passed in the ``login_dict`` dictionary
+    to ``check_auth``.
+
+    For example, if a password auth provider wants to implement a custom login
+    type of ``com.example.custom_login``, where the client is expected to pass
+    the fields ``secret1`` and ``secret2``, the provider should implement this
+    method and return the following dict::
+
+      {"com.example.custom_login": ("secret1", "secret2")}
+
+``someprovider.check_auth``\(*username*, *login_type*, *login_dict*)
+
+    This method is the one that does the real work. If implemented, it will be
+    called for each login attempt where the login type matches one of the keys
+    returned by ``get_supported_login_types``.
+
+    It is passed the (possibly UNqualified) ``user`` provided by the client,
+    the login type, and a dictionary of login secrets passed by the client.
+
+    The method should return a Twisted ``Deferred`` object, which resolves to
+    the canonical ``@localpart:domain`` user id if authentication is successful,
+    and ``None`` if not.
+
+``someprovider.check_password``\(*user_id*, *password*)
+
+    This method provides a simpler interface than ``get_supported_login_types``
+    and ``check_auth`` for password auth providers that just want to provide a
+    mechanism for validating ``m.login.password`` logins.
+
+    Iif implemented, it will be called to check logins with an
+    ``m.login.password`` login type. It is passed a qualified
+    ``@localpart:domain`` user id, and the password provided by the user.
+
+    The method should return a Twisted ``Deferred`` object, which resolves to
+    ``True`` if authentication is successful, and ``False`` if not.