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

Configuring the LDAP Resource Adaptor

how to configure the resource adaptor using properties

Monitoring Resource Adaptor Statistics

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

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 AllowUnauthenticatedBind

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

 SearchTimeLimit
 Integer
 0

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

Yes

 MinConnections
 Integer
 10

how few TCP connections the resource adaptor will hold open in the connection pool (assuming the LDAP servers are reachable);
connections from this pool will be used for all query types except bind queries

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);
connections from this pool will be used for bind queries exclusively
(for the LDAP bind queries feature)

Yes

 BindMaxConnections
 Integer
 0

how many TCP connections the resource adaptor will hold open in the bind connection pool
0 = no connections in the bind pool (the LDAP bind queries feature is disabled in the resource adaptor)

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.
A value of 0 causes the connection to remain open indefinitely.
i.e. the primary server(s) will only be retried if the backup server fails.

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.
A value of 0 causes the connection to remain open indefinitely.
i.e. the primary server(s) will only be retried if the backup server fails.

Yes

 MaxQueueSize
 Integer
 (MaxConnections +BindMaxConnections) *3

how many queued queries will wait for a thread pool thread before they execute
(active reconfiguration of MaxConnections and BindMaxConnections won’t affect value of MaxQueueSize if default was used until resource adaptor reactivation)

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
(for the graceful connection establishment feature)

Yes

 PollCount
 Integer
 2

how many successful polls before sending regular 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

 IdleTimeout
 Integer
 0

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

Yes

 MaxQueriesPerConnection
 Integer
 0

how many queries a specific TCP connection in the connection pool can have before it closes
0 = do not close 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
(triggered by the periodic health checks, with frequency specified by BindHealthCheckInterval, or whenever connection is released to the bind pool, specified by BindCheckConnectionAgeOnRelease);
0 = do not close based on connection age

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 QueryTimeout (this does not affect the query timeout behaviour);
this is applicable to all query types except bind queries

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 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
(after reconfiguration will apply only to newly created connections)

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 BindMaxConnectionAge, whenever it is released to the bind pool

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

Note

Supported values are:

  • None — insecure connection (LDAP)

  • StartTLS — secure connection established using the StartTLS extended operation

  • TLS — secure connection (LDAPS).

No

 CertificateKeyStore
 String

          

path to JKS key store file to load certificate key from

Note
  • 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.

No

 CertificateKeyStorePassword
 String

          

password for certificate key store

No

 TrustKeyStore
 String

          

path to JKS key store for trust certificates

Note
  • 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.

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

Note
  • May be any values supported by the virtual machine vendor.

  • If empty, uses the default cipher suites.

No

 SSLSessionTimeout
 Integer
 0

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

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.

Note

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 (PollInterval, PollCount, PollDN, PollSearchFilter, PollSearchScope, and PollSuccessResultCodes).

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.

Note

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.

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 (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:

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.

Tip A list of statistics with descriptions for each of these parameters sets can be displayed with the
rhino-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