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.
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.pip install -U pip
.pip install matrix-synapse-ldap3
.Example Synapse configuration:
.. code:: yaml
modules:
#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:
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:
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
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
modules:
bind_password_file: "/var/secrets/synapse-ldap-bind-password"
Please note that every trailing \n
in the password file will be stripped automatically.
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:
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.
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:
handlers.file.level
to DEBUG
:.. code:: yaml
handlers: file:
level: DEBUG
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