Metadata-Version: 1.1
Name: matrix-synapse-ldap3
Version: 0.1.4
Summary: An LDAP3 auth provider for Synapse
Home-page: https://github.com/matrix-org/matrix-synapse-ldap3
Author: UNKNOWN
Author-email: UNKNOWN
License: UNKNOWN
Description: 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 and docker images from matrix.org.
        - If you installed into a virtualenv: `pip install matrix-synapse-ldap3`.
        - For other installation mechanisms, see the documentation provided by the maintainer.
        
        Usage
        -----
        
        Example synapse config:
        
        .. code:: yaml
        
           password_providers:
            - module: "ldap_auth_provider.LdapAuthProvider"
              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)"
        
        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
        
           password_providers:
            - module: "ldap_auth_provider.LdapAuthProvider"
              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)"
        
        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
        
           password_providers:
            - module: "ldap_auth_provider.LdapAuthProvider"
              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)"
        
        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
        
           password_providers:
            - module: "ldap_auth_provider.LdapAuthProvider"
              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
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
