Configure LDAP authentication

Introduction

This document describes how to configure LDAP authentication in Micetro.

Installation on Centos Linux

  1. Download the Python script and signature file from GitHub.

  2. To use LDAP authentication and authorization, start by installing mm_ldap.py on the machine where the Men&Mice 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 Men&Mice 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 permissions 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 the Men&Mice Central service to authenticate users using an LDAP service.

To configure the Men&Mice Central service, login as the superuser administrator through the Men&Mice Management Console. In the top left-hand corner select Tools ‣ System Settings ‣ Advanced and check the Enable LDAP integration checkbox.

Using LDAP with Central running on Windows

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