Allow password_auth_providers to return a callback

... so that they have a way to record access tokens.

docs/password_auth_providers.rst

@@ -70,6 +70,11 @@ Password auth provider classes may optionally provide the following methods.
     the canonical ``@localpart:domain`` user id if authentication is successful,
     and ``None`` if not.
 
+    Alternatively, the ``Deferred`` can resolve to a ``(str, func)`` tuple, in
+    which case the second field is a callback which will be called with the
+    result from the ``/login`` call (including ``access_token``, ``device_id``,
+    etc.)
+
 ``someprovider.check_password``\(*user_id*, *password*)
 
     This method provides a simpler interface than ``get_supported_login_types``

synapse/handlers/auth.py

@@ -517,7 +517,8 @@ class AuthHandler(BaseHandler):
             login_submission (dict): the whole of the login submission
                 (including 'type' and other relevant fields)
         Returns:
-            Deferred[str]: canonical user id
+            Deferred[str, func]: canonical user id, and optional callback
+                to be called once the access token and device id are issued
         Raises:
             StoreError if there was a problem accessing the database
             SynapseError if there was a problem with the request
@@ -581,11 +582,13 @@ class AuthHandler(BaseHandler):
                     ),
                 )
 
-            returned_user_id = yield provider.check_auth(
+            result = yield provider.check_auth(
                 username, login_type, login_dict,
             )
-            if returned_user_id:
-                defer.returnValue(returned_user_id)
+            if result:
+                if isinstance(result, str):
+                    result = (result, None)
+                defer.returnValue(result)
 
         if login_type == LoginType.PASSWORD:
             known_login_type = True
@@ -595,7 +598,7 @@ class AuthHandler(BaseHandler):
             )
 
             if canonical_user_id:
-                defer.returnValue(canonical_user_id)
+                defer.returnValue((canonical_user_id, None))
 
         if not known_login_type:
             raise SynapseError(400, "Unknown login type %s" % login_type)

synapse/rest/client/v1/login.py

@@ -219,7 +219,7 @@ class LoginRestServlet(ClientV1RestServlet):
             raise SynapseError(400, "User identifier is missing 'user' key")
 
         auth_handler = self.auth_handler
-        canonical_user_id = yield auth_handler.validate_login(
+        canonical_user_id, callback = yield auth_handler.validate_login(
             identifier["user"],
             login_submission,
         )
@@ -238,6 +238,9 @@ class LoginRestServlet(ClientV1RestServlet):
             "device_id": device_id,
         }
 
+        if callback is not None:
+            yield callback(result)
+
         defer.returnValue((200, result))
 
     @defer.inlineCallbacks