summary refs log tree commit diff
path: root/docs/password_auth_providers.rst
diff options
context:
space:
mode:
authorRichard van der Hoff <richard@matrix.org>2017-10-30 14:41:35 +0000
committerRichard van der Hoff <richard@matrix.org>2017-10-31 10:47:52 +0000
commitebda45de4c04d4a3d569e4f2969b798699bd5b16 (patch)
treea61cd8b00a7fb8501a517e10584f6c40d8535792 /docs/password_auth_providers.rst
parentMerge pull request #2605 from matrix-org/luke/fix-group-creation-error-wording (diff)
downloadsynapse-ebda45de4c04d4a3d569e4f2969b798699bd5b16.tar.xz
Start some documentation on password providers
Document the existing interface, before I start adding new stuff.
Diffstat (limited to 'docs/password_auth_providers.rst')
-rw-r--r--docs/password_auth_providers.rst39
1 files changed, 39 insertions, 0 deletions
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.