Configure: User federation with AD or LDAP
Configure: User federation with AD or LDAP
Overview
This article explains how to add a new User Federation provider to Secure Access (previously known as ESA), connecting it to an LDAP or Active Directory (AD) directory so that directory users can authenticate against that solution.
Secure Access's admin console is, internally, an unrebranded Keycloak instance. The screens in this article are the stock Keycloak User Federation pages, so the terminology (Realm, Vendor, Edit Mode, LDAP mapper, etc.) is Keycloak's own.
Before You Start
On a 2025.2 or later environment, the recommended way to connect a directory to Secure Access is to create an Authentication Task under the relevant connector (AD/LDAP) in the ESM Connectors module. That task automatically syncs down to Secure Access (around a 1 minute delay) and creates the User Federation entry for you.
Use the manual steps below when there is no Authentication Task to sync from (older environments, a standalone OpenLDAP directory with no matching EPE connector, or troubleshooting an existing federation).
Before adding a new provider, make sure you have:
- Admin access to the Secure Access console as
main.admin(https://{TENANT}.com/auth/), on the correct realm. - Network connectivity from the Secure Access (ESA) container to the LDAP/AD server, on the correct port (389 for LDAP, 636 for LDAPS).
- A bind account (Bind DN) with read access to the directory, and its credentials.
- The base DN(s) / OU(s) that contain the users to be imported.
- The directory vendor (Active Directory, generic LDAP, RHDS, etc.) so the correct Vendor template can be selected.
Step 1: Add a New LDAP User Federation Provider
Log in to the Secure Access admin console, select the correct realm, and go to User Federation > Add Ldap providers. Fill in the General options and Connection and authentication settings sections.

| Field | Purpose | Example (from screenshot) |
|---|---|---|
| UI display name | Name shown for this provider in the User Federation list. Use something that identifies the directory and scope. | OpenLDAP Connector - OU=Internal Users,OU=solutions,DC=efecte,DC=com |
| Vendor | Directory type. Controls default attribute mappings (e.g. username/UUID attributes). Choose the value that matches the actual directory server, not necessarily the display name. | Active Directory |
| Connection URL | LDAP(S) URL of the directory server, ldap:// or ldaps:// plus host and port. |
ldap://94.237.83.233:389 |
| Enable StartTLS | Encrypts the connection over the plain LDAP port. Recommended for anything handling real user credentials. | Off |
| Use Truststore SPI | Which Keycloak truststore to use for validating the directory's TLS certificate (LDAPS/StartTLS only). | Not set |
| Connection pooling | Reuses LDAP connections instead of opening a new one per request. | Off |
| Connection timeout | Milliseconds before a connection attempt times out. Blank uses the default. | Not set |
| Bind type | Authentication method used to bind to the directory. | simple |
| Bind DN | Distinguished name of the account Secure Access uses to query the directory. | cn=admin,dc=efecte,dc=com |
| Bind credentials | Password for the Bind DN account. | Hidden |
Use the Test connection button to confirm the Connection URL is reachable, and Test authentication to confirm the Bind DN and credentials are valid, before saving.
Step 2: Configure LDAP Searching and Updating
Scroll down to the LDAP searching and updating section and configure how Secure Access locates and reads user entries.

| Field | Purpose | Example (from screenshot) |
|---|---|---|
| Edit mode | Whether Secure Access may write back to the directory. Use READ_ONLY unless password changes/updates must be pushed back to the source directory. |
READ_ONLY |
| Users DN | Base DN under which user entries are searched. | OU=Internal Users,OU=solutions,DC=efecte,DC=com |
| Relative user creation DN | Where new users are created, relative to Users DN (only relevant when Edit mode allows writes). | Not set |
| Username LDAP attribute | Directory attribute mapped to the Keycloak username. | uid |
| RDN LDAP attribute | Attribute used as the entry's relative distinguished name. | entryDN |
| UUID LDAP attribute | Attribute used as the entry's unique, immutable identifier. | entryUUID |
| User object classes | Object classes an LDAP entry must have to be treated as a user. | person, organizationalPerson, inetOrgPerson |
| User LDAP filter | Additional LDAP filter applied on top of the object classes above. | (objectClass=person) |
| Search scope | How deep under Users DN the search looks. | Subtree |
| Read timeout | Milliseconds before a read operation times out. Blank uses the default. | Not set |
| Pagination | Enables paged LDAP search results, needed for directories with large numbers of users. | On |
| Referral | How LDAP referrals are handled during search. | Not set |
Step 3: Configure Synchronization Settings
Scroll down to Synchronization settings to control how and how often Secure Access pulls users from the directory.

| Field | Purpose | Example (from screenshot) |
|---|---|---|
| Import users | Imports directory users into Secure Access's own database on first authentication/sync. Should be On for a standard federation. | On |
| Sync Registrations | Whether newly registered Secure Access users are written back to this directory. | Off |
| Batch size | Number of users processed per batch during a sync. | 1000 |
| Periodic full sync | Automatically runs a full sync of all users on a schedule. | On |
| Full sync period | Seconds between full syncs. |
86400 (24 hours) |
| Periodic changed users sync | Automatically syncs only users changed since the last sync, on a schedule. | On |
| Changed users sync period | Seconds between changed-users syncs. |
300 (5 minutes) |
| Remove invalid users during searches | Removes locally imported users that no longer match the search filter/DN in the directory. | On |
Kerberos integration (lower on the same screen) is only needed for Kerberos-based SSO against this directory. Leave both Allow Kerberos authentication and Use Kerberos for password authentication off unless Kerberos SSO is explicitly required.
Step 4: Configure Cache and Advanced Settings

| Field | Purpose | Example (from screenshot) |
|---|---|---|
| Cache policy | How long imported user data is cached before being re-read from the directory. | DEFAULT |
| Enable the LDAPv3 password modify extended operation | Uses the LDAPv3 extended operation for password changes instead of a plain attribute write. Only relevant with a writable Edit mode. | Off |
| Validate password policy | Enforces the directory's own password policy on password changes made through Secure Access. | Off |
| Trust Email | Treats the imported email address as already verified. | Off |
| Connection trace | Enables verbose LDAP connection logging for troubleshooting. | Off |
Query Supported Extensions queries the directory server for the LDAP extensions it supports, useful when deciding whether to enable the password modify extended operation above.
Step 5: Save and Synchronize Users
- Click Save.
- Open the provider's Action menu and select Synchronize all users to pull in the initial set of users.
- Check the Mappers tab. An AD_GroupMapper (
group-ldap-mapper) is usually created automatically; create one manually if it is missing and group membership needs to sync.
Once synchronization completes without errors, directory users under the configured Users DN appear under Users in Secure Access and can authenticate against this federation.
Troubleshooting
SSL trust error: "PKIX path building failed"
This error in keycloak.log means Secure Access does not trust the certificate presented by the AD/LDAP server over LDAPS. Fix it from inside the Secure Access (ESA) container:
openssl s_client -connect IP:636
keytool -importcert -file <exported-cert> -keystore truststore.jks
docker stop [TENANT]-esa && run-image -e TENANT=[TENANT] esa
This procedure requires container-level access to the Secure Access environment and should only be performed by Matrix42 delivery/operations staff.
Result
Secure Access now has a working LDAP/AD User Federation provider. Users from the configured directory and base DN can authenticate against any solution routed through Secure Access, and will be kept in sync according to the schedule configured in Step 3.
Table of Contents