+ +

Password auth provider callbacks

Password auth providers offer a way for server administrators to integrate +their Synapse installation with an external authentication system. The callbacks can be +registered by using the Module API's register_password_auth_provider_callbacks method.

Callbacks

`auth_checkers`

 auth_checkers: Dict[Tuple[str,Tuple], Callable]
+

A dict mapping from tuples of a login type identifier (such as m.login.password) and a +tuple of field names (such as ("password", "secret_thing")) to authentication checking +callbacks, which should be of the following form:

async def check_auth(
+    user: str,
+    login_type: str,
+    login_dict: "synapse.module_api.JsonDict",
+) -> Optional[
+    Tuple[
+        str, 
+        Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]]
+    ]
+]
+

The login type and field names should be provided by the user in the +request to the /login API. The Matrix specification +defines some types, however user defined ones are also allowed.

The callback is passed the user field provided by the client (which might not be in +@username:server form), the login type, and a dictionary of login secrets passed by +the client.

If the authentication is successful, the module must return the user's Matrix ID (e.g. +@alice:example.com) and optionally a callback to be called with the response to the +/login request. If the module doesn't wish to return a callback, it must return None +instead.

If the authentication is unsuccessful, the module must return None.

`check_3pid_auth`

async def check_3pid_auth(
+    medium: str, 
+    address: str,
+    password: str,
+) -> Optional[
+    Tuple[
+        str, 
+        Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]]
+    ]
+]
+

Called when a user attempts to register or log in with a third party identifier, +such as email. It is passed the medium (eg. email), an address (eg. jdoe@example.com) +and the user's password.

If the authentication is successful, the module must return the user's Matrix ID (e.g. +@alice:example.com) and optionally a callback to be called with the response to the /login request. +If the module doesn't wish to return a callback, it must return None instead.

If the authentication is unsuccessful, the module must return None.

`on_logged_out`

async def on_logged_out(
+    user_id: str,
+    device_id: Optional[str],
+    access_token: str
+) -> None
+

Called during a logout request for a user. It is passed the qualified user ID, the ID of the +deactivated device (if any: access tokens are occasionally created without an associated +device ID), and the (now deactivated) access token.

Example

The example module below implements authentication checkers for two different login types:

my.login.type +
- Expects a my_field field to be sent to /login
- Is checked by the method: self.check_my_login
+
m.login.password (defined in the spec) +
- Expects a password field to be sent to /login
- Is checked by the method: self.check_pass
+

from typing import Awaitable, Callable, Optional, Tuple
+
+import synapse
+from synapse import module_api
+
+
+class MyAuthProvider:
+    def __init__(self, config: dict, api: module_api):
+
+        self.api = api
+
+        self.credentials = {
+            "bob": "building",
+            "@scoop:matrix.org": "digging",
+        }
+
+        api.register_password_auth_provider_callbacks(
+            auth_checkers={
+                ("my.login_type", ("my_field",)): self.check_my_login,
+                ("m.login.password", ("password",)): self.check_pass,
+            },
+        )
+
+    async def check_my_login(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "my.login_type":
+            return None
+
+        if self.credentials.get(username) == login_dict.get("my_field"):
+            return self.api.get_qualified_user_id(username)
+
+    async def check_pass(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "m.login.password":
+            return None
+
+        if self.credentials.get(username) == login_dict.get("password"):
+            return self.api.get_qualified_user_id(username)
+

+ +