Skip to main content

An LDAP3 auth provider for Synapse

Project description

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) that offers more fully-featured integration.

Installation

  • Included as standard in the deb packages and docker images 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:

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.

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:

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

Alternatively you can also put the bind_password of 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 need
     bind_password_file: "/var/secrets/synapse-ldap-bind-password"

Please note that every trailing \n in the password file will be stripped automatically.

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:

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:

handlers:
  file:
    # [...]
    level: DEBUG
  • Add the following to the loggers section:

loggers:
   # [...]
   ldap3:
     level: DEBUG
   ldap_auth_provider:
     level: DEBUG

Finally, restart your Synapse server for the changes to take effect:

synctl restart

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matrix-synapse-ldap3-0.3.0.tar.gz (21.0 kB view details)

Uploaded Source

Built Distribution

matrix_synapse_ldap3-0.3.0-py3-none-any.whl (14.1 kB view details)

Uploaded Python 3

File details

Details for the file matrix-synapse-ldap3-0.3.0.tar.gz.

File metadata

  • Download URL: matrix-synapse-ldap3-0.3.0.tar.gz
  • Upload date:
  • Size: 21.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.5

File hashes

Hashes for matrix-synapse-ldap3-0.3.0.tar.gz
Algorithm Hash digest
SHA256 8bb6517173164d4b9cc44f49de411d8cebdb2e705d5dd1ea1f38733c4a009e1d
MD5 3d7ee1661060640df397b1b4a24d8b0e
BLAKE2b-256 507580322f4a05c3d582c579eb580df34da8932577ca5f4f844e1d46946f6096

See more details on using hashes here.

Provenance

File details

Details for the file matrix_synapse_ldap3-0.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for matrix_synapse_ldap3-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8b4d701f8702551e98cc1d8c20dbed532de5613584c08d0df22de376ba99159d
MD5 9734fc61985f0820ea4ed860dc62c4a5
BLAKE2b-256 c9879484876f57c370f059228e9f201d912ca3892026aebd46da50847ca78719

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page