diff --git a/docs/password_auth_providers.rst b/docs/password_auth_providers.rst
new file mode 100644
index 0000000000..3da1a67844
--- /dev/null
+++ b/docs/password_auth_providers.rst
@@ -0,0 +1,39 @@
+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.
diff --git a/synapse/config/password_auth_providers.py b/synapse/config/password_auth_providers.py
index 90824cab7f..e9828fac17 100644
--- a/synapse/config/password_auth_providers.py
+++ b/synapse/config/password_auth_providers.py
@@ -13,41 +13,40 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-from ._base import Config, ConfigError
+from ._base import Config
from synapse.util.module_loader import load_module
+LDAP_PROVIDER = 'ldap_auth_provider.LdapAuthProvider'
+
class PasswordAuthProviderConfig(Config):
def read_config(self, config):
self.password_providers = []
-
- provider_config = None
+ providers = []
# We want to be backwards compatible with the old `ldap_config`
# param.
ldap_config = config.get("ldap_config", {})
- self.ldap_enabled = ldap_config.get("enabled", False)
- if self.ldap_enabled:
- from ldap_auth_provider import LdapAuthProvider
- parsed_config = LdapAuthProvider.parse_config(ldap_config)
- self.password_providers.append((LdapAuthProvider, parsed_config))
+ if ldap_config.get("enabled", False):
+ providers.append[{
+ 'module': LDAP_PROVIDER,
+ 'config': ldap_config,
+ }]
- providers = config.get("password_providers", [])
+ providers.extend(config.get("password_providers", []))
for provider in providers:
+ mod_name = provider['module']
+
# This is for backwards compat when the ldap auth provider resided
# in this package.
- if provider['module'] == "synapse.util.ldap_auth_provider.LdapAuthProvider":
- from ldap_auth_provider import LdapAuthProvider
- provider_class = LdapAuthProvider
- try:
- provider_config = provider_class.parse_config(provider["config"])
- except Exception as e:
- raise ConfigError(
- "Failed to parse config for %r: %r" % (provider['module'], e)
- )
- else:
- (provider_class, provider_config) = load_module(provider)
+ if mod_name == "synapse.util.ldap_auth_provider.LdapAuthProvider":
+ mod_name = LDAP_PROVIDER
+
+ (provider_class, provider_config) = load_module({
+ "module": mod_name,
+ "config": provider['config'],
+ })
self.password_providers.append((provider_class, provider_config))
|
