By default GemFire XD initiates a search in LDAP to obtain the full DN of a simple user
name. You can configure the GemFire XD search behavior as necessary depending on whether or
not your LDAP server supports anonymous search.
Understanding LDAP Search Behavior
In an LDAP system, users are hierarchically organized in the directory as a set of
entries. An
entry is a set of name-attribute pairs identified by a unique
name, called a DN (distinguished name). An entry is unambiguously identified by a
DN, which is the concatenation of selected attributes from each entry in the tree
along a path leading from the root down to the named entry, ordered from right to
left. For example, a DN for a user might look like this:
cn=mary,ou=People,dc=example,dc=com
uid=mary,ou=People,dc=example,dc=com
The allowable entries for the name are defined by the entry's objectClass.
An LDAP client can bind to the directory (successfully log in) if it provides a user
ID and password. The user ID must be a DN, the fully qualified list of names and
attributes. This means that the user must provide a very long name.
Typically the user knows only a simple user name (for example, the first part of the
DN above, mary). With GemFire XD, a user does not need to specify the full DN
because an LDAP client (GemFire XD itself) can go to the directory first as a guest
or anonymous user, search for the full DN, and then rebind to the directory using
the full DN to authenticate the user.
By default GemFire XD initiates a search for a full DN before binding to the
directory and using the full DN for user authentication. GemFire XD does not
initiate a search only in the following cases:
- When the gemfirexd.auth-ldap-search-filter property is set to
gemfirexd.user.
- When a user DN has been cached
locally for the specific user via the
gemfirexd.user.UserName property.
Properties for Configuring LDAP Search
Some systems permit anonymous searches, while others require a user DN and password.
You can specify a specific DN and password to use for the search by configuring the
properties described below. In addition, you can limit the scope of the search by
specifying a filter (definition of the object class for the user) and a base
(directory from which to begin the search) by using the properties described below.
Note: Each of the following properties must be specified as a system property
when you boot a GemFire XD peer. For example, when booting a new GemFire XD
server with gfxd, use the command-line option
-J-Dgemfirexd.auth-ldap-search-base=searchbase.
- gemfirexd.auth-ldap-search-dn
specifies the DN with which to bind (authenticate) to the server when
searching for user DNs. This property is required if your LDAP provider does
not support anonymous binding. If your LDAP provider supports anonymous
binding, then this parameter is optional.
If you configure this property,
the value must be a valid DN recognized by the directory service, and
the DN must have the authority to search for entries. If you do not
configure this property, it defaults to anonymous search using the root
DN specified by
gemfirexd.auth-ldap-search-base
property. For example:
uid=guest,dc=example,dc=com
- gemfirexd.auth-ldap-search-pw
specifies the password for the guest user DN specified in gemfirexd.auth-ldap-search-dn. If
you do not configure this property, GemFire XD defaults to using anonymous
search with the root DN specified by the gemfirexd.auth-ldap-search-base property.
- gemfirexd.auth-ldap-search-base specifies
the root DN of the point in your hierarchy from which to begin a guest
search for the user's DN. For example:
ou=people,dc=example,dc=com
To narrow the
search, you can specify a user's objectClass.
Note: When
using Netscape Directory Server you can set this property to the root
DN, the special entry to which access control does not apply.
If you configure gemfirexd.auth-ldap-search-base, then
your LDAP server must either support anonymous binding or you must
configure both gemfirexd.auth-ldap-search-dn
and gemfirexd.auth-ldap-search-pw to
provide the DN to use for searching for entries.
- gemfirexd.auth-ldap-search-filter
specifies a logical expression that describes what constitutes a user for
your LDAP directory service. The default value of this property is
objectClass=inetOrgPerson. If you include the token
%USERNAME% in the filter definition, then GemFire XD
replaces the token with the user name that is being authenticated. If you do
not provide a search-filter, then GemFire XD uses the default search filter:
(&(objectClass=inetOrgPerson)(uid=%USERNAME%))
If you provide a search filter that does not have the
%USERNAME% token, then GemFire XD prepends the
token to the default search filter. For example:
(&(<provided_filter>)(objectClass=inetOrgPerson)(uid=%USERNAME%))
Example LDAP Search Configuration
Consider the following LDAP search invoked using the OpenLDAP
ldapsearch tool:
ldapsearch -b ou=users,dc=domain,dc=com /* base DN */
-x /* non-SASL plain-text authentication */
-D uid=test,ou=ldapTesting,dc=domain,dc=com /* bind DN */
-w test /* bind password */
"(&(objectClass=user)(uid=user1))" /* filter */
To configure the above search with GemFire XD you would define the properties:
gemfirexd.auth-ldap-search-base=ou=users,dc=domain,dc=com
gemfirexd.auth-ldap-search-filter=(&(objectClass=user)(uid=%USERNAME%))
gemfirexd.auth-ldap-search-dn=uid=test,ou=ldapTesting,dc=domain,dc=com
gemfirexd.auth-ldap-search-pw=test