Package org.forgerock.openam.ldap

Class LDAPUtils

java.lang.Object
org.forgerock.openam.ldap.LDAPUtils
@Supported 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: 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 Details

  • Method Details

    • newPrioritizedFailoverConnectionPool

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

      @Supported public static ConnectionFactory newFailoverConnectionPool(Set<org.forgerock.openam.ldap.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

      @Supported public static ConnectionFactory newFailoverConnectionPool(Set<org.forgerock.openam.ldap.LDAPURL> servers, String username, char[] password, int maxSize, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, Options ldapOptions, boolean mtlsEnabled, String mtlsSecretId, Secrets secrets, Realm realm)
      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
      mtlsEnabled - whether mTLS is enabled.
      mtlsSecretId - is the ID of the mTLS secret.
      secrets - the secrets object.
      realm - the realm.
      Returns:
      A failover loadbalanced authenticated/anonymous connection pool, which may also send heartbeat requests.

    • newFailoverConnectionPool

      @Supported public static ConnectionFactory newFailoverConnectionPool(Set<org.forgerock.openam.ldap.LDAPURL> primaryUrls, Set<org.forgerock.openam.ldap.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.

    • newFailoverConnectionPool

      @Supported public static ConnectionFactory newFailoverConnectionPool(Set<org.forgerock.openam.ldap.LDAPURL> primaryUrls, Set<org.forgerock.openam.ldap.LDAPURL> secondaryUrls, String username, char[] password, int maxSize, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTLS, boolean sslTrustAll, boolean mtlsEnabled, String mtlsCertificateLabel, Realm realm, Secrets secrets, 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).
      mtlsEnabled - Whether mtls is enabled.
      mtlsCertificateLabel - The mtls certificate label, only required if mTLS is enabled.
      realm - The realm, only required if mTLS is enabled.
      secrets - The object to use to object secrets, only required if mTLS is enabled.
      ldapOptions - Additional LDAP settings used to create the pool
      Returns:
      A failover loadbalanced authenticated/anonymous connection pool, which may also send heartbeat requests.

    • newPrioritizedFailoverConnectionFactory

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

      @Supported public static ConnectionFactory newFailoverConnectionFactory(Set<org.forgerock.openam.ldap.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.

    • newFailoverConnectionFactory

      @Supported public static ConnectionFactory newFailoverConnectionFactory(Set<org.forgerock.openam.ldap.LDAPURL> servers, String username, char[] password, int heartBeatInterval, String heartBeatTimeUnit, boolean useStartTls, boolean sslTrustAll, boolean mtlsEnabled, String mtlsSecretId, Realm realm, Secrets secrets, 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).
      mtlsEnabled - whether mTLS is enabled.
      mtlsSecretId - is the ID of the mTLS secret.
      secrets - the secrets object.
      realm - the realm.
      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

      @Supported public static Set<org.forgerock.openam.ldap.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

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

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

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

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

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

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

      @Supported public static Set<org.forgerock.openam.ldap.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

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

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

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

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

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

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

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

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

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

      @Supported public static String escapeValue(String str)
      Escapes characters that should be escaped.
      Parameters:
      str - The string to escape.
      Returns:
      The escaped string.

    • partiallyEscapeAssertionValue

      @Supported public static String partiallyEscapeAssertionValue(String assertionValue, boolean allowWildCards)
      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.
      allowWildCards - Whether to allow wildcard characters or to escape them.
      Returns:
      The escaped assertionValue.

    • normalizeDN

      @Supported public static String normalizeDN(String dn)
      Normalizes the DN.
      Parameters:
      dn - The DN to normalize.
      Returns:
      The normalized DN.

    • newDN

      @Supported public static Dn newDN(String orgName)
      Creates a DN from the specified DN string.
      Parameters:
      orgName - The DN string.
      Returns:
      A DN.
      Throws:
      LocalizedIllegalArgumentException - If the provided string is not a valid LDAP string representation of a DN.

    • formatToRFC

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

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

      @Supported 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.

    • createFailoverConnectionFactory

      @Supported public static ConnectionFactory createFailoverConnectionFactory(String host, int defaultPort, boolean ssl, String authDN, String authPasswd, boolean mtlsEnabled, String mtlsSecretId, Realm realm, Secrets secrets, 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.
      mtlsEnabled - whether mTLS is enabled.
      mtlsSecretId - is the ID of the mTLS secret.
      secrets - the secrets object.
      realm - the realm.
      options - Any additional options.
      Returns:
      A connection factory.

    • getLdapUrls

      @Supported public static Set<org.forgerock.openam.ldap.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

      @Supported public static Set<org.forgerock.openam.ldap.LDAPURL> getLdapUrls(Set<org.forgerock.openam.ldap.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

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

      @Supported public static ConnectionFactory newPasswordConnectionFactory(Set<org.forgerock.openam.ldap.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 connection factory.
      Returns:
      A failover loadbalanced anonymous connection pool, which may also send heartbeat requests.

    • newPasswordConnectionFactory

      @Supported public static ConnectionFactory newPasswordConnectionFactory(Set<org.forgerock.openam.ldap.LDAPURL> primaryServers, Set<org.forgerock.openam.ldap.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 connection factory.
      Returns:
      A failover loadbalanced anonymous connection pool, which may also send heartbeat requests.