The LDAP Resource Adaptor lets you connect from a Rhino SLEE to LDAP servers and send client requests in order to perform protocol operations to add and delete, search and retrieve, or alter directory entries, or test the validity of credentials to bind to a directory.
Features of the LDAP Resource Adaptor include:
-
Asynchronous query API — exposes an resource adaptor type that provides an asynchronous API, in an OpenCloud namespace
-
Graceful connection establishment — provides "graceful" connections to LDAP servers
-
LDAP queries — lets you use the API to perform LDAP operations, including Add, Compare, Delete, Modify, Modify DN and Search
-
LDAP bind queries — lets you use the API to perform LDAP Bind operations with given credentials (test credentials validity)
-
LDAP server groups — supports sets of LDAP servers for load balancing and failover.
Topics
how to configure the resource adaptor using properties |
|
how to monitor LDAP resource adaptor statistics |
Other documentation for the LDAP Resource Adaptor can be found on the LDAP Resource Adaptor product page.
Configuring the LDAP Resource Adaptor
Below are details of configuring deployment descriptor properties, secure communication, and active reconfiguration.
Resource adaptor configuration properties
The LDAP resource adaptor has the following configuration properties:
Name | Type | Default | Description | Active reconfig? |
---|---|---|---|---|
User |
String |
|
LDAP user to use for each connection, can be empty for anonymous connections |
No |
Password |
String |
|
LDAP password to use for each connection, can be empty; also see |
No |
Host |
String |
|
LDAP server groups information to use for the connections |
No |
ConnectionTimeout |
Integer |
5000 |
how long, in milliseconds, the resource adaptor should wait when trying to establish a TCP connection with a remote peer |
Yes |
QueryTimeout |
Long |
2000 |
timeout, in milliseconds, for a specific query (any further results sent by the server won’t be processed for the query) |
Yes |
SearchTimeLimit |
Integer |
0 |
maximum time, in seconds, that the server should spend processing a specific search query |
Yes |
MinConnections |
Integer |
10 |
how few TCP connections the resource adaptor will hold open in the connection pool (assuming the LDAP servers are reachable); |
Yes |
MaxConnections |
Integer |
20 |
how many TCP connections the resource adaptor will hold open in the connection pool |
Yes |
BindMinConnections |
Integer |
0 |
how few TCP connections the resource adaptor will hold open in the bind connection pool (assuming the LDAP servers are reachable); |
Yes |
BindMaxConnections |
Integer |
0 |
how many TCP connections the resource adaptor will hold open in the bind connection pool |
Yes |
BindMaxFailoverConnectionAge |
Integer |
0 |
how long, in milliseconds, a connection to a backup server can exist in the bind connection pool before it is closed in order to try the primary server(s) again. |
Yes |
MaxFailoverConnectionAge |
Integer |
0 |
how long, in milliseconds, a connection to a backup server can exist in the connection pool before it is closed in order to try the primary server(s) again. |
Yes |
MaxQueueSize |
Integer |
(MaxConnections +BindMaxConnections) *3 |
how many queued queries will wait for a thread pool thread before they execute |
No |
MaxQueueTime |
Integer |
5000 |
how long, in milliseconds, a query will wait in the queue before it executes |
Yes |
PollInterval |
Integer |
5000 |
time, in milliseconds, between polls on a new connection in the connection pool to an LDAP server |
Yes |
PollCount |
Integer |
2 |
how many successful polls before sending regular queries to the LDAP server |
Yes |
PollDN |
String |
null |
LDAP DN to use for poll queries |
Yes |
PollSearchFilter |
String |
(objectclass=*) |
the LDAP search filter to use for poll queries (see |
Yes |
PollSearchScope |
String |
base |
LDAP search scope; must be one of |
Yes |
PollSuccessResultCodes |
String |
null |
comma-separated list of result codes that should not be treated as poll failures |
Yes |
IdleTimeout |
Integer |
0 |
how long, in milliseconds, to wait before closing idle connections in the connection pool |
Yes |
MaxQueriesPerConnection |
Integer |
0 |
how many queries a specific TCP connection in the connection pool can have before it closes |
Yes |
BindMaxConnectionAge |
Integer |
0 |
how long, in milliseconds, a specific TCP connection can stay open in the bind connection pool before it is automatically closed |
Yes |
AbandonOnTimeout |
Boolean |
false |
whether the resource adaptor should send an abandon request to any query for which no result is received in the query timeout period, specified by |
Yes |
MaxMessageSize |
Integer |
20971520 |
maximum allowed message size, in bytes, for messages read from the server; |
Yes |
ReceiveBufferSize |
Integer |
0 |
socket receive buffer size requested when establishing a connection to the server |
Yes |
SendBufferSize |
Integer |
0 |
socket send buffer size requested when establishing a connection to the server |
Yes |
UseSchema |
Boolean |
false |
whether connections should try to retrieve schema information from the server, which may be used to select the appropriate matching rules when comparing attribute values for the attributes included in a search result entry |
Yes |
AllowUnauthenticatedBind |
Boolean |
false |
whether to allow sending bind queries with a non-empty DN and empty password (that is, the unauthenticated authentication mechanism of the simple Bind method) |
Yes |
BindHealthCheckInterval |
Integer |
60000 |
time, in milliseconds, between periodic health checks against the connections available in the bind pool (determine whether connections are valid and suitable for use) |
Yes |
BindCheckConnectionAgeOnRelease |
Boolean |
true |
whether to check the age of a connection against the configured maximum connection age, specified by |
Yes |
Configuring secure communication (SSL/TLS or StartTLS)
The resource adaptor supports the use of SSL/TLS and StartTLS for secure communication. TLS should be used to create connections that are always secure (and will generally use a different port from that used for LDAP communication, typically port 636
). StartTLS establishes insecure connection and later adds security using the StartTLS extended operation (and will communicate over the same port used for insecure LDAP communication, typically port 389
).
The following LDAP resource adaptor configuration properties configure secure connection:
Name | Type | Default | Description | Active reconfig? | ||
---|---|---|---|---|---|---|
TransportSecurity |
String |
None |
enable/disable secure transport connection
|
No |
||
CertificateKeyStore |
String |
|
path to JKS key store file to load certificate key from
|
No |
||
CertificateKeyStorePassword |
String |
|
password for certificate key store |
No |
||
TrustKeyStore |
String |
|
path to JKS key store for trust certificates
|
No |
||
TrustKeyStorePassword |
String |
|
password for trust key store |
No |
||
CipherSuites |
String |
|
comma-separated list of TLS cipher suites to be enabled for use when establishing TLS handshake
|
No |
||
SSLSessionTimeout |
Integer |
0 |
time, in seconds, after which TLS session should be invalidated and new session will be established (cipher keys change) |
No |
Key stores
For information about creating a key store, please see the Java Virtual Machine vendor documentation: Oracle keytool documentation and Oracle general information about TLS support in the JSSE Reference Guide.
Active reconfiguration
The resource adaptor supports active reconfiguration. This means that (most) configuration properties can be updated without deactivating and re-activating the resource adaptor entity. If a property cannot be updated at runtime, then an alarm is raised indicating that the entity must be deactivated and re-activated. The table above indicates which properties allow active reconfiguration.
Graceful Connection Establishment
Graceful connection establishment is a feature that provides "graceful" connections to LDAP servers, which must successfully respond to N "poll" query operations (read-only queries on specific DNs), before being used for requests. This prevents an LDAP server from being swamped with requests immediately after it (re)starts and begins accepting connections.
The graceful connection establishment feature is only for regular LDAP queries, not for LDAP bind queries. It can be configured using the resource adaptor configuration properties ( |
LDAP Bind Queries
LDAP bind queries are a feature of the resource adaptor that allow sending of independent bind request(s) to configured servers (LDAP server groups), and retrieving results in order to test the validity of passed credentials binding to the directory.
The LDAP bind queries feature uses a dedicated connection pool ( It must be enabled using the resource adaptor configuration properties ( |
LDAP Server Groups
LDAP server groups are sets of servers where one is a primary server, and the rest are backup servers.
Within a server group, queries go to the primary server if it is available, then to the backup server(s).
Note that following the failure of the preferred server(s), there is a configurable delay before the LDAP RA will attempt to use them again. See the BindMaxFailoverConnectionAge
and MaxFailoverConnectionAge
configuration properties.
Across multiple server groups, the resource adaptor balances the load evenly.
You specify all LDAP server groups in a single string. Servers for a group are separated by whitespace, server groups are separated by commas.
Each server may optionally include a port number to use instead of the default LDAP port (389
).
For example:
Server group configuration | What it specifies |
---|---|
server1:389 |
1 group of 1 server |
server1:389,server2:589 |
2 groups of 1 server each |
server1 server2,server3 |
2 groups, 1 with a backup server ( |
Monitoring Resource Adaptor Statistics
The LDAP Resource Adaptor creates several statistic parameter sets that can be monitored using the Rhino Stats tool.
Statistics parameter sets
The root parameter set is named LDAP-RA
.entity-name
and has three child parameter sets:
The LDAPStats
parameter set has statistics that are specific to all LDAP query types except LDAP bind queries, while the LDAPBindStats
parameter set has statistics that are specific to LDAP bind queries exclusively. The LDAPWorkerPoolStats
parameter set contains statistics specific to the worker pool of the LDAP resource adaptor.
A list of statistics with descriptions for each of these parameters sets can be displayed with therhino-stats -l command, as shown below. |
LDAPStats
parameter set
Parameter Set: LDAP-RA.ldap.LDAPStats Parameter Set Type: ResourceAdaptorID[name=LDAP,vendor=OpenCloud,version=3.1].LDAPStats Description: Statistics for all query types except bind queries of the LDAP RA Counter type statistics: Id: Name: Label: Description: 0 queries queries Number of LDAP queries started by the RA 1 successfulQueries success Number of successful LDAP queries 2 failedQueries failed Number of failed LDAP queries 3 activeConnections connections Current number of active connections to the LDAP server 4 replacedConnections replaced Number of LDAP pool connections replaced Sample type statistics: Id: Name: Label: Description: 4 connWaitTime connwait Time spent obtaining an LDAP connection from the pool 5 queryTime querytime Time spent waiting for the query response
LDAPBindStats
parameter set
Parameter Set: LDAP-RA.ldap.LDAPBindStats Parameter Set Type: ResourceAdaptorID[name=LDAP,vendor=OpenCloud,version=3.1].LDAPBindStats Description: Statistics for bind queries of the LDAP RA Counter type statistics: Id: Name: Label: Description: 0 queries queries Number of LDAP bind queries started by the RA 1 successfulQueries success Number of successful LDAP bind queries 2 failedQueries failed Number of failed LDAP bind queries Sample type statistics: Id: Name: Label: Description: 3 queryTime querytime Time spent waiting for the bind query response
LDAPWorkerPoolStats
parameter set
Parameter Set: LDAP-RA.ldap.LDAPWorkerPoolStats Parameter Set Type: ResourceAdaptorID[name=LDAP,vendor=OpenCloud,version=3.0].LDAPWorkerPoolStats Description: Statistics for thread worker pool of the LDAP RA Counter type statistics: Id: Name: Label: Description: 0 availableThreads availThrd Current number of threads available to perform queries 1 rejectedQueries reject Number of tasks that were rejected because the queue was full 2 queueSize qsize Current number of queued tasks waiting to be executed 3 queueTimeouts timeouts Number of tasks that timed out waiting on the queue Sample type statistics: Id: Name: Label: Description: 4 queueWaitTime qwait Time spent by tasks waiting in the queue