Skip to main content

LDAP Configuration

The LDAP Authentication module allows Mango to authenticate users against an LDAP directory server or Microsoft Active Directory. The module supports configurable authentication order, automatic user creation, and role synchronization.

Overview​

When LDAP authentication is enabled, Mango attempts to authenticate users through all available authentication methods in priority order and rejects the user only if none succeed. The module provides the following capabilities:

  • Priority-based authentication -- Configure the order in which authentication methods are tried (LDAP, token auth, local username/password).
  • Automatic user creation -- New users logging into Mango for the first time via LDAP are automatically created in the Mango database.
  • Role synchronization -- Optionally synchronize Mango roles with LDAP groups on each login based on regex matching and configurable role behavior.
  • Active Directory support -- Full support for Microsoft Active Directory with domain and root DN configuration.

Configuration Properties​

Add the following properties to your mango.properties file. Adjust the values to match your LDAP server configuration.

Core Settings​

# Enable LDAP authentication
ldap.enabled=true

# Authentication priority (lower values = higher priority)
# Default priorities: Token Auth = 2, Mango Username/Password = 1
ldap.authentication.order=0

# LDAP server URL
ldap.authentication.url=ldap://ldap.example.com:389/dc=example,dc=com

# Manager DN for authenticating to the LDAP server
# Omit for anonymous access
ldap.authentication.managerDn=cn=admin,dc=example,dc=com
ldap.authentication.managerPassword=manager_password

# Password encoding: PLAIN, BCRYPT, SCRYPT, ARGON2, SHA, PBKDF2, MD4
# Using anything other than PLAIN, BCRYPT, or SHA may result in locked passwords
ldap.authentication.encoder=PLAIN

# Lock passwords so users can only log in via LDAP
ldap.authentication.lockPasswords=false

User Search Settings​

# DN patterns for direct user lookup (semicolon-separated for multiple patterns)
ldap.authentication.userDnPatterns=uid={0},ou=people

# LDAP filter for searching users (e.g., "(uid={0})")
# {0} is replaced with the login name
ldap.authentication.userSearchFilter=

# Search base for user searches (used with userSearchFilter)
ldap.authentication.userSearchBase=

Group and Role Settings​

# Search base for group membership
ldap.authentication.groupSearchBase=ou=groups

# LDAP filter for group search ("{0}" is the user's DN)
ldap.authentication.groupSearchFilter=(uniqueMember={0})

# Attribute containing the role name
ldap.authentication.groupRoleAttribute=cn

# Create new Mango roles for LDAP groups that do not exist
ldap.authorization.createNewRoles=true

# Regex to filter which roles are created
ldap.authorization.newRoleRegex=.*

# Role synchronization behavior:
# LDAP_ONLY    - Only LDAP roles used, replaced on every login (default)
# MANGO_ONLY   - All LDAP roles ignored
# LDAP_ADDITIVE - LDAP roles are added to existing Mango roles
ldap.authentication.roleBehavior=LDAP_ONLY

User Attribute Mapping​

ldap.authentication.passwordAttribute=userPassword
ldap.authentication.nameAttribute=cn
ldap.authentication.emailAttribute=mail

Active Directory Settings​

# Enable Active Directory mode
ldap.authentication.isActiveDirectory=true

# AD domain (used if username has no domain)
ldap.authentication.activeDirectory.domain=example.com

# Root DN (can be empty)
ldap.authentication.activeDirectory.rootDn=

Role Synchronization Behavior​

The ldap.authentication.roleBehavior property controls how Mango handles roles from LDAP:

ModeBehavior
LDAP_ONLYMango roles are completely replaced with LDAP roles on every login. If a role is removed in LDAP, it is removed in Mango on next login.
MANGO_ONLYAll LDAP group information is ignored. Roles are managed exclusively within Mango.
LDAP_ADDITIVELDAP roles are added to the user's existing Mango roles. Removing a role in LDAP does not remove it from Mango -- manual intervention is required.

For most environments, LDAP_ONLY is recommended because it keeps Mango roles fully synchronized with the LDAP directory.

Testing Your Configuration​

  1. Start Mango with the LDAP configuration in place.
  2. Attempt to log in with an LDAP user's credentials.
  3. Check MA_HOME/logs/ma.log for authentication-related log messages.
  4. If authentication fails, enable debug logging for com.serotonin.m2m2 to get detailed diagnostics. See Debug Log Settings.

Troubleshooting​

Users Cannot Log In​

  • Verify the LDAP URL, manager DN, and password are correct.
  • Check that the user DN pattern or search filter matches your directory structure.
  • Ensure the LDAP server is reachable from the Mango host (test with ldapsearch on Linux).

Roles Not Synchronizing​

  • Verify the groupSearchBase and groupSearchFilter match your LDAP group structure.
  • Check that ldap.authorization.createNewRoles=true if the roles do not already exist in Mango.
  • Review the newRoleRegex to ensure it matches the group names you expect.