← Back to plugin index

LDAP Connection Pool
Description
LDAP server connection pool supporting failover with multiple servers and secure connections using LDAP over SSL or the START_TLS extended operation.

The plugin makes use of the UnboundID LDAP SDK.

Note: If several plugins share the same main connection settings (server addresses with ports, bind DN, SSL settings) they also share one single connection pool.

Connection Pooling

This plugin manages a pool of open connections to the LDAP server. To perform an operation a connection is checked out of the pool, then used for the operation and afterward checked into the pool of available connections again.

There are several configuration properties that influence how these connections are managed and how connection errors are handled.

To debug the LDAP connections set the following Java system properties:

  • com.unboundid.ldap.sdk.debug.enabled=true - If set to true, LDAP debugging is enabled.
  • com.unboundid.ldap.sdk.debug.type=asn1,connect,exception,ldap,ldif,monitor,coding-error,other - If set, only the given categories will be logged.
  • com.unboundid.ldap.sdk.debug.includeStackTrace=true - If set to true, a stack trace will be included with every log message.
  • com.unboundid.ldap.sdk.debug.level=ALL - If set, only messages with a level higher than specified (like ALL, FINE, INFO, WARNING, ...) will be written.
  • javax.net.debug=all - Set this property to diagnose SSL related issues.
Type name
LdapConnectionPool
Class
com.airlock.iam.core.misc.util.ldap.LdapConnectionPool
May be used by
LDAP Credential Persister Active Directory Connector LDAP Connector Active Directory Password Policy Connector LDAP Token List Persister LDAP User Persister LDAP Password Authenticator
Properties
Servers With Ports (serversWithPorts)
Description
List of server names with ports in the form of: server-name:port . If no port number is specified, the default port 389 (or 636 if using SSL) is assumed.
Attributes
String-List
Mandatory
Server Selection Policy (serverSelectionPolicy)
Description
Which policy to use if more than one server is configured, one of FAILOVER or ROUND_ROBIN.
  • FAILOVER: Always try to get a connection from the first server, if that fails from the second, etc...
  • ROUND_ROBIN: Cycle through the configured servers to get connections.
Attributes
Enum
Optional
Default value
FAILOVER
Service Account Username (bindDn)
Description
The bind DN (distinguished name) to bind to the LDAP server.
Attributes
String
Optional
Example
CN=MedusaUser,CN=users,dc=exchangeserver,dc=company,dc=com
Service Account Password (password)
Description
The password to bind to the LDAP server for searching and modifying users.
Attributes
String
Optional
Sensitive
Anonymous Bind (anonymousBind)
Description
Enable this property to allow anonymous binds. An anonymous bind allows users to connect to the Directory Server without supplying any username or password. This simplifies common search and read operations, like checking the directory for a phone number or email address, by not requiring users to authenticate to the directory first. However, there are risks with anonymous binds. If no authentication is enforced, sensitive data like user data might be accessible for unauthenticated or unauthorized users because the access to the Directory Server is not protected. Only set this property to true if it is absolutely necessary and you are aware of the resulting security implications.
Attributes
Boolean
Optional
Default value
false
Connection Security (connectionSecurity)
Description

The type of connection security, one of NONE, START_TLS or SSL.

Notice: Most directories will refuse to perform a password change operation if the connection is not secured using SSL/TLS.

Notice: Microsoft disabled support for Server certificates using MD5 with KB2862973 (mandatory update in early 2014). Using any server certificate with an MD5 signature in its entire chain will result in a connection error. The same error will be raised when using a certificate using SHA-512 without having KB2973337 installed.

Attributes
Enum
Optional
Default value
NONE
Keystore File (keystoreFile)
Description
The file name of the Java keystore used for SSL operations. It must contain the private key for client authentication. This is only used if SSL is enabled.
Note: If the keystore file name is relative, it is loaded relative to the current directory of the JVM process.
Attributes
File/Path
Optional
Keystore Password (keystorePassword)
Description
The password used to read the keystore and the private key also. This is only used if SSL is enabled.
Attributes
String
Optional
Sensitive
Key Alias (keyAlias)
Description
The alias of the private key for SSL client authentication. This is only used if SSL is enabled and if the server enforces SSL client authentication. If only the server certificate should be checked, please leave this property empty.
Attributes
String
Optional
Example
airlock
Check Certificate Server Name (checkCertificateServerName)
Description
Tells if the server name should be checked against the name in the certificate.
Attributes
Boolean
Optional
Default value
true
Check Certificate Validity (checkCertificateValidity)
Description
Tells if the server certificate validity dates should be respected.
Attributes
Boolean
Optional
Default value
true
Trust All Server Certificates (trustAllServerCertificates)
Description
Tells if all server certificates should be trusted. Note: Only enable this flag for testing.
Attributes
Boolean
Optional
Default value
false
Truststore File (truststoreFile)
Description
The file name of the Java truststore used for SSL operations. It must contain the trusted server CA certs. This is only used if SSL is enabled and "Trust All Server Certificates" is not active.
Note: If the file name is relative, it is loaded relative to the current directory of the JVM process.
Attributes
File/Path
Optional
Truststore Password (truststorePassword)
Description
The password used to read the truststore. Can be left empty if the truststore does not require any password. This is only used if SSL is enabled.
Attributes
String
Optional
Sensitive
Use Synchronous Mode (useSynchronousMode)
Description
Specifies whether to operate in synchronous mode, in which at most one operation may be in progress at any time on a given connection.
Attributes
Boolean
Optional
Default value
true
Follow Referrals (followReferrals)
Description
Tells if automatic referral following should be enabled.
Attributes
Boolean
Optional
Default value
false
Connection Timeout [ms] (connectTimeoutInMs)
Description
How long to wait for a connection to be established.
Attributes
Integer
Optional
Default value
2000
Response Timeout [ms] (responseTimeoutInMs)
Description
How long to wait for the server response on a protocol level.
This timeout may be reached if the connection has been dropped by a firewall without actively terminating the connection or when a query requires a lot of time on the server.
Attributes
Integer
Optional
Default value
20000
Initial Connections (initialConnections)
Description
How many connections should be opened initially.
Attributes
Integer
Optional
Default value
10
Maximum Connections (maximumConnections)
Description
Maximum number of open connections.
Attributes
Integer
Optional
Default value
100
Create New Connections If Necessary (createNewConnectionsIfNecessary)
Description
When a connection is requested but the pool has used up all free connections, it first waits for up to "Max Wait Time In Ms" for a connection to become available. If still no connection is available and this setting is enabled, a new connection is created; otherwise an exception is thrown.
Attributes
Boolean
Optional
Default value
false
Max Wait Time For Connection [ms] (maxWaitTimeInMs)
Description
Maximum time to wait until an existing, valid connection can be obtained from the pool. After that, either a new one is created (if "Create New Connections If Necessary" is enabled) or else an exception is thrown. Specify 0 to indicate not to wait at all in case of no available connection.
Attributes
Long
Optional
Default value
5000
Max Connection Age [ms] (maxConnectionAgeInMs)
Description
Maximum age of held open LDAP connections in millis. Any connection older will not be reused. Set to 0 for no limit if the LDAP server (and possible firewalls inbetween) support this. If set to unlimited, it is recommended to enable the background health check.
Attributes
Long
Optional
Default value
3600000
Try Synchronous Read During Health Check (trySynchronousReadDuringHealthCheck)
Description
Specifies whether health check processing for connections operating in synchronous mode should include attempting to perform a read from each connection with a very short timeout.
Attributes
Boolean
Optional
Default value
false
Health Check Response Timeout [ms] (healthCheckResponseTimeoutInMs)
Description
How long to wait for the server response when doing a connection health check.
Attributes
Long
Optional
Default value
30000
Retry Upon Invalid Connection Error (retryUponInvalidConnectionError)
Description
If an operation fails because the current connection is invalid, checkout a new connection from the pool and try again.
Attributes
Boolean
Optional
Default value
true
Enable Health Check On Checkout (enableHealthCheckOnCheckout)
Description
Perform a health check query every time before actually using an open connection.
Attributes
Boolean
Optional
Default value
true
Enable Health Check In Background (enableHealthCheckInBackground)
Description
Perform a health check query in the background for all held connections at the configured interval. Note: by setting this property to false, socket level connection health checking is still being performed.
Attributes
Boolean
Optional
Default value
true
Enable Health Check On Exception (enableHealthCheckOnException)
Description
Perform a health check query after an LDAP exception occurred on a LDAP connection.
Attributes
Boolean
Optional
Default value
false
Enable Health Check On Create (enableHealthCheckOnCreate)
Description
Perform a health check query when creating a new LDAP connection.
Attributes
Boolean
Optional
Default value
false
Enable Health Check On Release (enableHealthCheckOnRelease)
Description
Perform a health check query when putting an open LDAP connection back to the pool.
Attributes
Boolean
Optional
Default value
false
Background Health Check Interval [ms] (backgroundHealthCheckIntervalInMs)
Description
Interval in milliseconds between performing the configured LDAP connection health checks on open LDAP connections held by the pool. Note: socket level health checking can not be disabled.
Attributes
Long
Optional
Default value
60000
Health Check Query Dn (healthCheckQueryDn)
Description
DN that should be queried for in a LDAP health check query. If empty it's the root DSE.
Attributes
String
Optional
Use Schema (useSchema)
Description
Specifies whether to try to use schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).
Attributes
Boolean
Optional
Default value
false
YAML Template (with default values) 

type: LdapConnectionPool
id: LdapConnectionPool-xxxxxx
displayName: 
comment: 
properties:
  anonymousBind: false
  backgroundHealthCheckIntervalInMs: 60000
  bindDn:
  checkCertificateServerName: true
  checkCertificateValidity: true
  connectTimeoutInMs: 2000
  connectionSecurity: NONE
  createNewConnectionsIfNecessary: false
  enableHealthCheckInBackground: true
  enableHealthCheckOnCheckout: true
  enableHealthCheckOnCreate: false
  enableHealthCheckOnException: false
  enableHealthCheckOnRelease: false
  followReferrals: false
  healthCheckQueryDn:
  healthCheckResponseTimeoutInMs: 30000
  initialConnections: 10
  keyAlias:
  keystoreFile:
  keystorePassword:
  maxConnectionAgeInMs: 3600000
  maxWaitTimeInMs: 5000
  maximumConnections: 100
  password:
  responseTimeoutInMs: 20000
  retryUponInvalidConnectionError: true
  serverSelectionPolicy: FAILOVER
  serversWithPorts:
  trustAllServerCertificates: false
  truststoreFile:
  truststorePassword:
  trySynchronousReadDuringHealthCheck: false
  useSchema: false
  useSynchronousMode: true