Package org.forgerock.openam.ldap

Class LDAPUtils

  • @SupportedAll
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 Detail

      • AFFINITY_ENABLED

        public static final Option<Boolean> AFFINITY_ENABLED
        An Option that tells whether affinity based load balancing is enabled for the connections.

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

        public static LdapConnectionFactory 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.

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

      • prioritizeServers

        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

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

        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,
                                                   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 - allow wild card queries with the '*' character.
        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<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

        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

        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<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 pool
        Returns:
        A failover loadbalanced anonymous connection pool, which may also send heartbeat requests.

      • newPasswordConnectionFactory

        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 pool
        Returns:
        A failover loadbalanced anonymous connection pool, which may also send heartbeat requests.