Package: matrix-synapse-ldap3
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 alsoma1sd(3rd party)
that offers more fully-featured integration.InstallationIncluded as standard in thedeb packagesanddocker imagesfrom 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.UsageExample Synapse configuration:modules:-module:"ldap_auth_provider.LdapAuthProviderModule"config:enabled:trueuri:"ldap://ldap.example.com:389"start_tls:truebase:"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: secretIf 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.modules:-module:"ldap_auth_provider.LdapAuthProviderModule"config:enabled:trueuri:-"ldap://ldap1.example.com:389"-"ldap://ldap2.example.com:389"start_tls:truebase:"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: secretIf 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:modules:-module:"ldap_auth_provider.LdapAuthProviderModule"config:enabled:truemode:"search"uri:"ldap://ldap.example.com:389"start_tls:truebase:"ou=users,dc=example,dc=com"attributes:uid:"cn"mail:"mail"name:"givenName"# Search auth if anonymous search not enabledbind_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: secretAlternatively you can also put thebind_passwordof your service user into its
own file to not leak secrets into your configuration:modules:-module:"ldap_auth_provider.LdapAuthProviderModule"config:enabled:true# all the other options you needbind_password_file:"/var/secrets/synapse-ldap-bind-password"Please note that every trailing\nin the password file will be stripped automatically.Active Directory forest supportIf theactive_directoryflag is set totrue, 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 theexample.comforest:modules:-module:"ldap_auth_provider.LdapAuthProviderModule"config:enabled:truemode:"search"uri:"ldap://main.example.com:389"base:"dc=example,dc=com"# Must be true for this feature to workactive_directory:true# Optional. Users from this domain may log in without specifying the domain partdefault_domain:main.example.comattributes: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 eithermain\someuser,main.example.com\someuser,someuser/main.example.comorsomeuser.Users of other domains in theexample.comforest can log in withdomain\loginorlogin/domain.Please note thatuserPrincipalNameor a similar-looking LDAP attribute in the formatlogin@domainmust be used when theactive_directoryoption is enabled.Troubleshooting and Debuggingmatrix-synapse-ldap3logging is included in the Synapse homeserver log
(typicallyhomeserver.log). The LDAP plugin log level can be increased toDEBUGfor troubleshooting and debugging by making the following modifications
to your Synapse server’s logging configuration file:Set the value forhandlers.file.leveltoDEBUG:handlers:file:# [...]level:DEBUGAdd the following to theloggerssection:loggers:# [...]ldap3:level:DEBUGldap_auth_provider:level:DEBUGFinally, restart your Synapse server for the changes to take effect:synctlrestart