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’ll 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 here 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 will also have to 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

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

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 pane.

3. Select the Enable LDAP integration.

Using LDAP with Central Running on Windows

To use LDAP with a Micetro Central server running on Windows, Python must be installed for all users. See Installing Python for Micetro Central on Windows.