4.9 KiB
Password auth provider modules
Password auth providers offer a way for server administrators to integrate their Synapse installation with an existing authentication system.
A password auth provider is a Python class which is dynamically loaded into Synapse, and provides a number of methods by which it can integrate with the authentication system.
This document serves as a reference for those looking to implement their own password auth providers. Additionally, here is a list of known password auth provider module implementations:
Required methods
Password auth provider classes must provide the following methods:
-
parse_config(config)
This method is passed theconfig
object for this module from the homeserver configuration file.It should perform any appropriate sanity checks on the provided configuration, and return an object which is then passed into
__init__
.This method should have the
@staticmethod
decoration. -
__init__(self, config, account_handler)
The constructor is passed the config object returned by
parse_config
, and asynapse.module_api.ModuleApi
object which allows the password provider to check if accounts exist and/or create new ones.
Optional methods
Password auth provider classes may optionally provide the following methods:
-
get_db_schema_files(self)
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. -
get_supported_login_types(self)
This method, if implemented, should return a
dict
mapping from a login type identifier (such asm.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 thelogin_dict
dictionary tocheck_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 fieldssecret1
andsecret2
, the provider should implement this method and return the following dict:{"com.example.custom_login": ("secret1", "secret2")}
-
check_auth(self, username, login_type, login_dict)
This method 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
field provided by the client, the login type, and a dictionary of login secrets passed by the client.The method should return an
Awaitable
object, which resolves to the canonical@localpart:domain
user ID if authentication is successful, andNone
if not.Alternatively, the
Awaitable
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 (includingaccess_token
,device_id
, etc.) -
check_3pid_auth(self, medium, address, password)
This method, if implemented, is called when a user attempts to register or log in with a third party identifier, such as email. It is passed the medium (ex. "email"), an address (ex. "jdoe@example.com") and the user's password.
The method should return an
Awaitable
object, which resolves to astr
containing the user's (canonical) User id if authentication was successful, andNone
if not.As with
check_auth
, theAwaitable
may alternatively resolve to a(user_id, callback)
tuple. -
check_password(self, user_id, password)
This method provides a simpler interface than
get_supported_login_types
andcheck_auth
for password auth providers that just want to provide a mechanism for validatingm.login.password
logins.If 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 an
Awaitable
object, which resolves toTrue
if authentication is successful, andFalse
if not. -
on_logged_out(self, user_id, device_id, access_token)
This method, if implemented, is called when a user logs out. 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.
It may return an
Awaitable
object; the logout request will wait for theAwaitable
to complete, but the result is ignored.