LDAP Resource Adaptor Guide

The LDAP Resource Adaptor lets you connect from a Rhino SLEE to LDAP servers, to search and retrieve directory entries, or test the validity of credentials to bind to a directory.

Features of the LDAP Resource Adaptor include:

Asynchronous query API — exposes a resource adaptor type that provides an asynchronous API, in an OpenCloud namespace
Graceful connection establishment — 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 outgoing client search requests; keeps an LDAP server from being swamped with requests immediately after it (re)starts and begins accepting connections
LDAP searches — lets you use the API to perform LDAP Search operations
LDAP bind queries — lets you use the API to perform LDAP bind operations with given credentials (test credentials validity)
LDAP server groups — supports LDAP server groups.

Topics

Configuring the LDAP Resource Adaptor

how to configure the resource adaptor using properties

Monitoring Resource Adaptor Statistics

how to monitor LDAP RA 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.

Deployment descriptor properties

To configure the LDAP RA, you declare the following properties in its deployment descriptor:

Name Type Default Description Active reconfig?

Name	Type	Default	Description	Active reconfig?
User	String		LDAP user to use for each connection	No
Password	String		LDAP password to use for each connection	No
Host	String		LDAP server group information to use for the connections	No
ConnectionTimeout	Integer	5000	how long, in milliseconds, the RA should wait when trying to establish a TCP connection with a remote peer `0` = there should be no connection timeout	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) `0` = there should be no timeout	Yes
TimeLimit	Integer	0	maximum time, in seconds, that the server should spend processing a specific query `0` = there should be no limit	Yes
SearchMinConnections	Integer	10	how few TCP connections the RA will hold open in the search connection pool (assuming the LDAP servers are reachable); connections from this pool will be used for search queries exclusively	Yes
SearchMaxConnections	Integer	20	how many TCP connections the RA will hold open in the search connection pool	Yes
BindMinConnections	Integer	0	how few TCP connections the RA will hold open in the bind connection pool (assuming the LDAP servers are reachable); connections from this pool will be used for bind queries exclusively	Yes
BindMaxConnections	Integer	0	how many TCP connections the RA will hold open in the bind connection pool `0` = no connections in the bind pool (sending bind requests is disabled in the RA)	Yes
MaxQueueSize	Integer	(SearchMaxConnections +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 search connection pool to an LDAP server (for the "graceful connection establishment" feature)	Yes
PollCount	Integer	2	how many successful polls before sending regular search queries to the LDAP server (for the "graceful connection establishment" feature)	Yes
PollDN	String	null	LDAP DN to use for poll queries (for the "graceful connection establishment" feature)	Yes
PollSearchFilter	String	(objectclass=*)	the LDAP search filter to use for poll queries (see `PollDN`)	Yes
PollSearchScope	String	base	LDAP search scope; must be one of `base`, `one`, `sub`, or `subordinate_subtree` — for a base object, one-level, subtree, or any subordinate entries (excluding base DN) search	Yes
PollSuccessResultCodes	String	null	comma-separated list of result codes that should not be treated as poll failures (for the "graceful connection establishment" feature)	Yes
SearchIdleTimeout	Integer	0	how long, in milliseconds, to wait before closing idle connections in the search connection pool `0` = do not close based on idle time	Yes
MaxSearchesPerConnection	Integer	0	how many search queries a specific TCP connection in the search connection pool can have before it closes `0` = do not close based on based on number of queries	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 `0` = do not close based on connection age	Yes
AbandonOnTimeout	Boolean	false	whether the RA should send an abandon request to any search query for which no result is received in the query timeout period, specified by `QueryTimeout` (this does not affect the query timeout behaviour)	Yes
MaxMessageSize	Integer	20971520	maximum allowed message size, in bytes, for messages read from the server; for example, `20971520` = 20MB `0` = no limit should be enforced	Yes
ReceiveBufferSize	Integer	0	socket receive buffer size requested when establishing a connection to the server `0` = automatically determine by the JVM based on the underlying system settings	Yes
SendBufferSize	Integer	0	socket send buffer size requested when establishing a connection to the server `0` = automatically determine by the JVM based on the underlying system settings	Yes
UseSchema	Boolean	false	whether to try to use schema information when reading data from the server	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

User

String

LDAP user to use for each connection

Password

String

LDAP password to use for each connection

Host

String

LDAP server group information to use for the connections

ConnectionTimeout

Integer

how long, in milliseconds, the RA should wait when trying to establish a TCP connection with a remote peer
0 = there should be no connection timeout

Yes

QueryTimeout

Long

timeout, in milliseconds, for a specific query (any further results sent by the server won’t be processed for the query)
0 = there should be no timeout

Yes

TimeLimit

Integer

maximum time, in seconds, that the server should spend processing a specific query
0 = there should be no limit

Yes

SearchMinConnections

Integer

how few TCP connections the RA will hold open in the search connection pool (assuming the LDAP servers are reachable);
connections from this pool will be used for search queries exclusively

Yes

SearchMaxConnections

Integer

how many TCP connections the RA will hold open in the search connection pool

Yes

BindMinConnections

Integer

how few TCP connections the RA will hold open in the bind connection pool (assuming the LDAP servers are reachable);
connections from this pool will be used for bind queries exclusively

Yes

BindMaxConnections

Integer

how many TCP connections the RA will hold open in the bind connection pool
0 = no connections in the bind pool (sending bind requests is disabled in the RA)

Yes

MaxQueueSize

Integer

(SearchMaxConnections +BindMaxConnections) *3

how many queued queries will wait for a thread pool thread before they execute

MaxQueueTime

Integer

how long, in milliseconds, a query will wait in the queue before it executes

Yes

PollInterval

Integer

time, in milliseconds, between polls on a new connection in the search connection pool to an LDAP server
(for the "graceful connection establishment" feature)

Yes

PollCount

Integer

how many successful polls before sending regular search queries to the LDAP server
(for the "graceful connection establishment" feature)

Yes

PollDN

String

null

LDAP DN to use for poll queries
(for the "graceful connection establishment" feature)

Yes

PollSearchFilter

String

(objectclass=*)

the LDAP search filter to use for poll queries (see PollDN)

Yes

PollSearchScope

String

base

LDAP search scope; must be one of base, one, sub, or subordinate_subtree — for a base object, one-level, subtree, or any subordinate entries (excluding base DN) search

Yes

PollSuccessResultCodes

String

null

comma-separated list of result codes that should not be treated as poll failures
(for the "graceful connection establishment" feature)

Yes

SearchIdleTimeout

Integer

how long, in milliseconds, to wait before closing idle connections in the search connection pool
0 = do not close based on idle time

Yes

MaxSearchesPerConnection

Integer

how many search queries a specific TCP connection in the search connection pool can have before it closes
0 = do not close based on based on number of queries

Yes

BindMaxConnectionAge

Integer

how long, in milliseconds, a specific TCP connection can stay open in the bind connection pool before it is automatically closed
0 = do not close based on connection age

Yes

AbandonOnTimeout

Boolean

false

whether the RA should send an abandon request to any search query for which no result is received in the query timeout period, specified by QueryTimeout (this does not affect the query timeout behaviour)

Yes

MaxMessageSize

Integer

20971520

maximum allowed message size, in bytes, for messages read from the server;
for example, 20971520 = 20MB
0 = no limit should be enforced

Yes

ReceiveBufferSize

Integer

socket receive buffer size requested when establishing a connection to the server
0 = automatically determine by the JVM based on the underlying system settings

Yes

SendBufferSize

Integer

socket send buffer size requested when establishing a connection to the server
0 = automatically determine by the JVM based on the underlying system settings

Yes

UseSchema

Boolean

false

whether to try to use schema information when reading data from the server

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

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 RA configuration properties configure secure connection:

Name Type Default Description Active reconfig?

TransportSecurity

String

None

enable/disable secure transport connection

Supported values are:

None — insecure connection (LDAP)
StartTLS — secure connection established using the StartTLS extended operation
TLS — secure connection (LDAPS).

CertificateKeyStore

String

path to JKS key store file to load certificate key from

May contain system properties in Ant style, for example ${rhino.dir.home} to refer to the Rhino home directory.
By default, the resource adaptors have permission to read files from ${rhino.dir.home}/keystores.

CertificateKeyStorePassword

String

password for certificate key store

TrustKeyStore

String

path to JKS key store for trust certificates

The special value <<TRUST ALL>> may be used to bypass trust checks.
If no value is specified (the default), then the JVM default trust manager is used.
May contain system properties in Ant style, for example ${rhino.dir.home} to refer to the Rhino home directory.
By default, the resource adaptors have permission to read files from ${rhino.dir.home}/keystores.

TrustKeyStorePassword

String

password for trust key store

CipherSuites

String

comma-separated list of TLS cipher suites to be enabled for use when establishing TLS handshake

May be any values supported by the virtual machine vendor.
If empty, uses the default cipher suites.

SSLSessionTimeout

Integer

time, in seconds, after which TLS session should be invalidated and new session will be established (cipher keys change)
0 = sessions do not time out

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.

LDAP Bind Queries

LDAP bind queries is a feature of the LDAP Resource Adaptor that allows for 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 (bind connection pool), which is disabled by default.

It must be enabled using the resource adaptor configuration properties (BindMinConnections and BindMaxConnections) to allow sending bind request(s).

LDAP Server Groups

LDAP server groups are sets of servers where one is a primary server, and the rest are backup servers.

Queries go to the primary server if available, otherwise to the backup server(s). For multiple server groups, the RA balances queries across groups.

You specify all LDAP server groups in a single string, white-space separated; and each server name may optionally contain a port number to use instead of the default LDAP port (389). For example:

Server group configuration What it specifies

Server group configuration	What it specifies
server1:389	1 group of 1 server
server1:389,server2:589	2 groups, each with 1 server
server1 server2,server3	2 groups, 1 with a backup server (`server2`)

server1:389

1 group of 1 server

server1:389,server2:589

2 groups, each with 1 server

server1 server2,server3

2 groups, 1 with a backup server (server2)

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:

LDAPSearchStats
LDAPBindStats
LDAPWorkerPoolStats.

The LDAPSearchStats and LDAPBindStats parameter sets have statistics that are specific to search and bind queries respectively. The LDAPWorkerPoolStats parameter set contains statistics specific to the worker pool of the LDAP RA.

A list of statistics with descriptions for each of these parameters sets can be displayed with the
rhino-stats -l command, as shown below.

`LDAPSearchStats` parameter set

Parameter Set: LDAP-RA.ldap.LDAPSearchStats
Parameter Set Type: ResourceAdaptorID[name=LDAP,vendor=OpenCloud,version=3.0].LDAPSearchStats
Description: Statistics for search queries of the LDAP RA

Counter type statistics:
  Id: Name:              Label:       Description:
  0   queries            queries      Number 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

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 search response

`LDAPBindStats` parameter set

Parameter Set: LDAP-RA.ldap.LDAPBindStats
Parameter Set Type: ResourceAdaptorID[name=LDAP,vendor=OpenCloud,version=3.0].LDAPBindStats
Description: Statistics for bind queries of the LDAP RA

Counter type statistics:
  Id: Name:              Label:   Description:
  0   queries            queries  Number LDAP queries started by the RA
  1   successfulQueries  success  Number of successful LDAP queries
  2   failedQueries      failed   Number of failed LDAP queries

Sample type statistics:
  Id: Name:         Label:     Description:
  3   queryTime     querytime  Time spent waiting for the bind 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

LDAP Resource Adaptor Guide

Topics

Configuring the LDAP Resource Adaptor

Deployment descriptor properties

Configuring secure communication (SSL/TLS or StartTLS)

Key stores

Active reconfiguration

LDAP Bind Queries

LDAP Server Groups

Monitoring Resource Adaptor Statistics

Statistics parameter sets

LDAPSearchStats parameter set

LDAPBindStats parameter set

LDAPWorkerPoolStats parameter set

`LDAPSearchStats` parameter set

`LDAPBindStats` parameter set

`LDAPWorkerPoolStats` parameter set