Class LdapManager
- java.lang.Object
-
- org.jivesoftware.openfire.ldap.LdapManager
-
public class LdapManager extends Object
Centralized administration of LDAP connections. ThegetInstance()
method should be used to get an instace. The following properties configure this manager:- ldap.host
- ldap.port
- ldap.baseDN
- ldap.alternateBaseDN
- ldap.adminDN
- ldap.adminPassword
- ldap.usernameField -- default value is "uid".
- ldap.usernameSuffix -- default value is "".
- ldap.nameField -- default value is "cn".
- ldap.emailField -- default value is "mail".
- ldap.searchFilter -- the filter used to load the list of users. When defined, it will be used with the default filter, which is "([usernameField]={0})" where [usernameField] is the value of ldap.usernameField.
- ldap.groupNameField
- ldap.groupMemberField
- ldap.groupDescriptionField
- ldap.posixMode
- ldap.groupSearchFilter
- ldap.flattenNestedGroups
- ldap.debugEnabled
- ldap.sslEnabled
- ldap.startTlsEnabled
- ldap.autoFollowReferrals
- ldap.autoFollowAliasReferrals
- ldap.initialContextFactory -- if this value is not specified, "com.sun.jndi.ldap.LdapCtxFactory" will be used.
- ldap.connectionPoolEnabled -- true if an LDAP connection pool should be used. False if not set.
- ldap.findUsersFromGroupsEnabled -- If true then Openfire users will be identified from the members of Openfire groups instead of from the list of all users in LDAP. This option is only useful if you wish to restrict the users of Openfire to those in certain groups. Normally this is done by applying an appropriate ldap.searchFilter, but there are a number of reasons why you may wish to enable this option instead:
- If group members cannot be identified by the attributes of the user in LDAP (typically the memberOf attribute) then users cannot be filtered using ldap.searchFilter
- If the number of Openfire users is small compared to the total number of users in LDAP then it may be more performant to identify these users from the groups to which they belong instead of applying an ldap.searchFilter. Note that if this is not the case, enabling this option may significantly decrease performance.
- Author:
- Matt Tucker
-
-
Field Summary
Fields Modifier and Type Field Description static SystemProperty<Integer>
LDAP_PAGE_SIZE
-
Constructor Summary
Constructors Constructor Description LdapManager(Map<String,String> properties)
Constructs a new LdapManager instance.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
checkAuthentication(Rdn[] userRDN, String password)
Returns true if the user is able to successfully authenticate against the LDAP server.static LdapName
createNewAbsolute(LdapName base, Rdn[] relative)
static LdapName
escapeForJNDI(Rdn... rdn)
Returns a JNDI Name for an array of RDNs that is suitable to use to access LDAP through JNDI.LdapName
findGroupAbsoluteDN(String groupname)
LikefindGroupRDN(String)
but returns the absolute DN of a groupRdn[]
findGroupRDN(String groupname)
Finds a groups's RDN using it's group name.Rdn[]
findGroupRDN(String groupname, LdapName baseDN)
Finds a groups's dn using it's group name.Rdn[]
findUserRDN(String username)
Finds a user's RDN using their username.Rdn[]
findUserRDN(String username, LdapName baseDN)
Finds a user's RDN using their username in the specified baseDN.String
getAdminDN()
Returns the starting admin DN that searches for admins will performed with.String
getAdminPassword()
Returns the starting admin DN that searches for admins will performed with.LdapName
getAlternateBaseDN()
Returns the alternate starting DN that searches for users will performed with.LdapName
getBaseDN()
Returns the starting DN that searches for users will performed with.LdapContext
getContext()
Returns a DirContext for the LDAP server that can be used to perform lookups and searches using the default base DN.LdapContext
getContext(LdapName baseDN)
Returns a DirContext for the LDAP server that can be used to perform lookups and searches using the specified base DN.String
getEmailField()
Returns the LDAP field name that the user's email address is stored in.String
getGroupDescriptionField()
Return the field used to describe a group.String
getGroupMemberField()
Return the field used to list members within a group.String
getGroupNameField()
Returns the field name used for groups.LdapName
getGroupsBaseDN(String groupname)
Returns the BaseDN for the given groupname.String
getGroupSearchFilter()
Returns the filter used for searching the directory for groups, which includes the default filter plus any custom-defined search filter.Collection<String>
getHosts()
Returns the LDAP servers hosts; e.g.static LdapManager
getInstance()
Provides singleton access to an instance of the LdapManager class.LdapUserTester.PropertyMapping
getNameField()
Returns the LDAP field name that the user's name is stored in.int
getPort()
Returns the LDAP server port number.static Rdn[]
getRelativeDNFromResult(SearchResult answer)
Returns a RDN from the search result answer.String
getSearchFilter()
Returns the filter used for searching the directory for users, which includes the default filter (username field search) plus any custom-defined search filter.String
getUsernameField()
Returns the LDAP field name that the lookup for an authorization identity (username to act as) will be performed on.String
getUsernameSuffix()
Returns the suffix appended to the username when LDAP lookups are performed.LdapName
getUsersBaseDN(String username)
Returns the BaseDN for the given username.boolean
isConnectionPoolEnabled()
Returns whether an LDAP connection pool should be used or not.boolean
isDebugEnabled()
Returns true if LDAP connection debugging is turned on.boolean
isFindUsersFromGroupsEnabled()
boolean
isFlattenNestedGroups()
Returns true if nested / complex / hierarchic groups should be should be flattened.boolean
isFollowAliasReferralsEnabled()
Returns true if LDAP alias referrals will automatically be followed when found.boolean
isFollowReferralsEnabled()
Returns true if LDAP referrals will automatically be followed when found.boolean
isGroupDN(LdapName dn)
Check if the given DN matches the group search filterboolean
isPosixMode()
Return true if the LDAP server is operating in Posix mode.boolean
isSslEnabled()
Returns true if LDAP connection is via SSL or not.boolean
isStartTlsEnabled()
Returns true if LDAP connection is via START or not.boolean
isSubTreeSearch()
Returns true if the entire tree under the base DN will be searched (recursive search) when doing LDAP queries (finding users, groups, etc).static String
joinFilter(char operator, List<String> parts)
Joins individual strings into one, formatted as an LDAP filter, such as(&(part-a)(part-b)(part-c))
.LdapName
parseAsLdapNameOrLog(String value)
Attempts to parse a string value as an LdapName.List<String>
retrieveAttributeOf(String attributeName, LdapName dn)
Reads the attribute values of an entry with the given DN.List<String>
retrieveList(String attribute, String searchFilter, int startIndex, int numResults, String suffixToTrim)
Generic routine for retrieving a list of results from the LDAP server.List<String>
retrieveList(String attribute, String searchFilter, int startIndex, int numResults, String suffixToTrim, boolean escapeJIDs)
Generic routine for retrieving a list of results from the LDAP server.Integer
retrieveListCount(String attribute, String searchFilter)
Generic routine for retrieving the number of available results from the LDAP server that match the passed search filter.String
retrieveSingle(String attribute, String searchFilter, boolean failOnMultipleResults)
Generic routine for retrieving a single element from the LDAP server.String
retrieveSingle(String attribute, String searchFilter, boolean failOnMultipleResults, LdapName baseDN)
Generic routine for retrieving a single element from the LDAP server.static String
sanitizeSearchFilter(String value)
Escapes any special chars (RFC 4515) from a string representing a search filter assertion value.static String
sanitizeSearchFilter(String value, boolean acceptWildcard)
Escapes any special chars (RFC 4514/4515) from a string representing a search filter assertion value, with the exception of the '*' wildcard signvoid
setAdminDN(String adminDN)
Sets the starting admin DN that searches for admins will performed with.void
setAdminPassword(String adminPassword)
Sets the admin password for the LDAP server we're connecting to.void
setAlternateBaseDN(LdapName alternateBaseDN)
Sets the alternate starting DN that searches for users will performed with.void
setBaseDN(LdapName baseDN)
Sets the starting DN that searches for users will performed with.void
setConnectionPoolEnabled(boolean connectionPoolEnabled)
Sets whether an LDAP connection pool should be used or not.void
setDebugEnabled(boolean debugEnabled)
Sets whether LDAP connection debugging is turned on.void
setEmailField(String emailField)
Sets the LDAP field name that the user's email address is stored in.void
setFlattenNestedGroups(boolean flattenNestedGroups)
Set whether nested / complex / hierarchic groups should be should be flattened.void
setFollowAliasReferralsEnabled(boolean followAliasReferrals)
Sets whether LDAP alias referrals should be automatically followed.void
setFollowReferralsEnabled(boolean followReferrals)
Sets whether LDAP referrals should be automatically followed.void
setGroupDescriptionField(String groupDescriptionField)
Sets the field used to describe a group.void
setGroupMemberField(String groupMemberField)
Sets the field used to list members within a group.void
setGroupNameField(String groupNameField)
Sets the field name used for groups.void
setGroupSearchFilter(String groupSearchFilter)
Sets the search filter appended to the default filter when searching for groups.void
setHosts(Collection<String> hosts)
Sets the list of LDAP servers host; e.g.,localhost
ormachine.example.com
, etc.static void
setInstance(LdapManager instance)
Exposed for test use onlyvoid
setNameField(LdapUserTester.PropertyMapping nameField)
Sets the LDAP field name that the user's name is stored in.void
setPort(int port)
Sets the LDAP server port number.void
setPosixMode(boolean posixMode)
Sets whether the LDAP server is operating in Posix mode.void
setSearchFilter(String searchFilter)
Sets the search filter appended to the default filter when searching for users.void
setSslEnabled(boolean sslEnabled)
Sets whether the connection to the LDAP server should be made via ssl or not.void
setStartTlsEnabled(boolean startTlsEnabled)
Sets whether the connection to the LDAP server should be made via StartTLS or not.void
setSubTreeSearch(boolean subTreeSearch)
Sets whether the entire tree under the base DN will be searched (recursive search) when doing LDAP queries (finding users, groups, etc).void
setUsernameField(String usernameField)
Sets the LDAP field name that the username lookup will be performed on.void
setUsernameSuffix(String usernameSuffix)
Set the suffix appended to the username whenever LDAP lookups are performed.static List<String>
splitFilter(String input)
Splits a string formatted as an LDAP filter, such as(&(part-a)(part-b)(part-c))
, in separate parts.
-
-
-
Field Detail
-
LDAP_PAGE_SIZE
public static final SystemProperty<Integer> LDAP_PAGE_SIZE
-
-
Constructor Detail
-
LdapManager
public LdapManager(Map<String,String> properties)
Constructs a new LdapManager instance. Typically,getInstance()
should be called instead of this method. LdapManager instances should only be created directly for testing purposes.- Parameters:
properties
- the Map that contains properties used by the LDAP manager, such as LDAP host and base DN.
-
-
Method Detail
-
setInstance
public static void setInstance(LdapManager instance)
Exposed for test use only
-
getInstance
public static LdapManager getInstance()
Provides singleton access to an instance of the LdapManager class.- Returns:
- an LdapManager instance.
-
splitFilter
public static List<String> splitFilter(String input)
Splits a string formatted as an LDAP filter, such as(&(part-a)(part-b)(part-c))
, in separate parts. When the provided input cannot be parsed as an LDAP filter, the returned collection contains one element: the original input.- Parameters:
input
- The value to be split.- Returns:
- The splitted value.
-
joinFilter
public static String joinFilter(char operator, List<String> parts)
Joins individual strings into one, formatted as an LDAP filter, such as(&(part-a)(part-b)(part-c))
.- Parameters:
operator
- the second character of the resulting string.parts
- The parts to be joined into one string.- Returns:
- The joined string value.
-
parseAsLdapNameOrLog
public LdapName parseAsLdapNameOrLog(String value)
Attempts to parse a string value as an LdapName. This method returns null (and logs an error) if the value was non-null and non-empty and the parsing fails. This method returns null if the provided value was null or empty.- Parameters:
value
- The value to be parsed (can be null or empty).- Returns:
- The parsed value, possibly null.
-
getRelativeDNFromResult
public static Rdn[] getRelativeDNFromResult(SearchResult answer) throws NamingException
Returns a RDN from the search result answer. The return value consists of one or more Rdn instances, that, when combined, are relative to the base DN that was used for the search.- Parameters:
answer
- The result of the search (cannot be null).- Returns:
- A relative distinguished name from the answer.
- Throws:
NamingException
- When the search result value cannot be used to form a valid RDN value.
-
getContext
public LdapContext getContext() throws NamingException
Returns a DirContext for the LDAP server that can be used to perform lookups and searches using the default base DN. The alternate DN will be used in case there is aNamingException
using base DN. The context uses the admin login that is defined byadminDN
andadminPassword
.- Returns:
- a connection to the LDAP server.
- Throws:
NamingException
- if there is an error making the LDAP connection.
-
getContext
public LdapContext getContext(LdapName baseDN) throws NamingException
Returns a DirContext for the LDAP server that can be used to perform lookups and searches using the specified base DN. The context uses the admin login that is defined byadminDN
andadminPassword
.- Parameters:
baseDN
- the base DN to use for the context.- Returns:
- a connection to the LDAP server.
- Throws:
NamingException
- if there is an error making the LDAP connection.
-
checkAuthentication
public boolean checkAuthentication(Rdn[] userRDN, String password)
Returns true if the user is able to successfully authenticate against the LDAP server. The "simple" authentication protocol is used.- Parameters:
userRDN
- the user's rdn to authenticate (relative tobaseDN
).password
- the user's password.- Returns:
- true if the user successfully authenticates.
-
isFindUsersFromGroupsEnabled
public boolean isFindUsersFromGroupsEnabled()
-
findUserRDN
public Rdn[] findUserRDN(String username) throws Exception
Finds a user's RDN using their username. Normally, this search will be performed using the field "uid", but this can be changed by setting theusernameField
property.Searches are performed over all subtrees relative to the
baseDN
. If the search fails in thebaseDN
then another search will be performed in thealternateBaseDN
. For example, if thebaseDN
is "o=jivesoftware, o=com" and we do a search for "mtucker", then we might find a userDN of "uid=mtucker,ou=People". This kind of searching is a good thing since it doesn't make the assumption that all user records are stored in a flat structure. However, it does add the requirement that "uid" field (or the other field specified) must be unique over the entire subtree from thebaseDN
. For example, it's entirely possible to create two dn's in your LDAP directory with the same uid: "uid=mtucker,ou=People" and "uid=mtucker,ou=Administrators". In such a case, it's not possible to uniquely identify a user, so this method will throw an error.The dn that's returned is relative to the default
baseDN
.- Parameters:
username
- the username to lookup the dn for.- Returns:
- the dn associated with
username
. - Throws:
Exception
- if the search for the dn fails.
-
findUserRDN
public Rdn[] findUserRDN(String username, LdapName baseDN) throws Exception
Finds a user's RDN using their username in the specified baseDN. Normally, this search will be performed using the field "uid", but this can be changed by setting theusernameField
property. Searches are performed over all sub-trees relative to thebaseDN
unless sub-tree searching has been disabled. For example, if thebaseDN
is "o=jivesoftware, o=com" and we do a search for "mtucker", then we might find a userDN of "uid=mtucker,ou=People". This kind of searching is a good thing since it doesn't make the assumption that all user records are stored in a flat structure. However, it does add the requirement that "uid" field (or the other field specified) must be unique over the entire subtree from thebaseDN
. For example, it's entirely possible to create two dn's in your LDAP directory with the same uid: "uid=mtucker,ou=People" and "uid=mtucker,ou=Administrators". In such a case, it's not possible to uniquely identify a user, so this method will throw an error.The RDN that's returned is relative to the
baseDN
.- Parameters:
username
- the username to lookup the dn for.baseDN
- the base DN to use for this search.- Returns:
- the RDN associated with
username
. - Throws:
Exception
- if the search for the RDN fails.- See Also:
to search using the default baseDN and alternateBaseDN.
-
findGroupRDN
public Rdn[] findGroupRDN(String groupname) throws Exception
Finds a groups's RDN using it's group name. Normally, this search will be performed using the field "cn", but this can be changed by setting thegroupNameField
property.Searches are performed over all subtrees relative to the
baseDN
. If the search fails in thebaseDN
then another search will be performed in thealternateBaseDN
. For example, if thebaseDN
is "o=jivesoftware, o=com" and we do a search for "managers", then we might find a groupDN of "uid=managers,ou=Groups". This kind of searching is a good thing since it doesn't make the assumption that all user records are stored in a flat structure. However, it does add the requirement that "cn" field (or the other field specified) must be unique over the entire subtree from thebaseDN
. For example, it's entirely possible to create two dn's in your LDAP directory with the same cn: "cn=managers,ou=Financial" and "cn=managers,ou=Engineers". In such a case, it's not possible to uniquely identify a group, so this method will throw an error.The RDN that's returned is relative to the default
baseDN
.- Parameters:
groupname
- the groupname to lookup the RDN for.- Returns:
- the RDN associated with
groupname
. - Throws:
Exception
- if the search for the RDN fails.
-
findGroupAbsoluteDN
public LdapName findGroupAbsoluteDN(String groupname) throws Exception
LikefindGroupRDN(String)
but returns the absolute DN of a group- Throws:
Exception
-
findGroupRDN
public Rdn[] findGroupRDN(String groupname, LdapName baseDN) throws Exception
Finds a groups's dn using it's group name. Normally, this search will be performed using the field "cn", but this can be changed by setting thegroupNameField
property.Searches are performed over all subtrees relative to the
baseDN
. If the search fails in thebaseDN
then another search will be performed in thealternateBaseDN
. For example, if thebaseDN
is "o=jivesoftware, o=com" and we do a search for "managers", then we might find a groupDN of "uid=managers,ou=Groups". This kind of searching is a good thing since it doesn't make the assumption that all user records are stored in a flat structure. However, it does add the requirement that "cn" field (or the other field specified) must be unique over the entire subtree from thebaseDN
. For example, it's entirely possible to create two dn's in your LDAP directory with the same cn: "cn=managers,ou=Financial" and "cn=managers,ou=Engineers". In such a case, it's not possible to uniquely identify a group, so this method will throw an error.The dn that's returned is relative to the default
baseDN
.- Parameters:
groupname
- the groupname to lookup the dn for.baseDN
- the base DN to use for this search.- Returns:
- the dn associated with
groupname
. - Throws:
Exception
- if the search for the dn fails.- See Also:
to search using the default baseDN and alternateBaseDN.
-
isGroupDN
public boolean isGroupDN(LdapName dn)
Check if the given DN matches the group search filter- Parameters:
dn
- the absolute DN of the node to check- Returns:
- true if the given DN is matching the group filter. false oterwise.
- Throws:
NamingException
- if the search for the dn fails.
-
getHosts
public Collection<String> getHosts()
Returns the LDAP servers hosts; e.g.localhost
ormachine.example.com
, etc. This value is stored as the Jive Propertyldap.host
.- Returns:
- the LDAP server host name.
-
setHosts
public void setHosts(Collection<String> hosts)
Sets the list of LDAP servers host; e.g.,localhost
ormachine.example.com
, etc. This value is store as the Jive Propertyldap.host
using a comma as a delimiter for each host.Note that all LDAP servers have to share the same configuration.
- Parameters:
hosts
- the LDAP servers host names.
-
getPort
public int getPort()
Returns the LDAP server port number. The default is 389. This value is stored as the Jive Propertyldap.port
.- Returns:
- the LDAP server port number.
-
setPort
public void setPort(int port)
Sets the LDAP server port number. The default is 389. This value is stored as the Jive propertyldap.port
.- Parameters:
port
- the LDAP server port number.
-
isDebugEnabled
public boolean isDebugEnabled()
Returns true if LDAP connection debugging is turned on. When on, trace information about BER buffers sent and received by the LDAP provider is written to System.out. Debugging is turned off by default.- Returns:
- true if LDAP debugging is turned on.
-
setDebugEnabled
public void setDebugEnabled(boolean debugEnabled)
Sets whether LDAP connection debugging is turned on. When on, trace information about BER buffers sent and received by the LDAP provider is written to System.out. Debugging is turned off by default.- Parameters:
debugEnabled
- true if debugging should be turned on.
-
isSslEnabled
public boolean isSslEnabled()
Returns true if LDAP connection is via SSL or not. SSL is turned off by default.- Returns:
- true if SSL connections are enabled or not.
-
setSslEnabled
public void setSslEnabled(boolean sslEnabled)
Sets whether the connection to the LDAP server should be made via ssl or not.- Parameters:
sslEnabled
- true if ssl should be enabled, false otherwise.
-
isStartTlsEnabled
public boolean isStartTlsEnabled()
Returns true if LDAP connection is via START or not. TLS is turned off by default.- Returns:
- true if StartTLS connections are enabled or not.
-
setStartTlsEnabled
public void setStartTlsEnabled(boolean startTlsEnabled)
Sets whether the connection to the LDAP server should be made via StartTLS or not.- Parameters:
startTlsEnabled
- true if StartTLS should be used, false otherwise.
-
getUsernameField
public String getUsernameField()
Returns the LDAP field name that the lookup for an authorization identity (username to act as) will be performed on. By default, this is "uid".- Returns:
- the LDAP field that the authorization identity (username to act as) lookup will be performed on.
-
getUsernameSuffix
public String getUsernameSuffix()
Returns the suffix appended to the username when LDAP lookups are performed. By default this is "".- Returns:
- the suffix appened to usernames when LDAP lookups are performed.
-
setUsernameField
public void setUsernameField(String usernameField)
Sets the LDAP field name that the username lookup will be performed on. By default this is "uid".- Parameters:
usernameField
- the LDAP field that the username lookup will be performed on.
-
setUsernameSuffix
public void setUsernameSuffix(String usernameSuffix)
Set the suffix appended to the username whenever LDAP lookups are performed.- Parameters:
usernameSuffix
- the String to append to usernames for lookups
-
getNameField
public LdapUserTester.PropertyMapping getNameField()
Returns the LDAP field name that the user's name is stored in. By default this is "cn". Another common value is "displayName".- Returns:
- the LDAP field that that corresponds to the user's name.
-
setNameField
public void setNameField(LdapUserTester.PropertyMapping nameField)
Sets the LDAP field name that the user's name is stored in. By default this is "cn". Another common value is "displayName".- Parameters:
nameField
- the LDAP field that that corresponds to the user's name.
-
getEmailField
public String getEmailField()
Returns the LDAP field name that the user's email address is stored in. By default this is "mail".- Returns:
- the LDAP field that that corresponds to the user's email address.
-
setEmailField
public void setEmailField(String emailField)
Sets the LDAP field name that the user's email address is stored in. By default this is "mail".- Parameters:
emailField
- the LDAP field that that corresponds to the user's email address.
-
getBaseDN
public LdapName getBaseDN()
Returns the starting DN that searches for users will performed with. Searches will performed on the entire sub-tree under the base DN.- Returns:
- the starting DN used for performing searches.
-
setBaseDN
public void setBaseDN(LdapName baseDN)
Sets the starting DN that searches for users will performed with. Searches will performed on the entire sub-tree under the base DN.- Parameters:
baseDN
- the starting DN used for performing searches.
-
getAlternateBaseDN
public LdapName getAlternateBaseDN()
Returns the alternate starting DN that searches for users will performed with. Searches will performed on the entire sub-tree under the alternate base DN after they are performed on the main base DN.- Returns:
- the alternate starting DN used for performing searches. If no alternate
DN is set, this method will return
null
.
-
setAlternateBaseDN
public void setAlternateBaseDN(LdapName alternateBaseDN)
Sets the alternate starting DN that searches for users will performed with. Searches will performed on the entire sub-tree under the alternate base DN after they are performed on the main base dn.- Parameters:
alternateBaseDN
- the alternate starting DN used for performing searches.
-
getUsersBaseDN
public LdapName getUsersBaseDN(String username)
Returns the BaseDN for the given username.- Parameters:
username
- username to return its base DN.- Returns:
- the BaseDN for the given username. If no baseDN is found,
this method will return
null
.
-
getGroupsBaseDN
public LdapName getGroupsBaseDN(String groupname)
Returns the BaseDN for the given groupname.- Parameters:
groupname
- groupname to return its base DN.- Returns:
- the BaseDN for the given groupname. If no baseDN is found,
this method will return
null
.
-
getAdminDN
public String getAdminDN()
Returns the starting admin DN that searches for admins will performed with. Searches will performed on the entire sub-tree under the admin DN.- Returns:
- the starting DN used for performing searches.
-
setAdminDN
public void setAdminDN(String adminDN)
Sets the starting admin DN that searches for admins will performed with. Searches will performed on the entire sub-tree under the admins DN.- Parameters:
adminDN
- the starting DN used for performing admin searches.
-
getAdminPassword
public String getAdminPassword()
Returns the starting admin DN that searches for admins will performed with. Searches will performed on the entire sub-tree under the admin DN.- Returns:
- the starting DN used for performing searches.
-
setAdminPassword
public void setAdminPassword(String adminPassword)
Sets the admin password for the LDAP server we're connecting to.- Parameters:
adminPassword
- the admin password for the LDAP server we're connecting to.
-
setConnectionPoolEnabled
public void setConnectionPoolEnabled(boolean connectionPoolEnabled)
Sets whether an LDAP connection pool should be used or not.- Parameters:
connectionPoolEnabled
- true if an LDAP connection pool should be used.
-
isConnectionPoolEnabled
public boolean isConnectionPoolEnabled()
Returns whether an LDAP connection pool should be used or not.- Returns:
- true if an LDAP connection pool should be used.
-
getSearchFilter
public String getSearchFilter()
Returns the filter used for searching the directory for users, which includes the default filter (username field search) plus any custom-defined search filter.- Returns:
- the search filter.
-
setSearchFilter
public void setSearchFilter(String searchFilter)
Sets the search filter appended to the default filter when searching for users.- Parameters:
searchFilter
- the search filter appended to the default filter when searching for users.
-
isSubTreeSearch
public boolean isSubTreeSearch()
Returns true if the entire tree under the base DN will be searched (recursive search) when doing LDAP queries (finding users, groups, etc). When false, only a single level under the base DN will be searched. The default istrue
which is the best option for most LDAP setups. In only a few cases will the directory be setup in such a way that it's better to do single level searching.- Returns:
- true if the entire tree under the base DN will be searched.
-
setSubTreeSearch
public void setSubTreeSearch(boolean subTreeSearch)
Sets whether the entire tree under the base DN will be searched (recursive search) when doing LDAP queries (finding users, groups, etc). When false, only a single level under the base DN will be searched. The default istrue
which is the best option for most LDAP setups. In only a few cases will the directory be setup in such a way that it's better to do single level searching.- Parameters:
subTreeSearch
- true if the entire tree under the base DN will be searched.
-
isFollowReferralsEnabled
public boolean isFollowReferralsEnabled()
Returns true if LDAP referrals will automatically be followed when found.- Returns:
- true if LDAP referrals are automatically followed.
-
setFollowReferralsEnabled
public void setFollowReferralsEnabled(boolean followReferrals)
Sets whether LDAP referrals should be automatically followed.- Parameters:
followReferrals
- true if LDAP referrals should be automatically followed.
-
isFollowAliasReferralsEnabled
public boolean isFollowAliasReferralsEnabled()
Returns true if LDAP alias referrals will automatically be followed when found.- Returns:
- true if LDAP alias referrals are automatically followed.
-
setFollowAliasReferralsEnabled
public void setFollowAliasReferralsEnabled(boolean followAliasReferrals)
Sets whether LDAP alias referrals should be automatically followed.- Parameters:
followAliasReferrals
- true if LDAP alias referrals should be automatically followed.
-
getGroupNameField
public String getGroupNameField()
Returns the field name used for groups. Value of groupNameField defaults to "cn".- Returns:
- the field used for groups.
-
setGroupNameField
public void setGroupNameField(String groupNameField)
Sets the field name used for groups.- Parameters:
groupNameField
- the field used for groups.
-
getGroupMemberField
public String getGroupMemberField()
Return the field used to list members within a group. Value of groupMemberField defaults to "member".- Returns:
- the field used to list members within a group.
-
setGroupMemberField
public void setGroupMemberField(String groupMemberField)
Sets the field used to list members within a group. Value of groupMemberField defaults to "member".- Parameters:
groupMemberField
- the field used to list members within a group.
-
getGroupDescriptionField
public String getGroupDescriptionField()
Return the field used to describe a group. Value of groupDescriptionField defaults to "description".- Returns:
- the field used to describe a group.
-
setGroupDescriptionField
public void setGroupDescriptionField(String groupDescriptionField)
Sets the field used to describe a group. Value of groupDescriptionField defaults to "description".- Parameters:
groupDescriptionField
- the field used to describe a group.
-
isPosixMode
public boolean isPosixMode()
Return true if the LDAP server is operating in Posix mode. By default false is returned. When in Posix mode, users are stored within a group by their username alone. When not enabled, users are stored in a group using their entire DN.- Returns:
- true if posix mode is being used by the LDAP server.
-
setPosixMode
public void setPosixMode(boolean posixMode)
Sets whether the LDAP server is operating in Posix mode. When in Posix mode, users are stored within a group by their username alone. When not enabled, users are stored in a group using their entire DN.- Parameters:
posixMode
- true if posix mode is being used by the LDAP server.
-
getGroupSearchFilter
public String getGroupSearchFilter()
Returns the filter used for searching the directory for groups, which includes the default filter plus any custom-defined search filter.- Returns:
- the search filter when searching for groups.
-
isFlattenNestedGroups
public boolean isFlattenNestedGroups()
Returns true if nested / complex / hierarchic groups should be should be flattened.This means: if group A is member of group B, the members of group A will also be members of group B
-
setFlattenNestedGroups
public void setFlattenNestedGroups(boolean flattenNestedGroups)
Set whether nested / complex / hierarchic groups should be should be flattened.- See Also:
isFlattenNestedGroups()
-
setGroupSearchFilter
public void setGroupSearchFilter(String groupSearchFilter)
Sets the search filter appended to the default filter when searching for groups.- Parameters:
groupSearchFilter
- the search filter appended to the default filter when searching for groups.
-
retrieveList
public List<String> retrieveList(String attribute, String searchFilter, int startIndex, int numResults, String suffixToTrim)
Generic routine for retrieving a list of results from the LDAP server. It's meant to be very flexible so that just about any query for a list of results can make use of it without having to reimplement their own calls to LDAP. This routine also accounts for sorting settings, paging settings, any other global settings, and alternate DNs. The passed in filter string needs to be pre-prepared! In other words, nothing will be changed in the string before it is used as a string.- Parameters:
attribute
- LDAP attribute to be pulled from each result and placed in the return results. Typically pulled from this manager.searchFilter
- Filter to use to perform the search. Typically pulled from this manager.startIndex
- Number/index of first result to include in results. (-1 for no limit)numResults
- Number of results to include. (-1 for no limit)suffixToTrim
- An arbitrary string to trim from the end of every attribute returned. null to disable.- Returns:
- A simple list of strings (that should be sorted) of the results.
-
retrieveList
public List<String> retrieveList(String attribute, String searchFilter, int startIndex, int numResults, String suffixToTrim, boolean escapeJIDs)
Generic routine for retrieving a list of results from the LDAP server. It's meant to be very flexible so that just about any query for a list of results can make use of it without having to reimplement their own calls to LDAP. This routine also accounts for sorting settings, paging settings, any other global settings, and alternate DNs. The passed in filter string needs to be pre-prepared! In other words, nothing will be changed in the string before it is used as a string.- Parameters:
attribute
- LDAP attribute to be pulled from each result and placed in the return results. Typically pulled from this manager.searchFilter
- Filter to use to perform the search. Typically pulled from this manager.startIndex
- Number/index of first result to include in results. (-1 for no limit)numResults
- Number of results to include. (-1 for no limit)suffixToTrim
- An arbitrary string to trim from the end of every attribute returned. null to disable.escapeJIDs
- Use JID-escaping for returned results (e.g. usernames)- Returns:
- A simple list of strings (that should be sorted) of the results.
-
retrieveSingle
public String retrieveSingle(String attribute, String searchFilter, boolean failOnMultipleResults)
Generic routine for retrieving a single element from the LDAP server. It's meant to be very flexible so that just about any query for a single results can make use of it without having to reimplement their own calls to LDAP.The passed in filter string needs to be pre-prepared! In other words, nothing will be changed in the string before it is used as a string.
- Parameters:
attribute
- LDAP attribute to be pulled from each result and placed in the return results. Typically pulled from this manager. Null means the the absolute DN is returned.searchFilter
- Filter to use to perform the search. Typically pulled from this manager.failOnMultipleResults
- It true, anIllegalStateException
will be thrown, if the search result is not unique. If false, just the first result will be returned.- Returns:
- A single string.
-
retrieveSingle
public String retrieveSingle(String attribute, String searchFilter, boolean failOnMultipleResults, LdapName baseDN)
Generic routine for retrieving a single element from the LDAP server. It's meant to be very flexible so that just about any query for a single results can make use of it without having to reimplement their own calls to LDAP.The passed in filter string needs to be pre-prepared! In other words, nothing will be changed in the string before it is used as a string.
- Parameters:
attribute
- LDAP attribute to be pulled from each result and placed in the return results. Typically pulled from this manager. Null means the the absolute DN is returned.searchFilter
- Filter to use to perform the search. Typically pulled from this manager.failOnMultipleResults
- It true, anIllegalStateException
will be thrown, if the search result is not unique. If false, just the first result will be returned.baseDN
- DN where to start the search. TypicallygetBaseDN()
orgetAlternateBaseDN()
.- Returns:
- A single string.
-
retrieveAttributeOf
public List<String> retrieveAttributeOf(String attributeName, LdapName dn) throws NamingException
Reads the attribute values of an entry with the given DN.- Parameters:
attributeName
- LDAP attribute to be read.dn
- DN of the entry.- Returns:
- A list with the values of the attribute.
- Throws:
NamingException
-
retrieveListCount
public Integer retrieveListCount(String attribute, String searchFilter)
Generic routine for retrieving the number of available results from the LDAP server that match the passed search filter. This routine also accounts for paging settings and alternate DNs. The passed in filter string needs to be pre-prepared! In other words, nothing will be changed in the string before it is used as a string.- Parameters:
attribute
- LDAP attribute to be pulled from each result and used in the query. Typically pulled from this manager.searchFilter
- Filter to use to perform the search. Typically pulled from this manager.- Returns:
- The number of entries that match the filter.
-
sanitizeSearchFilter
public static String sanitizeSearchFilter(String value)
Escapes any special chars (RFC 4515) from a string representing a search filter assertion value.- Parameters:
value
- The input string.- Returns:
- A assertion value string ready for insertion into a search filter string.
-
escapeForJNDI
public static LdapName escapeForJNDI(Rdn... rdn)
Returns a JNDI Name for an array of RDNs that is suitable to use to access LDAP through JNDI. This method applies JDNI-suitable escaping to each RDNWhen using the JNDI to access an LDAP service, you should be aware that the forward slash character ("/") in a string name has special meaning to the JNDI. If the LDAP entry's name contains this character, then you need to escape it (using the backslash character ("\")). For example, an LDAP entry with the name "cn=O/R" must be presented as the string "cn=O\\/R" to the JNDI context methods.
- Parameters:
rdn
- The names to escape (cannot be null).- Returns:
- A JNDI name representation of the values (never null).
- See Also:
- JNDI, Handling Special Characters
-
sanitizeSearchFilter
public static String sanitizeSearchFilter(String value, boolean acceptWildcard)
Escapes any special chars (RFC 4514/4515) from a string representing a search filter assertion value, with the exception of the '*' wildcard sign- Parameters:
value
- The input string.acceptWildcard
-true
to accept wildcards, otherwisefalse
- Returns:
- A assertion value string ready for insertion into a search filter string.
-
-