.. meta:: :description: How to enable ldap authentication in Micetro :keywords: ldap, external authentication .. _ldap-user-auth: Lightweight Directory Access Protocol (LDAP) user authentication ================================================================ LDAP user authentication allows you to configure user authentication against an LDAP server, providing a streamlined method for managing user access across systems and services. To implement LDAP authentication, you first need to set up an authentication server that hosts the LDAP directory containing user credentials. Once the authentication server is established, you can enable LDAP authentication within Micetro, allowing users to authenticate using their LDAP credentials. Installation on Centos Linux ---------------------------- 1. Confirm that there is directory called “extensions” in the Central data directory, and that it contains a Python script named ``mm_auth_cb.py`` and an accompanying signature file. This Python script handles the authentication callback from the external provider. The directory and files are created during the installation of Micetro Central. 2. To use LDAP authentication and authorization, start by installing ``mm_ldap.py`` on the machine where the Micetro Central service is run and install the Python extension used by Central when connecting to an LDAP directory: .. code-block:: bash sudo yum install python-ldap sudo mkdir /var/mmsuite/mmcentral/extensions sudo cp mm_ldap.py /var/mmsuite/mmcentral/extensions sudo chown -R root:root /var/mmsuite/mmcentral/extensions sudo chmod 440 /var/mmsuite/mmcentral/extensions/mm_ldap.py A signature file for the Python extension must also be installed and placed in the extension directory: .. code-block:: bash sudo cp mm_ldap.signature /var/mmsuite/mmcentral/extensions .. note:: For security reasons, the Central service will not execute ``mm_ldap.py`` unless the signature ``inmm_ldap.signature`` matches the signature calculated for ``mm_ldap.py``. Configuring LDAP with Active Directory -------------------------------------- LDAP configurations are stored in a JSON config file that should be stored in the Micetro Central service root directory: .. code-block:: bash sudo cp ldapconf.json /var/mmsuite/mmcentral sudo chown root:root /var/mmsuite/mmcentral/ldapconf.json sudo chmod 440 /var/mmsuite/mmcentral/ldapconf.json The configuration file for AD has the following schema: .. code-block:: { "server": { "uri": str, // e.g. ldaps://example.com:636 "reader_dn": str | null, "reader_password": str | null, "skip_cert_verification": bool | null, // Default: false. "ca_cert_file": str | null, "disable_referrals": bool | null, // Default: true. "use_start_tls": bool | null, // Default: false. }, "user_search_config": { "base_dn": str, "search_filter": str, "scope": "subtree" | "onelevel", // Default: 'subtree' "email_attribute": str | null, "group_search_config": null | { "base_dn": str, "scope": "subtree" | "onelevel", // Default: 'subtree' "search_filter": str, "name_attribute": str // Default: 'name' } } } .. csv-table:: :header: "Name", "Description", "Example", "Required", "Default" :widths: 10, 70, 10, 5, 5 "uri","URI for LDAP service.", "ldaps://example.com:636", "Yes", "None" "reader_dn","DN or login name for a user that has permission to search in the directory. Not needed when all users have permissions to search (for example AD LDAP service).", "user@example.com", "No", "None" "reader_password", "Password for reader_dn user.",, "No", "None" "skip_cert_verification", "If true, then certificates will not be verified. Set to true when using self-signed certificates.",, "No", "false" "ca_cert_file", "Path of file containing all trusted CA certificates.",, "No", "None" "disable_referrals", "Skip referrals when doing LDAP queries. Should be set to true for AD LDAP services.", "No", "true" "user_start_tls", "Use TLS when connecting to LDAP service. This is still experimental. Please use LDAPS instead.",, "No", "false" "user_search_config.base_dn", "DN from where to start searching for a user in the directory.", "'dc=corp, dc=example, dc=com'", "Yes", "None" "user_search_config.search_filter", "Filter to use for searching for a user. Username will be inserted into placeholder '{username}' if specified.", "(&(objectClass=user)(userPrincipalName={username}))", "Yes", "None" "scope", "Scope to use when searching. Should be either 'subtree' or 'onelevel'. Defaults to 'subtree'.", "subtree", "No", "subtree" "email_attribute", "LDAP attribute used to store users email address.", "userPrincipalName", "No", "None" "group_search_config.base_dn", "DN from where to start searching for groups in the directory.", "'dc=corp, dc=example, dc=com'", "If group authentication is used.", "None" "group_search_config.scope", "Scope to use when searching. Should be either 'subtree' or 'onelevel'. Defaults to 'subtree'.", "subtree", "No", "subtree" "group_search_config.search_filter", "Search filter to use when searching for groups. Users DN will be inserted into placeholder '{dn}' if specified. Username will be inserted into placeholder '{username}' if specified.", "(&(objectClass=group)(member:={dn}))", "If group authentication is used.", "None" "group_search_config.name_attribute", "Attribute used to store name of group.", "name", "If group authentication is used.", "name" Example configuration for connecting to an AD LDAP service: .. code-block:: { "server": { "uri": "ldaps://ldap.example.com:636", "skip_cert_verification": false, "disable_referrals": true, "use_start_tls": false }, "user_search_config": { "base_dn": "dc=corp, dc=example, dc=com", "search_filter": "(&(objectClass=user)(userPrincipalName={username}))", "scope": "subtree", "email_attribute": "userPrincipalName", "group_search_config": { "base_dn": "dc=corp, dc=example, dc=com", "scope": "subtree", "search_filter": "(&(objectClass=group)(member:={dn}))", "name_attribute": "name" } } } Configuring LDAP with openLDAP ------------------------------ LDAP configurations are stored in a JSON config file that should be stored in the Micetro Central service root directory. .. code-block:: bash sudo cp ldapconf.json /var/mmsuite/mmcentral sudo chown root:root /var/mmsuite/mmcentral/ldapconf.json sudo chmod 440 /var/mmsuite/mmcentral/ldapconf.json To configure LDAP with openLDAP, install the server and use LDAP Account Manager to create users and groups, and add users to groups. Example configuration for connecting to an openLDAP LDAP service: .. code-block:: { "method": "authenticate", "server": { "uri": "ldap://ldap.example.com:636", "reader_dn": "cn=admin, dc=corp, dc=example, dc=com", "reader_password": "admin_password", "skip_cert_verification": false, "disable_referrals": true, "use_start_tls": false }, "user_search_config": { "base_dn": "dc=corp, dc=example, dc=com", "search_filter": "uid={username}", "group_search_config": { "base_dn": "ou=groups, dc=corp, dc=example, dc=com", "search_filter": "(&(objectClass=posixGroup)(memberUid={username}))", "name_attribute": "cn" } }, "version": [1, 0] } .. note:: In the ``name_attribute`` field, ``cn`` ("common name") refers to the group name in LDAP. In the LDAP configuration JSON file, enter ``cn`` in the ``name_attribute`` field if that attribute is used for group name in LDAP, not the group name itself. Additionally, replace the ``reader_dn`` and ``reader_password`` values with the admin credentials from LDAP. After setting up the server, enable LDAP authentication in Micetro as described below. Once LDAP is enabled in Groups, you can create an LDAP group. The group must have the same name in both Micetro and LDAP. Enter this name in the :guilabel:`External ID` field. .. image:: ../../images/ldap-users-externalid.png :width: 85% The next time you log in with an LDAP username created in LAM --- and that user is added to the specific group in LAM --- your user will be automatically added to the **Users** list with the permissions assigned to the associated group created in Micetro. .. image:: ../../images/ldap-authtype-group.png :width: 90% .. note:: LDAP users are only added to the LDAP group list after logging into Micetro. Enabling LDAP in Micetro ------------------------ After completing the setup of the server, you need to enable the LDAP authentication method in Micetro. **To enable LDAP integration**: 1. On the **Admin** page, select the :guilabel:`Configuration` tab. 2. Select :guilabel:`Authentication` under :guilabel:`System Settings` in the left sidebar. 3. Select :guilabel:`Enable LDAP integration`. Using LDAP with Micetro Central running on Windows -------------------------------------------------- To use LDAP with a Micetro Central server running on Windows, Python must be installed for all users. Refer to :ref:`central-python-ldap`.