1650eb5847
Provide an interface by which password auth providers can register db schema files to be run at startup
52 lines
1.9 KiB
ReStructuredText
52 lines
1.9 KiB
ReStructuredText
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.
|
|
|
|
Required methods
|
|
----------------
|
|
|
|
Password auth provider classes must provide the following methods:
|
|
|
|
*class* ``SomeProvider.parse_config``\(*config*)
|
|
|
|
This method is passed the ``config`` 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__``.
|
|
|
|
*class* ``SomeProvider``\(*config*, *account_handler*)
|
|
|
|
The constructor is passed the config object returned by ``parse_config``,
|
|
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.
|
|
|
|
*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.
|