org.forgerock.openam.ldap

Class LDAPUtils

java.lang.Object

org.forgerock.openam.ldap.LDAPUtils

public final class LDAPUtils
extends Object

Utility methods to help interaction with the OpenDJ LDAP SDK. There are two main ways currently to create connection pools/factories:

• Providing a set of servers in the format specified in LDAPUtils.prioritizeServers(java.util.Set, java.lang.String, java.lang.String), which will be prioritized based on the current server's server ID/site ID.
• Providing a set of LDAPURLs, which are already considered as "prioritized".

In case the configuration provides the possibility to assign LDAP servers to OpenAM servers/sites, then either you can prioritize manually (if the logic differs from this implementation) and create the corresponding LDAPURL objects, or you can pass in the list to the newPrioritized* methods.

Field Summary

Fields

Modifier and Type	Field and Description
static Option<Boolean>	AFFINITY_ENABLED An Option that tells whether affinity based load balancing is enabled for the connections.
static Option<LDAPUtils.CachedPoolOptions>	CACHED_POOL_OPTIONS An Option that stores the settings related to cached connection pooling.

Method Summary

Modifier and Type	Method and Description
static void	addAttributeToMapAsByteArray(Attribute attribute, Map<String,byte[][]> map) Converts the Attribute to an attribute name, 2-dimensional byte array map and adds it to the map passed in.
static void	addAttributeToMapAsString(Attribute attribute, Map<String,Set<String>> map) Converts the Attribute to an attribute name, set of String values map and adds it to the map passed in.
static Set<String>	collectNonIdenticalValues(Dn compare, Set<String> dns) Returns a set of all the non-root DNs from the collection that are not equal to the compare parameter.
static Set<LDAPURL>	convertToLDAPURLs(Set<String> servers) Converts the incoming set of URLs to LDAPURL instances and returns them as a set.
static ConnectionFactory	createFailoverConnectionFactory(String host, int defaultPort, boolean ssl, String authDN, String authPasswd, Options options) Creates a ConnectionFactory from the host string and associated details.
static boolean	dnEquals(String dn1, String dn2) Determines if the DN's are equal.
static String	escapeValue(String str) Escapes characters that should be escaped.
static String	formatToRFC(String dn) Converts a DN String to a RFC format and lowers case.
static Set<String>	getAttributeValuesAsStringSet(Attribute attribute) Converts all the attribute values to a String Set.
static String	getDBName(String suffix, Connection ld) Gets the DB name.
static Set<LDAPURL>	getLdapUrls(Set<LDAPURL> ldapServers, boolean isSSL) Converts the ldapServers and ssl into LDAPURL and add it into a Set.
static Set<LDAPURL>	getLdapUrls(String serverName, int port, boolean isSSL) Converts the serverName, port and ssl into LDAPURL and add it into a Set.
static String	getName(Dn dn) Returns the RDN without the attribute name from the passed in Dn object, for example: uid=demo,ou=people,dc=example,dc=com will return demo.
static SearchScope	getSearchScope(String scope, SearchScope defaultScope) Converts string representation of scope (as defined in the configuration) to the corresponding SearchScope object.
static boolean	isDN(String candidateDN) Tests whether the supplied string is a DN, and is not the root DN.
static Dn	newDN(String orgName) Creates a DN from the specified DN string.
static ConnectionFactory	newFailoverConnectionFactory(Set<LDAPURL> servers, String username, char[] password, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTls, boolean sslTrustAll, Options ldapOptions) Creates a new connection factory that is capable to failover to the servers defined in case there is an error.
static LdapConnectionFactory	newFailoverConnectionPool(Set<LDAPURL> primaryUrls, Set<LDAPURL> secondaryUrls, String username, char[] password, int maxSize, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, Options ldapOptions) Creates a new connection pool that is capable to failover from the primary to the secondary servers defined in case there is an error.
static ConnectionFactory	newFailoverConnectionPool(Set<LDAPURL> servers, String username, char[] password, int maxSize, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, Options ldapOptions) Creates a new connection pool that is capable to failover to the servers defined in case there is an error.
static ConnectionFactory	newNamedConnectionFactory(ConnectionFactory factory, String name) Creates a new connection factory which forwards connection requests to the provided factory, but whose toString method will always return name.
static ConnectionFactory	newPasswordConnectionFactory(Set<LDAPURL> primaryServers, Set<LDAPURL> secondaryServers, String username, char[] password, int maxSize, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, Options ldapOptions) Creates a new connection pooled connection factory that is capable to failover to the servers defined in case there is an error.
static ConnectionFactory	newPasswordConnectionFactory(Set<LDAPURL> servers, String username, char[] password, int maxSize, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, Options ldapOptions) Creates a new connection pooled connection factory that is capable to failover to the servers defined in case there is an error.
static ConnectionFactory	newPrioritizedFailoverConnectionFactory(Set<String> servers, String hostServerId, String hostSiteId, String username, char[] password, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, Options options) Based on the incoming parameters prioritizes the LDAP server list, then creates a connection factory that is capable to failover to the servers defined in case there is an error.
static ConnectionFactory	newPrioritizedFailoverConnectionPool(Set<String> servers, String hostServerId, String hostSiteId, String username, char[] password, int maxSize, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, Options ldapOptions) Based on the incoming parameters prioritizes the LDAP server list, then creates a connection pool that is capable to failover to the servers defined in case there is an error.
static String	normalizeDN(String dn) Normalizes the DN.
static Filter	parseFilter(String filter, Filter defaultFilter) Parses the incoming filter, and in case of failure falls back to the default filter.
static String	partiallyEscapeAssertionValue(String assertionValue) Escapes the provided assertion value according to the LDAP standard.
static Set<LDAPURL>	prioritizeServers(Set<String> servers, String hostServerId, String hostSiteId) Prioritizes the incoming LDAP servers based on their assigned servers/sites.
static String	rdnType(Rdn rdn) When provided an RDN, returns the attribute type name.
static String	rdnTypeFromDn(Dn dn) When provided a DN, returns the attribute type name of the first RDN.
static String	rdnTypeFromDn(String dn) When provided a DN, returns the attribute type name of the first RDN.
static String	rdnValue(Rdn rdn) When provided an RDN, returns the value part.
static String	rdnValueFromDn(Dn dn) When provided a DN, returns the value part of the first RDN.
static String	rdnValueFromDn(String dn) When provided a DN, returns the value part of the first RDN.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AFFINITY_ENABLED

public static final Option<Boolean> AFFINITY_ENABLED

An Option that tells whether affinity based load balancing is enabled for the connections.

CACHED_POOL_OPTIONS

public static final Option<LDAPUtils.CachedPoolOptions> CACHED_POOL_OPTIONS

An Option that stores the settings related to cached connection pooling.

Method Detail

newPrioritizedFailoverConnectionPool

public static ConnectionFactory newPrioritizedFailoverConnectionPool(Set<String> servers,
                                                                     String hostServerId,
                                                                     String hostSiteId,
                                                                     String username,
                                                                     char[] password,
                                                                     int maxSize,
                                                                     int heartBeatInterval,
                                                                     String heartBeatTimeUnit,
                                                                     boolean useStartTLS,
                                                                     boolean sslTrustAll,
                                                                     Options ldapOptions)

Based on the incoming parameters prioritizes the LDAP server list, then creates a connection pool that is capable to failover to the servers defined in case there is an error.

Parameters:

servers - The set of servers in the format defined in LDAPUtils.prioritizeServers(java.util.Set, java.lang.String, java.lang.String).

hostServerId - The server ID for this OpenAM server.

hostSiteId - The site ID for this OpenAM server.

username - The directory user's DN. May be null if this is an anonymous connection.

password - The directory user's password.

maxSize - The max size of the created pool.

heartBeatInterval - The interval for sending out heartbeat requests.

heartBeatTimeUnit - The timeunit for the heartbeat interval.

useStartTLS - Use StartTLS to connect to the LDAP Server(s).

sslTrustAll - trust all certs to connect to the LDAPS Server(s).

ldapOptions - Additional LDAP settings used to create the pool.

Returns:

A failover loadbalanced authenticated/anonymous connection pool, which may also send heartbeat requests.

newFailoverConnectionPool

public static ConnectionFactory newFailoverConnectionPool(Set<LDAPURL> servers,
                                                          String username,
                                                          char[] password,
                                                          int maxSize,
                                                          int heartBeatInterval,
                                                          String heartBeatTimeUnit,
                                                          boolean useStartTLS,
                                                          boolean sslTrustAll,
                                                          Options ldapOptions)

Creates a new connection pool that is capable to failover to the servers defined in case there is an error.

Parameters:

servers - The set of LDAP URLs that will be used to set up the connection factory.

username - The directory user's DN. May be null if this is an anonymous connection.

password - The directory user's password.

maxSize - The max size of the created pool.

heartBeatInterval - The interval for sending out heartbeat requests.

heartBeatTimeUnit - The timeunit for the heartbeat interval.

useStartTLS - Use StartTLS to connect to the LDAP Server(s).

sslTrustAll - trust all certs to connect to the LDAPS Server(s).

ldapOptions - Additional LDAP settings used to create the pool

Returns:

A failover loadbalanced authenticated/anonymous connection pool, which may also send heartbeat requests.

newFailoverConnectionPool

public static LdapConnectionFactory newFailoverConnectionPool(Set<LDAPURL> primaryUrls,
                                                              Set<LDAPURL> secondaryUrls,
                                                              String username,
                                                              char[] password,
                                                              int maxSize,
                                                              int heartBeatInterval,
                                                              String heartBeatTimeUnit,
                                                              boolean useStartTLS,
                                                              boolean sslTrustAll,
                                                              Options ldapOptions)

Creates a new connection pool that is capable to failover from the primary to the secondary servers defined in case there is an error.

Parameters:

primaryUrls - The set of LDAP URLs that will be used as primary servers to set up the connection factory.

secondaryUrls - The set of LDAP URLs that will be used as secondary servers to set up the connection factory.

username - The directory user's DN. May be null if this is an anonymous connection.

password - The directory user's password.

maxSize - The max size of the created pool.

heartBeatInterval - The interval for sending out heartbeat requests.

heartBeatTimeUnit - The timeunit for the heartbeat interval.

useStartTLS - Use StartTLS to connect to the LDAP Server(s).

sslTrustAll - trust all certs to connect to the LDAPS Server(s).

ldapOptions - Additional LDAP settings used to create the pool

Returns:

A failover loadbalanced authenticated/anonymous connection pool, which may also send heartbeat requests.

newPrioritizedFailoverConnectionFactory

public static ConnectionFactory newPrioritizedFailoverConnectionFactory(Set<String> servers,
                                                                        String hostServerId,
                                                                        String hostSiteId,
                                                                        String username,
                                                                        char[] password,
                                                                        int heartBeatInterval,
                                                                        String heartBeatTimeUnit,
                                                                        boolean useStartTLS,
                                                                        boolean sslTrustAll,
                                                                        Options options)

Based on the incoming parameters prioritizes the LDAP server list, then creates a connection factory that is capable to failover to the servers defined in case there is an error.

Parameters:

servers - The set of servers in the format defined in LDAPUtils.prioritizeServers(java.util.Set, java.lang.String, java.lang.String).

hostServerId - The server ID for this OpenAM server.

hostSiteId - The site ID for this OpenAM server.

username - The directory user's DN. May be null if this is an anonymous connection.

password - The directory user's password.

heartBeatInterval - The interval for sending out heartbeat requests.

heartBeatTimeUnit - The timeunit for the heartbeat interval.

useStartTLS - Use StartTLS to connect to the LDAP Server(s).

sslTrustAll - trust all certs to connect to the LDAPS Server(s).

options - Additional LDAP settings used to create the connection factory.

Returns:

A failover loadbalanced authenticated/anonymous connection factory, which may also send heartbeat requests.

newFailoverConnectionFactory

public static ConnectionFactory newFailoverConnectionFactory(Set<LDAPURL> servers,
                                                             String username,
                                                             char[] password,
                                                             int heartBeatInterval,
                                                             String heartBeatTimeUnit,
                                                             boolean useStartTls,
                                                             boolean sslTrustAll,
                                                             Options ldapOptions)

Creates a new connection factory that is capable to failover to the servers defined in case there is an error.

Parameters:

servers - The set of LDAP URLs that will be used to set up the connection factory.

username - The directory user's DN. May be null if this is an anonymous connection.

password - The directory user's password.

heartBeatInterval - The interval for sending out heartbeat requests.

heartBeatTimeUnit - The timeunit for the heartbeat interval.

useStartTls - Use StartTLS to connect to the LDAP Server(s).

sslTrustAll - trust all certs to connect to the LDAPS Server(s).

ldapOptions - Additional LDAP settings used to create the connection factory.

Returns:

A failover loadbalanced authenticated/anonymous connection factory, which may also send heartbeat requests.

prioritizeServers

public static Set<LDAPURL> prioritizeServers(Set<String> servers,
                                             String hostServerId,
                                             String hostSiteId)

Prioritizes the incoming LDAP servers based on their assigned servers/sites. The format of the server list can be either one of the followings:

• host:port - The LDAP server has no preferred server/site
• host:port|serverid - The LDAP server should be mainly used by an OpenAM instance with the same serverid
• host:port|serverid|siteid - The LDAP server should be mainly used by an OpenAM instance with the same serverid or with the same siteid

The resulting priority list will have the following order:

• servers that are linked with this server
• servers that are linked with the current site
• any other server that did not match in the same order as they were defined

Parameters:

servers - The Set of servers that needs to be prioritized in the previously described format.

hostServerId - This server's ID.

hostSiteId - This server's site ID.

Returns:

The prioritized Set of LDAP URLs that can be used to create connection factories.

getSearchScope

public static SearchScope getSearchScope(String scope,
                                         SearchScope defaultScope)

Converts string representation of scope (as defined in the configuration) to the corresponding SearchScope object.

Parameters:

scope - the string representation of the scope.

defaultScope - in case the coversion fail this default scope should be returned.

Returns:

the corresponding SearchScope object.

parseFilter

public static Filter parseFilter(String filter,
                                 Filter defaultFilter)

Parses the incoming filter, and in case of failure falls back to the default filter.

Parameters:

filter - The filter that needs to be parsed.

defaultFilter - If the parsing fails, this will be returned.

Returns:

The parsed Filter object, or the default Filter, if the parse failed.

getName

public static String getName(Dn dn)

Returns the RDN without the attribute name from the passed in Dn object, for example: uid=demo,ou=people,dc=example,dc=com will return demo.

Parameters:

dn - The DN that we need the name of.

Returns:

The RDN of the DN without the attribute name.

addAttributeToMapAsByteArray

public static void addAttributeToMapAsByteArray(Attribute attribute,
                                                Map<String,byte[][]> map)

Converts the Attribute to an attribute name, 2-dimensional byte array map and adds it to the map passed in. The first dimension of the byte array separates the different values, the second dimension holds the actual value.

Parameters:

attribute - The attribute that needs to be converted.

map - The map where the converted attribute is added to.

addAttributeToMapAsString

public static void addAttributeToMapAsString(Attribute attribute,
                                             Map<String,Set<String>> map)

Converts the Attribute to an attribute name, set of String values map and adds it to the map passed in.

Parameters:

attribute - The attribute that needs to be converted.

map - The map where the converted attribute is added to.

getAttributeValuesAsStringSet

public static Set<String> getAttributeValuesAsStringSet(Attribute attribute)

Converts all the attribute values to a String Set.

Parameters:

attribute - the attribute to be converted.

Returns:

A Set of String representations of the Attribute values.

convertToLDAPURLs

public static Set<LDAPURL> convertToLDAPURLs(Set<String> servers)

Converts the incoming set of URLs to LDAPURL instances and returns them as a set. The iteration order of the originally passed in Set is retained.

Parameters:

servers - The LDAP server URLs that needs to be converted to LDAPURL instances.

Returns:

A set of LDAPURLs corresponding to the passed in URLs.

rdnValueFromDn

public static String rdnValueFromDn(String dn)

When provided a DN, returns the value part of the first RDN.

Parameters:

dn - A DN.

Returns:

The value part of the first RDN.

Throws:

IllegalArgumentException - When the DN's RDN is multivalued, or when the DN is not a valid name.

rdnValueFromDn

public static String rdnValueFromDn(Dn dn)

When provided a DN, returns the value part of the first RDN.

Parameters:

dn - A DN.

Returns:

The value part of the first RDN.

Throws:

IllegalArgumentException - When the DN's RDN is multivalued.

rdnValue

public static String rdnValue(Rdn rdn)

When provided an RDN, returns the value part.

Parameters:

rdn - An RDN.

Returns:

The value part.

Throws:

IllegalArgumentException - When the RDN is multivalued.

rdnTypeFromDn

public static String rdnTypeFromDn(String dn)

When provided a DN, returns the attribute type name of the first RDN.

Parameters:

dn - A DN.

Returns:

The attribute type name of the first RDN.

Throws:

IllegalArgumentException - When the DN's RDN is multivalued.

rdnTypeFromDn

public static String rdnTypeFromDn(Dn dn)

When provided a DN, returns the attribute type name of the first RDN.

Parameters:

dn - A DN.

Returns:

The attribute type name of the first RDN.

Throws:

IllegalArgumentException - When the DN's RDN is multivalued.

rdnType

public static String rdnType(Rdn rdn)

When provided an RDN, returns the attribute type name.

Parameters:

rdn - An RDN.

Returns:

The attribute type name.

Throws:

IllegalArgumentException - When the RDN is multivalued.

collectNonIdenticalValues

public static Set<String> collectNonIdenticalValues(Dn compare,
                                                    Set<String> dns)
                                             throws InvalidNameException

Returns a set of all the non-root DNs from the collection that are not equal to the compare parameter.

Parameters:

compare - The DN to compare against.

dns - THe DNs to compare.

Returns:

A Set of non identical DNs.

Throws:

InvalidNameException - If an error occurs.

getDBName

public static String getDBName(String suffix,
                               Connection ld)

Gets the DB name.

Parameters:

suffix - The suffix.

ld - The connection.

Returns:

The name of the DB.

isDN

public static boolean isDN(String candidateDN)

Tests whether the supplied string is a DN, and is not the root DN.

Parameters:

candidateDN - The possible DN.

Returns:

true if the string is a DN.

escapeValue

public static String escapeValue(String str)

Escapes characters that should be escaped.

Parameters:

str - The string to escape.

Returns:

The escaped string.

partiallyEscapeAssertionValue

public static String partiallyEscapeAssertionValue(String assertionValue)

Escapes the provided assertion value according to the LDAP standard. As a special case this method does not escape the '*' character, in order to be able to use wildcards in filters.

Parameters:

assertionValue - The filter assertionValue that needs to be escaped.

Returns:

The escaped assertionValue.

normalizeDN

public static String normalizeDN(String dn)

Normalizes the DN.

Parameters:

dn - The DN to normalize.

Returns:

The normalized DN.

newDN

public static Dn newDN(String orgName)

Creates a DN from the specified DN string.

Parameters:

orgName - The DN string.

Returns:

A DN.

formatToRFC

public static String formatToRFC(String dn)

Converts a DN String to a RFC format and lowers case.

Parameters:

dn - the DN String to be formated

Returns:

a lowercase RFC fromat DN String

dnEquals

public static boolean dnEquals(String dn1,
                               String dn2)

Determines if the DN's are equal.

Parameters:

dn1 - The first DN.

dn2 - The second DN.

Returns:

true if the DN's are equal.

createFailoverConnectionFactory

public static ConnectionFactory createFailoverConnectionFactory(String host,
                                                                int defaultPort,
                                                                boolean ssl,
                                                                String authDN,
                                                                String authPasswd,
                                                                Options options)

Creates a ConnectionFactory from the host string and associated details. The host string can be any of the following:

• A plain hostname/IP address
• A hostname and port, in the format [host]:[port]
• A space-separated list of hostnames in priority order, e.g. host1 host2 host3
• A space-separated list of hostnames with port numbers in priority order, e.g. host1:389 host2:50389

If a list of hosts is given, a load balanced ConnectionFactory is returned. All factories are pre-authenticated using the supplied credentials.

Parameters:

host - The host/host-port string.

defaultPort - The port number to use for hosts that do not specify a port in the string.

ssl - SSL enabled or not.

authDN - The DN to bind with.

authPasswd - The password to bind with.

options - Any additional options.

Returns:

A connection factory.

getLdapUrls

public static Set<LDAPURL> getLdapUrls(String serverName,
                                       int port,
                                       boolean isSSL)

Converts the serverName, port and ssl into LDAPURL and add it into a Set.

Parameters:

serverName - The LDAP server name.

port - The LDAP server port number.

isSSL - boolean value of true/false for ssl.

Returns:

A set of LDAPURLs based on the passed serverName, port and ssl.

getLdapUrls

public static Set<LDAPURL> getLdapUrls(Set<LDAPURL> ldapServers,
                                       boolean isSSL)

Converts the ldapServers and ssl into LDAPURL and add it into a Set.

Parameters:

ldapServers - The LDAP servers in the format of serverName:port

isSSL - boolean value of true/false for ssl.

Returns:

A set of LDAPURLs based on the passed serverName, port and ssl.

newNamedConnectionFactory

public static ConnectionFactory newNamedConnectionFactory(ConnectionFactory factory,
                                                          String name)

Creates a new connection factory which forwards connection requests to the provided factory, but whose toString method will always return name.

This method may be useful for debugging purposes in order to more easily identity connection factories.

Parameters:

factory - The connection factory to be named.

name - The name of the connection factory.

Returns:

The named connection factory.

Throws:

NullPointerException - If factory or name was null.

newPasswordConnectionFactory

public static ConnectionFactory newPasswordConnectionFactory(Set<LDAPURL> servers,
                                                             String username,
                                                             char[] password,
                                                             int maxSize,
                                                             int heartBeatInterval,
                                                             String heartBeatTimeUnit,
                                                             boolean useStartTLS,
                                                             boolean sslTrustAll,
                                                             Options ldapOptions)

Creates a new connection pooled connection factory that is capable to failover to the servers defined in case there is an error.

Parameters:

servers - The set of LDAP URLs that will be used to set up the connection factory.

username - The directory user's DN. May be null if this is an anonymous connection.

password - The directory user's password.

maxSize - The max size of the created pool.

heartBeatInterval - The interval for sending out heartbeat requests.

heartBeatTimeUnit - The timeunit for the heartbeat interval.

useStartTLS - Use StartTLS to connect to the LDAP Server(s).

sslTrustAll - trust all certs to connect to the LDAPS Server(s).

ldapOptions - Additional LDAP settings used to create the pool

Returns:

A failover loadbalanced anonymous connection pool, which may also send heartbeat requests.

newPasswordConnectionFactory

public static ConnectionFactory newPasswordConnectionFactory(Set<LDAPURL> primaryServers,
                                                             Set<LDAPURL> secondaryServers,
                                                             String username,
                                                             char[] password,
                                                             int maxSize,
                                                             int heartBeatInterval,
                                                             String heartBeatTimeUnit,
                                                             boolean useStartTLS,
                                                             boolean sslTrustAll,
                                                             Options ldapOptions)

Creates a new connection pooled connection factory that is capable to failover to the servers defined in case there is an error.

Parameters:

primaryServers - The set of LDAP URLs that will be used to set up the connection factory.

secondaryServers - The secondary set of LDAP URLs that will be used to set up the connection factory.

username - The directory user's DN. May be null if this is an anonymous connection.

password - The directory user's password.

maxSize - The max size of the created pool.

heartBeatInterval - The interval for sending out heartbeat requests.

heartBeatTimeUnit - The timeunit for the heartbeat interval.

useStartTLS - Use StartTLS to connect to the LDAP Server(s).

sslTrustAll - trust all certs to connect to the LDAPS Server(s).

ldapOptions - Additional LDAP settings used to create the pool

Returns:

A failover loadbalanced anonymous connection pool, which may also send heartbeat requests.