Configuring GemFire XD to Search for DNs

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