Skip to main content
Workforce

Connect Active Directory

Connect your existing Active Directory to SecureAuth IAM to enable secure authentication for your workforce. This integration uses the SecureAuth LDAP Agent to create a secure connection between SecureAuth and your on-premises Active Directory.

Prerequisites​

Before connecting Active Directory, ensure you have:

  • Active Directory administrative credentials
  • Service account with read access to Active Directory
  • Virtual server or machine to host the LDAP Agent (can be configured after AD connection)
  • Network connectivity between the planned LDAP Agent location and your domain controllers

Connect Active Directory​

Step 1: Create new directory​

  1. In your Workforce workspace, go to Authentication > User Stores.
  2. Click Create New Directory. Result: The New User Directory page opens.
  3. Select Microsoft Active Directory. New User Directory page showing Microsoft Active Directory option highlighted
  4. Click Next.

Step 2: Configure connection details​

Complete the basic connection settings. Active Directory connection details form with Name, Domains, and provisioning options

Name
Enter a descriptive and unique name for your Active Directory connection.
Example: Corporate Active Directory

Domains
Select one or more domains from the list to customize your experience.
Example: company.com, hr.company.com

Enable the following based on your requirements:

Inline Factor Provisioning
Prompts users to set up authentication factors (like SMS, email, mobile authentication apps) during the login process.

Inline User Provisioning
Creates users automatically upon successful authentication.

Search Directory for Groups
Looks up user group membership directly from the directory during authentication for policy enforcement.

Step 3: Configure search and password settings​

Expand Search Lookup and Password Permission to configure user and group attributes. Search Lookup and Password Permission settings showing user and group identifier attributes

User Identifier Attribute
The attribute from the directory that uniquely matches users.
Default: mail | Alternatives: sAMAccountName, userPrincipalName

Group Identifier Attribute
The attribute that identifies groups in your directory.
Default: Object GUID | Alternative: distinguishedName

Enable the following based on your requirements:

Nested Group Searching
Matches users to groups through nested (indirect) group membership.
For example, if a user is in Group A and Group A is a member of Group B, the user will match to Group B.

Enable Change Password
Allow users to change their own AD password by entering their current password and a new one.
Note: Requires LDAP Agent version with password change support

Enable Reset Password
Allow users to reset their AD password through a password reset flow.
Note: Requires LDAP Agent version with password reset support and proper bind credentials configured.

Step 4: Configure connection settings​

Expand Connection Settings to configure agent communication. Connection Settings panel showing agent heartbeat timeout and performance options

Agent heartbeat timeout
Determines the interval between heartbeat requests to LDAP Agents, in seconds.
Default: 35 seconds

Enable optional performance features:

Agent Cache
Temporarily cache agent service responses. Helps maintain functionality during brief network interruptions.

  • Agent Cache Duration – Set how long cached responses remain valid. Enter values in hours and minutes. Default: 25 hours

Circuit breaker
Temporarily stop requests to a target service when repeated errors are detected. Prevents excessive retry attempts when the service is down.

  • Volume Threshold – Minimum number of requests in a time window before the error rate is calculated. Default: 10
  • Error Threshold – Percentage of failed requests (out of the total volume threshold) that triggers the circuit to open. Default: 50
  • Time Window – Length of the time window (in seconds) used to evaluate error rates. Default: 30
  • Sleep Window – Duration (in seconds) the system waits before retrying requests after the circuit opens. Default: 300

Step 5: Complete setup​

  1. Save your changes.
  2. Scroll down the page and download the LDAP Agent binary from the provided link.
  3. Follow the SecureAuth LDAP Agent deployment guide to complete the installation.

Verify Active Directory connection​

After configuration, confirm the Directory Information panel shows the directory as online and check the Directory Details. [screenshot placeholder]

Log locations​

  • Windows: C:\Program Files\SecureAuth\LDAP Agent\logs
  • Linux: /var/log/secureauth-ldap-agent

Next steps​

After connecting Active Directory: