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:

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:

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:

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:

{
  "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'
      }
    }
  }

Name	Description	Example	Required	Default
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:

{
  "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.

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:

{
  "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 External ID field.

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.

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 Configuration tab.

2. Select Authentication under System Settings in the left sidebar.

3. Select 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 Installing Python for Micetro Central on Windows.