LDAP Active Directory

Info

Accessible and manageable by roles that have the "Manage Authentication Services" permission such as "Project Owner".

Directory Presets

Click [Apply Preset] and pick a directory type to fill the user and group definition fields with matching defaults:

• Active Directory
• OpenLDAP
• 389 Directory Server / FreeIPA
• Active Directory (groups kept as organizational units)

Info

A confirmation dialog states that the chosen preset's values will replace anything you already entered in these fields, and that nothing is saved until you review the values and save the form yourself.

An image containing connection settings for user verification with LDAP is shown below:

The fields used in connection settings for user verification with LDAP are shown in the table below.

Field	Description
Name	Name information of the LDAP/Active Directory Identity Provider for the created Identity Provider.
Description	A description can be written to facilitate management related to the created LDAP/Active Directory Identity Provider.
LDAP Connection Pool Definition (LDAP Connection Pool Definition)	The pool from which the LDAP connection will be obtained is selected or created.
LDAP Authentication Type (LDAP Authentication Type)	One of two methods can be used when making Identity Provider with LDAP/Active Directory: 1. Simple Authentication: Username/password pair is sent to the LDAP server, and it is checked whether such a user exists. 2. Advanced Authentication: Features such as user memberships and permissions are used using the username/password pair.
User Configuration Expression (User Configuration Expression)	When Authentication Type is selected as Simple Authentication, User Configuration Expression is entered. The username coming in the request message is verified by being placed in place of {{username}} in the expression below. Accordingly, you should enter the expression below in a way that will create the LDAP search criteria according to the structure of the username that will come in the request message. For example, let the DN value of a user using the username1 be uid={{username}},ou=People,dc=example,dc=com on the LDAP server. Example 1: If the value "username1" comes as username in the request message, the expression should be written as: uid={{username}},ou=People,dc=example,dc=com Example 2: If the value "uid=username1" comes as username in the request message, the expression should be written as: {{username}},ou=People,dc=example,dc=com Example 3: If the value "uid=username1,ou=People,dc=example,dc=com" comes as user in the request message, the expression should be written as: {{username}}
User Object Class Definition (User Object Class Definition)	When Authentication Type is selected as Advanced Authentication, User Object Class Definition(s) are created.
Group Object Class Definition (Group Object Class Definition)	When Authentication Type is selected as Advanced Authentication, Group Object Class Definition(s) are created.
Variable Button (Variable)	You can select dynamic values for fields using the [<> Variable] button at the top of the page. For details, review Dynamic Variables.

Advanced Settings - User Object Class Definition

An image containing User Object Class Definition settings from advanced settings in connection settings for user verification with LDAP is shown below:

The fields used for User Object Class Definition from advanced settings in connection settings for user verification with LDAP are shown in the table below.

Field	Description
User Object Class Definition (User Object Class Definition)	The class name to be used to filter users is entered. Default value: inetOrgPerson
Custom Filter Attribute (Custom Filter Attribute)	Filter value that can be used in addition to the filter in the connection when retrieving users is entered. Example: (&(objectCategory=Person)(sAMAccountName=*))
User Base DN Attribute (User Base DN Attribute)	If this value is filled, this Base DN is used when searching and loading users instead of the Base DN in the connection. If no value is provided, the Base DN in the connection becomes valid. Example: cn=users,dc=ad,dc=example,dc=com
Search Scope (Search Scope)	Specifies at what level the search operation will be performed on the base DN.
Full Name Attribute (Full Name Attribute)	The name of the attribute to be used to find the user's full name is entered. Default value: cn
Login Name Attribute (Login Name Attribute)	The name of the attribute (login name) to be used for the user's system login is entered. Default value: uid
First Name Attribute (First Name Attribute)	The name of the attribute indicating the user's first name is entered. Default value: givenName
Last Name Attribute (Last Name Attribute)	The name of the attribute indicating the user's last name is entered. Default value: sn
E-mail Attribute (E-mail Attribute)	The name of the attribute indicating the user's e-mail address is entered. Default value: mail
Membership Attribute (Membership Attribute)	The name of the attribute indicating the user's group memberships is entered. Default value: isMemberOf
Account State Attribute (Account State Attribute)	The name of the attribute that tells whether the account has been switched off in the directory. For example, userAccountControl on Active Directory, pwdAccountLockedTime on OpenLDAP, nsAccountLock on 389 Directory Server / FreeIPA. Leave it empty to keep the current behaviour: the account state is not read and consumers are never switched off by synchronization.
Account State Format (Account State Format)	How the value of the Account State Attribute should be read: Active Directory bit mask, True means the account is switched off, The account is switched off while the attribute exists (lock time), or 389 Directory / FreeIPA lock. Picking the wrong format does not produce an error — it silently reports every locked account as active, so match it to your directory.
Attributes To Fetch (Attributes To Fetch)	When authentication is performed with LDAP, it specifies which information about the user will be retrieved in addition to authentication. When the Advanced Settings option is enabled on the LDAP Authentication Provider page, the "Attributes to Fetch" field appears. Attributes entered in this field, if present in the LDAP user, are retrieved with their values and: • If the LDAP provider is used in JWT generation, these attributes and their values (except null ones) are added to the JWT as claims. • If the LDAP provider is used in plaintext, basic, or digest authorization methods, these attributes and their values are added to the message context as custom variables. At this time, the #clientLDAPAttribute#. prefix is added to the beginning of the key value. For example, if the mail attribute is retrieved from LDAP, the key value is #clientLDAPAttribute#mail, and the value is dummy@dummy.com.

Disabled directory accounts

An account switched off in the directory is switched off in Apinizer too, once synchronization reads it. When the account is switched on again in the directory, synchronization switches it back on automatically. An account you switched off yourself in Apinizer is never touched by synchronization.

Advanced Settings - Group Object Class Definition

An image containing Group Object Class Definition settings from advanced settings in connection settings for user verification with LDAP is shown below:

The fields used for Group Object Class Definition from advanced settings in connection settings for user verification with LDAP are shown in the table below.

Field	Description
Group Object Class Name (Group Object Class Name)	The class name to be used to filter groups is entered. Default value: groupOfUniqueNames
Custom Filter Attribute (Custom Filter Attribute)	Filter value that can be used in addition to the filter in the connection when retrieving groups.
Group Base DN Attribute (Group Base DN Attribute)	If there is a value in this field, this Base DN is used when searching and loading groups instead of the Base DN in the connection. If no value is provided, the Base DN in the connection becomes valid.
Search Scope (Search Scope)	Specifies at what level the search operation will be performed on the base DN.
Group Name Attribute (Group Name Attribute)	The name of the attribute that holds the group name is entered.
Member Attribute (Member Attribute)	The name of the attribute that holds group members is entered.
Member Strategy (Member Strategy)	The method to be used to determine group members is selected. Default value: USER DN Values it can take: • USER DN • USER LOGIN This field only appears when How is membership determined? below is left at Current behaviour (default). In every other mode the member value's format is detected automatically.
How is membership determined? (Membership Source)	Decides how a user is attached to an organization. Options: Current behaviour (default) — nothing changes, memberships keep being read the way this installation reads them today; Find automatically (recommended) — the membership attribute on the user and the member list on the group are tried first, and if both come back empty, the organizational unit the user is in is used; Memberships are listed on the user (for example memberOf); Members are listed on the group (for example member); Our groups are OUs; a user belongs to the OU it is in; Both OU and group — the organization comes from the OU the user is in, while roles come from every membership list. If you are not sure, leave this as it is or choose Find automatically. Changing it only affects how memberships are read; nothing on your directory is modified.
Additional Attributes to Read	Extra attributes to read from each group. Adding the attribute that never changes when a group is renamed or moved — objectGUID on Active Directory, entryUUID on OpenLDAP and 389 Directory Server / FreeIPA — keeps the organization, its limits, and its members attached to the same record after the move. Leave it empty to keep reading groups exactly as before.

Testing the Connection Step by Step

Click [Test connection (step by step)] at the top of the provider screen to measure the connection in 12 separate steps before you save. Each step reports its own result, so you can see exactly where a problem breaks down. The older, single-result Test Configuration flow is still available too.

#	Step	What it checks
1	Configuration Check	Consistency of the form fields (address format, TLS options, required fields)
2	Server Connection	Whether the LDAP server can be reached over the network
3	Secure Connection (TLS)	The LDAPS/StartTLS handshake
4	Service Account Sign-in	Signing in with the service account configured on the connection
5	Directory Information	The directory type and tree roots the server reports about itself
6	Schema Check	Whether the configured object classes and attribute names exist in the directory schema
7	Base DN Read	Whether the root the searches start from is readable
8	User Search	Whether the configured user filter returns at least one record
9	Group Search	Whether the configured group filter returns at least one record
10	Attribute Permissions	Whether the service account can see all of the requested attributes
11	Membership Resolution	Whether the sampled users resolve to an organization under the configured membership mode
12	Paged Search Support	Whether the server can return large result sets page by page

Each row shows a status badge next to an explanation, a suggestion, and a copyable technical detail. When an attribute is not defined in the directory's schema, or the service account cannot see it, the matching step reports that on its own.

Directory Preview

Click [Directory Preview] to read the directory with the values currently on the form and see what synchronization would produce, without writing anything.

The preview has four tabs:

• Users: username, full name, e-mail, distinguished name, the organization the user would be linked to, the source of that link, and the raw attributes read.
• Groups: name, distinguished name, type (group or organizational unit), member count, and the format of its member values.
• Membership: each user next to the groups or organizational units it resolves to, with a filter to show only users that are not linked.
• Issues: configuration problems found while reading the preview (see below).

Click [Full scan (dry run)] to scan the whole directory with paging and see a report of what synchronization would change — records that would be created, updated, deactivated, or left without an organization — while still writing nothing.

Issues

Code	Meaning	What to do
I01	None of the users read carry the configured membership attribute.	On Active Directory this attribute is usually memberOf. If your directory does not publish group membership on the user entry at all, switch How is membership determined? to a mode that uses group member lists or the organizational unit tree instead.
I02	Group member values are in a different format than the configured strategy expects, so the reverse lookup can never match.	Switch How is membership determined? to Find automatically so the format of each member value is detected on its own.
I03	Some of the groups read are organizational units and carry no member list.	In this layout a user belongs to the organizational unit it is placed under. Set How is membership determined? accordingly.
I04	None of the member values match any of the users read.	The user search root and the groups are probably looking at different parts of the tree, or the user name attribute does not match the format used in the member values.
I05	The group search returned no records for the configured object class.	Check the group object class and the group search root. If your groups are organizational units, use organizationalUnit.
I06	The server does not support paged search results.	Synchronization can only read the first page, so some users will be missing and records will not be reconciled correctly. Enable paged results on the directory server.
I07	The login name attribute is empty on some of the users read.	The user name is taken from this attribute. On Active Directory it is usually sAMAccountName.
I08	The directory returned a referral during the search.	Some records may live on another server and are not read. Consider pointing the connection at a server that holds the whole tree.
I09	On Active Directory the primary group of a user is not listed on the user entry.	This is normal. A user that appears to be missing from a group such as Domain Users is affected by this.
I10	A member value points to another group (nested group).	Nested groups are detected but not resolved yet: members of the inner group are not treated as members of the outer one.
I11	The stable-identity attribute is not in the list of attributes to read.	Without it, a renamed or moved user is treated as a new person: the old record is deactivated and a new one is created, so the organization and limit links are lost. Add objectGUID (Active Directory) or entryUUID (OpenLDAP, 389 Directory Server / FreeIPA).
I12	Configured attributes are not defined in the directory schema.	The server silently ignores an attribute it does not know. Check the spelling and whether the attribute belongs to a different directory product.
I13	Requested attributes came back empty on every user read.	The service account is probably not allowed to see them. Check the access rights of the account used to connect.

Where a fix is available, an [Apply] button writes the suggestion to the form; review it and save.

Explain

Explain answers "why is this user's group empty?" for a single account. Enter a user name — and, optionally, a password to also attempt a sign-in — and click [Explain] to see, step by step:

• whether the user was found in the directory, and with which search filter,
• the raw attributes read from the user entry (as far as the service account can see them),
• how each of the three membership sources (user attribute, group member list, organizational unit tree) resolves for this user, with the filter used and the result,
• the final result used, and the organization it produces,
• a simulation of what would happen if this user signed in to the management console (which projects it would be a member of),
• a simulation of what would happen if this user called an API as a consumer (whether a matching consumer exists, its organization, and its active limit assignments),
• the account status, when an Account State Attribute is configured.

Passwords entered for the sign-in attempt are never stored or displayed.

How This Provider Works

A flow strip at the top of the provider screen summarizes the six stages this provider goes through, and clicking a stage jumps to the matching section of the form:

Connect (which server and connection) → Bind (which account authenticates) → Users (where users are searched and which attributes are read) → Groups (which group/OU entries are read) → Membership (how a user is attached to an organization) → Synchronization (schedule, scope, and the last run).

Synchronization

Using the LDAP Synchronization Profile tab on the LDAP edit screen, you can synchronize users from this source (and the related organization tree) into Credential records. For field descriptions, scheduling, and monitoring, see Credential Sync.

The provider and view screens carry a Synchronization section with an Enabled/Disabled badge, a [Synchronize Now] button, and a run-mode choice: Full, Users only, or Groups only. A [Refresh] button reloads the last-run summary without triggering a new run.

The last-run summary shows: users read, users carrying the membership attribute, groups read, groups with members, groups filtered out by the synchronization scope, users linked from the user attribute, from a group member list, or from the organizational unit tree, users that could not be linked to any organization, and users automatically re-enabled because they came back in the source. A [View issues] link opens the run's recorded issues. The same counters appear as columns of the Synchronization History table on the Credential Sync screen, shown as - for runs recorded before this counter set existed.

The Synchronization screen also carries a Support bundle action next to this source's row. It downloads an anonymized diagnostic archive — directory names, user names, and e-mail addresses are replaced by hashes, and no password is included. To have the LDAP operation log inside it, turn on Diagnostic Mode on the connection, reproduce the problem, then download the bundle.

Synchronization Scope

The Matched Field options for filtering which records are synchronized carry worked examples:

Matched Field	Example
Username	svc-*
E-mail	*@example.com
Path (DN / group path)	/Groups/* — the DN is read right to left, written as /Eng/Dev, and dc= components are dropped
Name	developers

A Try a pattern box evaluates a sample value against the current patterns without saving anything and without querying the directory.

Group and organization scope filters are enforced during synchronization: a group excluded by the filter is not created as an organization, and an existing organization that falls out of scope is not deleted or deactivated — it is left untouched. A plain literal pattern (no * or ?) is no longer incorrectly rejected as an unsafe pattern during synchronization.

Synchronization Behaviors

• A consumer that synchronization previously deactivated, and that later reappears in the source, is automatically re-enabled. A consumer you deactivated by hand is never touched by synchronization.
• When a user belongs to more than one in-scope group or OU, only one organization is linked — the deepest one. See How the Organization Link Is Determined for the full winner rule and the exceptions to the every-run rewrite.
• If the source directory carries two entries with the same login name, the second one is skipped and recorded as an issue; the first one is kept.
• If an organization with the same distinguished name already exists as a manually created record, synchronization does not create a duplicate organization — it links users to the existing one and records an issue, leaving the organization under manual management until you hand it over.
• If the synchronization schedule cannot be registered — for example an invalid cron expression — the error is shown immediately when you save, instead of only failing silently on the next scheduled run.
• A run that fails, or in which users could not be attached to an organization, produces an issue you can review from [View issues].

If two different LDAP sources contain the same directory entry (the same DN), synchronization from one source does not update the other source's organization record — each source's organization record belongs to that source alone, so a group present in both directories is kept and reconciled separately per source.

Paged results

During synchronization Apinizer reads the directory page by page using the LDAP PagedResults control (500 entries per page). If the directory server does not support that control — or does not allow it to be used — only the first page can be read. The run is then reported as Warning and, as a safety measure, no credential is deactivated or deleted; the records that were read are upserted normally. The same safety measure applies when even a single record read from the directory cannot be converted: the run counts as incomplete and deactivation/deletion is skipped. For a full synchronization, enable paged result support on the directory server or raise its server-side size limit.

Even when the directory server appears to support paged results, the same safety measure applies if paging stalls or repeats — the run is still treated as incomplete and deactivation/deletion is still skipped.

A directory that refuses the search is reported differently. If the configured base DN does not exist, or the bind account may not search under it, the run ends as Failed with a reason naming that base DN — not as a Warning about an incomplete read. Both are settings an administrator can correct, so they are kept distinct from a server that simply refuses paging.

Troubleshooting

Users and groups come in, but the user-to-organization/group link is empty

1. Open Explain and enter the affected user name. It shows which of the three membership sources found a match and which did not.
2. Open Directory Preview and check the Issues tab — I01, I02, I03, and I04 all describe variants of this problem, each with its own fix.
3. Check How is membership determined? in the Group Object Class Definition. On Active Directory, the usual choice is the mode that reads the membership attribute (memberOf). When groups are organizational units, choose Our groups are OUs; a user belongs to the OU it is in.
4. Turn on Diagnostic Mode on the connection to log every search made, and read the log while reproducing the problem.
5. If the problem needs support, download a Support bundle from the Synchronization screen.

Compatibility

Directory	Status
Active Directory 2012 R2 – 2025, including Samba AD	Tested
OpenLDAP 2.4 – 2.6 (the memberOf overlay is optional)	Tested
389 Directory Server / FreeIPA	Expected to work with the matching preset
Other LDAP-compatible directories	Fill the fields by hand, or apply the closest matching preset above. Then verify with Directory Preview and Test Connection

Backward Compatibility

Existing providers keep working exactly as before: How is membership determined? stays at Current behaviour (default) for them, and organization assignments do not change. The new membership modes apply only when you choose one yourself. During a rolling upgrade where the API Manager is upgraded before the gateway workers, the workers keep resolving membership the old way until they are redeployed.