An LDAP3 auth provider for Synapse
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Shay 23c2479a88
Merge pull request #171 from matrix-org/bump_release
2 weeks ago
.github Module template retrofit: Fix up type annotations and enable Mypy type checking in GHA CI (#145) 8 months ago
scripts-dev Module template retrofit: Lint script and Mypy configuration (#140) 8 months ago
tests requested changes 2 weeks ago
.codecov.yml Enable codecov support 3 years ago
.coveragerc Add test coverage support 3 years ago
.gitignore Module template retrofit: Update .gitignore (#139) 8 months ago
LICENSE Initial commit 6 years ago
MANIFEST.in Module template retrofit: Lint script and Mypy configuration (#140) 8 months ago
README.rst Link to Synapse installation docs 5 months ago
RELEASING.md Changed packaging to use setuptools declarative config in setup.cfg. (#129) 10 months ago
ldap_auth_provider.py bump version 2 weeks ago
mypy.ini Clean-up and type annotations (#150) 7 months ago
pyproject.toml Module template retrofit: Update Python project metadata and tool configuration (#146) 8 months ago
requirements.txt Initial commit 6 years ago
setup.cfg bump version of black 4 months ago
tox.ini Include ldaptor and mock in the test dependencies (#149) 7 months ago

README.rst

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 (https://github.com/ma1uta/ma1sd) (3rd party)
that offers more fully-featured integration.

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
-----

Example Synapse configuration:

.. code:: yaml

modules:
- module: "ldap_auth_provider.LdapAuthProviderModule"
config:
enabled: true
uri: "ldap://ldap.example.com:389"
start_tls: true
base: "ou=users,dc=example,dc=com"
attributes:
uid: "cn"
mail: "mail"
name: "givenName"
#bind_dn:
#bind_password:
#filter: "(objectClass=posixAccount)"
# Additional options for TLS, can be any key from https://ldap3.readthedocs.io/en/latest/ssltls.html#the-tls-object
#tls_options:
# validate: true
# 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

modules:
- module: "ldap_auth_provider.LdapAuthProviderModule"
config:
enabled: true
uri:
- "ldap://ldap1.example.com:389"
- "ldap://ldap2.example.com:389"
start_tls: true
base: "ou=users,dc=example,dc=com"
attributes:
uid: "cn"
mail: "email"
name: "givenName"
#bind_dn:
#bind_password:
#filter: "(objectClass=posixAccount)"
#tls_options:
# validate: true
# 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

modules:
- module: "ldap_auth_provider.LdapAuthProviderModule"
config:
enabled: true
mode: "search"
uri: "ldap://ldap.example.com:389"
start_tls: true
base: "ou=users,dc=example,dc=com"
attributes:
uid: "cn"
mail: "mail"
name: "givenName"
# Search auth if anonymous search not enabled
bind_dn: "cn=hacker,ou=svcaccts,dc=example,dc=com"
bind_password: "ch33kym0nk3y"
#filter: "(objectClass=posixAccount)"
#tls_options:
# validate: true
# local_certificate_file: foo.crt
# local_private_key_file: bar.pem
# local_private_key_password: secret

Active Directory forest support
-------------------------------

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:

- ``<login>/<domain>``
- ``<domain>\<login>``

In either case, this will be mapped to the Matrix UID ``<login>/<domain>`` (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

modules:
- module: "ldap_auth_provider.LdapAuthProviderModule"
config:
enabled: true
mode: "search"
uri: "ldap://main.example.com:389"
base: "dc=example,dc=com"
# Must be true for this feature to work
active_directory: true
# Optional. Users from this domain may log in without specifying the domain part
default_domain: main.example.com
attributes:
uid: "userPrincipalName"
mail: "mail"
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``.

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.

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
to your Synapse server's logging configuration file:

- Set the value for `handlers.file.level` to `DEBUG`:

.. code:: yaml

handlers:
file:
# [...]
level: DEBUG

- Add the following to the `loggers` section:

.. code:: 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