Configuring LDAP

The LDAP plugin integrates LiveAgent with your organization's LDAP directory. It provides two main capabilities: importing agents directly from LDAP, and authenticating those agents using their LDAP credentials at login.

For common issues after setup, see LDAP troubleshooting.

Supported features

• Import agents from your LDAP directory into LiveAgent
• Authenticate agents at login using their LDAP username and password
• Filter agent imports to a specific LDAP group
• Fallback to LiveAgent's built-in authentication if the LDAP server is unreachable

Requirements

• Every user you want to import must have a valid email address in the LDAP directory. Users without an email address cannot be imported.
• Your LDAP directory must use the posixGroup object class and the memberuid attribute if you intend to use group-based filtering during import.

Step 1 — Activate the plugin

Go to Configuration → Plugins and activate the LDAP plugin.

Step 2 — Configure the connection

After activation, open Configuration → LDAP. All fields are mandatory. When you save, LiveAgent validates the URL and port and attempts a test connection to the server before storing the settings.

• LDAP server URL — The full URL of your LDAP server, including the protocol prefix. Example: ldap://ldap.example.com
• Port — The port your LDAP server listens on. Select from the dropdown: 389 (default, plain LDAP), 636 (LDAPS), 80, or 443. Example: 389
• User Base DN — The base distinguished name of the directory subtree that contains your users. LiveAgent searches this subtree when listing and importing agents. Example: ou=people,dc=example,dc=com
• Group Base DN — The base distinguished name of the directory subtree that contains your groups. Used only when filtering imports by group name. Example: ou=groups,dc=example,dc=com
• User ID field — The LDAP attribute used as the unique identifier for each user. This value is stored per agent at import time and is also used to construct the login DN during authentication. Common values are uid or cn. Example: uid
• User email field — The LDAP attribute that holds the user's email address. LiveAgent uses this to match LDAP users against existing agents and to set the agent's email on import. Example: mail

Once all fields are filled in and the connection test passes, the Import agents button becomes available.

Step 3 — Import agents

Click the Import agents button to open the import dialog. You will need LDAP admin credentials with read access to the configured directory subtree. These credentials are not stored by LiveAgent and must be entered each time you open the dialog.

• Admin DN — The full distinguished name of an LDAP user who can read the entire directory subtree. Example: cn=admin,dc=example,dc=com
• Admin password — Password for the Admin DN account.
• Group name (optional) — If specified, only members of this group are listed. The group is matched by its cn attribute within the Groups Base DN, using the posixGroup object class and memberuid attribute. Leave empty to list all users under the User Base DN.

Click Fetch to load the user list. Each user is shown with an import status:

• Already imported — The agent exists in LiveAgent and their LDAP identifier is already linked. No action needed; this agent can already log in via LDAP.
• Import button — The agent either does not exist in LiveAgent yet, or exists by email match but is not yet linked to their LDAP identity. Click Import to create or link the agent.
• Unable to import — The LDAP user has no value in the configured email field and cannot be imported until an email address is added in LDAP.

When you click Import, LiveAgent:

1. Looks up an existing agent by email address, or creates a new one if none exists.
2. Updates the agent's display name from the LDAP name or cn attribute if it has changed.
3. Stores the agent's LDAP identifier (the value of the configured User ID field) against their account. This link is what enables LDAP login.
4. Re-activates the agent's account if it was previously deactivated.

How LDAP authentication works

When an agent enters their email and password on the LiveAgent login page:

1. LiveAgent looks up the agent by email address.
2. It retrieves the LDAP identifier stored for that agent during import.
3. It constructs an LDAP distinguished name in the format {User ID field}={stored identifier},{User Base DN}. For example, if User ID field is cn, the stored identifier is john.doe, and User Base DN is dc=example,dc=com, the resulting DN is cn=john.doe,dc=example,dc=com.
4. LiveAgent binds to the LDAP server using that DN and the password the agent entered. If the bind succeeds, the agent is logged in; if it fails, the login is rejected.
5. If the LDAP server is unreachable, LiveAgent falls back to its built-in password authentication.

Synchronization

There is no automatic synchronization between LiveAgent and your LDAP directory. Changes in LDAP are not reflected in LiveAgent until you manually act on them.

• New user added in LDAP — The user does not appear in LiveAgent automatically. Open the Import agents dialog and import them manually.
• User removed or disabled in LDAP — Their LiveAgent account remains active and their LDAP identifier stays linked. Their next login attempt will fail because LiveAgent cannot bind to LDAP with their credentials. Note that the fallback to built-in LiveAgent authentication only applies when the LDAP server itself is unreachable — it does not apply when credentials are simply rejected. You must deactivate the agent's LiveAgent account manually to prevent access.
• User details changed in LDAP (name) — Re-importing the agent through the wizard will update their display name in LiveAgent. If a user's email address changes in LDAP, importing will create a new agent rather than update the existing one, since agents are matched by email.