|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129 |
- <h2 style="color:red">
- This page of the Synapse documentation is now deprecated. For up to date
- documentation on setting up or writing a password auth provider module, please see
- <a href="modules/index.md">this page</a>.
- </h2>
-
- # 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:
-
- * [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3/)
- * [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth)
- * [matrix-synapse-rest-password-provider](https://github.com/ma1uta/matrix-synapse-rest-password-provider)
-
- ## Required methods
-
- Password auth provider classes must provide the following methods:
-
- * `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__`.
-
- This method should have the `@staticmethod` decoration.
-
- * `__init__(self, config, account_handler)`
-
- The constructor is passed the config object returned by
- `parse_config`, and a `synapse.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 as `m.login.password`) to an iterable
- giving the fields which must be provided by the user in the submission
- to [the `/login` API](https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-login).
- These fields are passed in the `login_dict` dictionary to `check_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 fields `secret1` and `secret2`, the provider should
- implement this method and return the following dict:
-
- ```python
- {"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, and `None` 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 (including `access_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 a `str` containing the user's (canonical) User id if
- authentication was successful, and `None` if not.
-
- As with `check_auth`, the `Awaitable` 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` and `check_auth` for password auth
- providers that just want to provide a mechanism for validating
- `m.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
- to `True` if authentication is successful, and `False` 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 the `Awaitable` to complete, but the result is ignored.
|