diff --git a/README.rst b/README.md similarity index 64% rename from README.rst rename to README.md index a01fc6e..8e0ea24 100644 --- a/README.rst +++ b/README.md @@ -1,28 +1,37 @@ -Synapse LDAP Auth Provider -========================== +# Synapse LDAP Auth Provider Allows synapse to use LDAP as a password provider. This allows users to log in to synapse with their username and password from an -LDAP server. There is also `ma1sd `_ (3rd party) +LDAP server. There is also [ma1sd](https://github.com/ma1uta/ma1sd) (3rd party) that offers more fully-featured integration. -Installation ------------- -- Included as standard in the `deb packages `_ and - `docker images `_ from matrix.org. +> [!WARNING] +> Synapse's password provider plugin functionality (which this module relies on) +> is not compatible with [Matrix Authentication +> Service](https://github.com/element-hq/matrix-authentication-service) (MAS), the +> next-gen Matrix auth server. +> +> To use Synapse and MAS together with an LDAP backend, it is recommended to use +> [Dex](https://github.com/dexidp/dex) with [MAS](https://github.com/element-hq/matrix-authentication-service), instead of +> `matrix-synapse-ldap3`. See [the relevant MAS +> documentation](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#map-any-upstream-sso-providers) +> for information on configuring Dex in MAS. + +## Installation + +- Included as standard in the [deb packages](https://matrix-org.github.io/synapse/latest/setup/installation.html#matrixorg-packages) and + [docker images](https://matrix-org.github.io/synapse/latest/setup/installation.html#docker-images-and-ansible-playbooks) from matrix.org. - If you installed into a virtualenv: - Ensure pip is up-to-date: `pip install -U pip`. - Install the LDAP password provider: `pip install matrix-synapse-ldap3`. - For other installation mechanisms, see the documentation provided by the maintainer. -Usage ------ +## Usage Example Synapse configuration: -.. code:: yaml - +```yaml modules: - module: "ldap_auth_provider.LdapAuthProviderModule" config: @@ -43,12 +52,12 @@ Example Synapse configuration: # local_certificate_file: foo.crt # local_private_key_file: bar.pem # local_private_key_password: secret +``` If you would like to specify more than one LDAP server for HA, you can provide uri parameter with a list. Default HA strategy of ldap3.ServerPool is employed, so first available server is used. -.. code:: yaml - +```yaml modules: - module: "ldap_auth_provider.LdapAuthProviderModule" config: @@ -70,13 +79,13 @@ Default HA strategy of ldap3.ServerPool is employed, so first available server i # local_certificate_file: foo.crt # local_private_key_file: bar.pem # local_private_key_password: secret +``` If you would like to enable login/registration via email, or givenName/email binding upon registration, you need to enable search mode. An example config in search mode is provided below: -.. code:: yaml - +```yaml modules: - module: "ldap_auth_provider.LdapAuthProviderModule" config: @@ -98,39 +107,38 @@ in search mode is provided below: # local_certificate_file: foo.crt # local_private_key_file: bar.pem # local_private_key_password: secret +``` -Alternatively you can also put the ``bind_password`` of your service user into its +Alternatively you can also put the `bind_password` of your service user into its own file to not leak secrets into your configuration: -.. code:: yaml - +```yaml modules: - module: "ldap_auth_provider.LdapAuthProviderModule" config: enabled: true # all the other options you need bind_password_file: "/var/secrets/synapse-ldap-bind-password" +``` -Please note that every trailing ``\n`` in the password file will be stripped automatically. +Please note that every trailing `\n` in the password file will be stripped automatically. -Active Directory forest support -------------------------------- +## Active Directory forest support -If the ``active_directory`` flag is set to ``true``, an Active Directory forest will be +If the ``active_directory`` flag is set to `true`, an Active Directory forest will be searched for the login details. In this mode, the user enters their login details in one of the forms: -- ``/`` -- ``\`` +- `/` +- `\` -In either case, this will be mapped to the Matrix UID ``/`` (The -normal AD domain separators, ``@`` and ``\``, cannot be used in Matrix User Identifiers, so -``/`` is used instead.) +In either case, this will be mapped to the Matrix UID `/` (The +normal AD domain separators, `@` and `\`, cannot be used in Matrix User Identifiers, so +`/` is used instead.) -Let's say you have several domains in the ``example.com`` forest: - -.. code:: yaml +Let's say you have several domains in the `example.com` forest: +```yaml modules: - module: "ldap_auth_provider.LdapAuthProviderModule" config: @@ -148,46 +156,46 @@ Let's say you have several domains in the ``example.com`` forest: name: "givenName" bind_dn: "cn=hacker,ou=svcaccts,dc=example,dc=com" bind_password: "ch33kym0nk3y" +``` -With this configuration the user can log in with either ``main\someuser``, -``main.example.com\someuser``, ``someuser/main.example.com`` or ``someuser``. +With this configuration the user can log in with either `main\someuser`, +`main.example.com\someuser`, `someuser/main.example.com` or `someuser`. -Users of other domains in the ``example.com`` forest can log in with ``domain\login`` -or ``login/domain``. +Users of other domains in the `example.com` forest can log in with `domain\login` +or `login/domain`. -Please note that ``userPrincipalName`` or a similar-looking LDAP attribute in the format -``login@domain`` must be used when the ``active_directory`` option is enabled. +Please note that `userPrincipalName` or a similar-looking LDAP attribute in the format +`login@domain` must be used when the `active_directory` option is enabled. -Troubleshooting and Debugging ------------------------------ +## Troubleshooting and Debugging -``matrix-synapse-ldap3`` logging is included in the Synapse homeserver log -(typically ``homeserver.log``). The LDAP plugin log level can be increased to -``DEBUG`` for troubleshooting and debugging by making the following modifications +`matrix-synapse-ldap3` logging is included in the Synapse homeserver log +(typically `homeserver.log`). The LDAP plugin log level can be increased to +`DEBUG` for troubleshooting and debugging by making the following modifications to your Synapse server's logging configuration file: - Set the value for `handlers.file.level` to `DEBUG`: -.. code:: yaml - +```yaml handlers: file: # [...] level: DEBUG +``` - Add the following to the `loggers` section: -.. code:: yaml - +```yaml loggers: # [...] ldap3: level: DEBUG ldap_auth_provider: level: DEBUG +``` Finally, restart your Synapse server for the changes to take effect: -.. code:: sh - - synctl restart +```shell +synctl restart +```