LDAP configuration parameters¶

Percona Server for MongoDB provides a set of configuration parameters to enable and fine-tune LDAP authentication and authorization.

UsertoDN cache parameters¶

To reduce the number of round trips to the LDAP server during authentication and authorization, Percona Server for MongoDB caches the results of LDAP UsertoDN mapping configured by security.ldap.userToDNMapping (exposed as --ldapUserToDNMapping at startup and ldapUserToDNMapping at runtime).

For more details on configuring UsertoDN mapping, see LDAP authorization and Set up LDAP authentication and authorization using NativeLDAP.

The cache is controlled by the following server parameters:

Parameter	Required	Description
`ldapUserToDNCacheTTLSeconds`	No	Specifies how long (in seconds) a cache entry remains valid. Default: `30`. Set to `0` to disable caching.
`ldapUserToDNCacheSize`	No	Defines the maximum number of entries stored in the cache. Default: `10000`. Set to `0` to disable caching.

Note

Both parameters can be set at startup and at runtime using setParameter.

Cache invalidation parameters

The cache is automatically invalidated when any of the following parameters change at runtime:

Parameter	Required	Description
`ldapUserToDNMapping`	Yes	Rules for mapping usernames to LDAP DNs.
`ldapUserToDNCacheTTLSeconds`	No	Changing the TTL value clears the cache.
`ldapUserToDNCacheSize`	No	Changing the cache size clears the cache.
`ldapServers`	Yes	Comma-separated list of LDAP servers to connect to.

Connection pool parameters¶

These parameters control how Percona Server for MongoDB maintains its pool of connections to the LDAP server.

Important

All connection pool parameters are startup-only. They must be defined in the configuration file or via --setParameter at launch and cannot be changed via db.adminCommand() while the instance is running.

Parameter	Required	Description
`ldapUseConnectionPool`	No	Enables/disables connection pooling. Default is OS dependent: `true` on Windows and specific Linux builds using `libldap_r`.
`ldapConnectionPoolHostRefreshIntervalMillis`	No	Frequency (in ms) of health checks for pooled connections. Default: `60000`.
`ldapConnectionPoolIdleHostTimeoutSecs`	No	Seconds a pooled connection can remain idle before being closed. Default: `300`.
`ldapConnectionPoolMinimumConnectionsPerHost`	No	Minimum number of connections to maintain per LDAP host. Default: `1`.
`ldapConnectionPoolMaximumConnectionsPerHost`	No	Maximum number of open connections per LDAP host. Default: `2147483647`.
`ldapConnectionPoolMaximumConnectionsInProgressPerHost`	No	Limits concurrent in-progress connection attempts per host to prevent spikes. Default: `2`.
`ldapConnectionPoolUseLatencyForHostPriority`	No	When `true`, the pool prioritizes connections to hosts with the lowest latency. Default: `true`.

MongoDB configuration file (LDAP section)

security:
  authorization: enabled
  ldap:
    mode: authzAndAuthn
setParameter:
  # --- Connection Pool Settings (Startup Only) ---
  ldapUseConnectionPool: true
  ldapForceMultiThreadMode: true
  ldapConnectionPoolMinimumConnectionsPerHost: 5
  ldapConnectionPoolMaximumConnectionsPerHost: 100
  ldapConnectionPoolIdleHostTimeoutSecs: 600

LDAP cache refresh parameters¶

As of version 8.0.20-8, Percona Server for MongoDB introduced parameters to optimize authentication performance and reduce unnecessary load on the LDAP server. These settings control how cached user information is refreshed, allowing administrators to fine-tune the balance between maintaining up-to-date user data and minimizing LDAP query overhead—especially in high-scale environments with many concurrent users.

Parameter	Required	Description
`ldapUserCacheRefreshInterval`	No	Defines how often (in seconds) the server refreshes cached user information from LDAP when interval-based refresh is enabled through `ldapShouldRefreshUserCacheEntries=true`. If not explicitly configured, Percona Server for MongoDB uses the built-in default for the server version. Can be configured at startup and runtime.
`ldapShouldRefreshUserCacheEntries`	No	Selects the LDAP user cache refresh strategy. - When set to `true`, each cached `$external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. - When set to `false`, all `$external` users are evicted from the cache at intervals defined by `ldapUserCacheInvalidationInterval`. This preserves the behavior that existed prior to the introduction of `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries`. Default: `false` (expiration-based invalidation using `ldapUserCacheInvalidationInterval`) to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. The default value will change to `true` in future major versions. This parameter can be configured at startup only.
`ldapUserCacheInvalidationInterval`	No	Defines the interval between total external user cache flushes, in seconds. Cached LDAP user entries are evicted after this interval and are re-acquired from LDAP on the next operation. Default: `30` seconds. This parameter can be configured at startup and runtime.
`ldapUserCacheStalenessInterval`	No	Defines how long `mongod` retains cached LDAP user information after a failed refresh attempt before invalidating the cache entry, in seconds. Maximum allowed value: `86400` seconds. Default: `30` seconds. This parameter can be configured at startup and runtime.

Interval-based refresh: ldapShouldRefreshUserCacheEntries: true

Runtime (setParameter)Command lineConfiguration file

> db.adminCommand({
...   setParameter: 1,
...   ldapUserCacheRefreshInterval: 300
... })

mongod --setParameter "ldapUserCacheRefreshInterval=300" \
        --setParameter "ldapShouldRefreshUserCacheEntries=true"

setParameter:
  ldapUserCacheRefreshInterval: 300
  ldapShouldRefreshUserCacheEntries: true

Expiration-based invalidation: ldapShouldRefreshUserCacheEntries: false

Runtime (setParameter)Command lineConfiguration file

> db.adminCommand({
...   setParameter: 1,
...   ldapUserCacheInvalidationInterval: 30
... })

mongod --setParameter "ldapUserCacheInvalidationInterval=30" \
        --setParameter "ldapShouldRefreshUserCacheEntries=false"

setParameter:
  ldapUserCacheInvalidationInterval: 30
  ldapShouldRefreshUserCacheEntries: false

Security and concurrency parameters¶

These parameters are used for LDAP server authentication, secure connection handling, and ensuring thread-safe operations during concurrent access.

Parameter	Required	Description
`ldapQueryUser`	No	Specifies the DN (Distinguished Name) of the user that binds to the LDAP server. Default: `N/A`.
`ldapQueryPassword`	No	Specifies the password for `ldapQueryUser`. Default: `N/A`.
`ldapForceMultiThreadMode`	No	Enables concurrent LDAP operations. Required for connection pooling. Use only with a thread-safe `libldap` implementation. Default: `false`.
`ldapRetryCount`	No	Specifies the number of times the server retries an LDAP operation after a network error. Default: `0`.

MongoDB configuration file: Performance and retries

security:
  authorization: enabled
  ldap:
    mode: authzAndAuthn
# --- Performance & Retries ---
setParameter:
  ldapRetryCount: 3