Authenticating with LDAP on IBM HTTP Server using mod_ibm_ldap (Distributed systems)

This section describes how to configure LDAP to protect files on IBM® HTTP Server.

Deprecated feature: The mod_ibm_ldap module is provided with this release of IBM HTTP Server for compatibility with previous releases. If you are using the mod_ibm_ldap module for your LDAP configuration, you must migrate existing configurations to use the mod_authnz_ldap and mod_ldap modules to ensure future support for your LDAP configuration. See the topic Authenticating with LDAP on IBM HTTP Server using mod_ldap for a description of how to use the mod_ldap module.

Before you begin

The LDAP module is not loaded into IBM HTTP Server by default. Without the LoadModule directive, the LDAP features are not available for use. In order to enable the LDAP function, add a LoadModule directive to the IBM HTTP Server httpd.conf file as follows:

LoadModule ibm_ldap_module modules/IBMModuleLDAP.dll

LoadModule ibm_ldap_module modules/mod_ibm_ldap.so

If you have the LDAP client installed on your computer, you can use ldapsearch as a tool to test the values you intend to use for the various settings.

About this task

See Lightweight Directory Access Protocol (LDAP) directives to obtain detailed descriptions of the LDAP (mod_ibm_ldap) directives.

Procedure

Edit the httpd.conf IBM HTTP Server configuration file.
Determine the resource you want to limit access to.
For example: <Directory "/secure_info">.
Add directives in httpd.conf to the directory location (container) to be protected with values specific to your environment. For example:
- LdapConfigFile path_to_ldap.prop
- AuthType Basic
- AuthNameTitle of your protected Realm
- Require valid-user
There are three options for how to use IBM HTTP Server to authenticate with your existing LDAP installation.
- Authorization based on LDAP group membership.
  Use LDAP to check user passwords and verify that the user exists in a group defined in LDAP.
  Note: The membership that identifies the user as being able to access the resource is a part of the group, not part of the user's own LDAP entry.
  
  For example, to restrict access to a group, add the following directive:
```
LDAPRequire group grp1
```
  For this form of LDAPRequire, you must have groups configured in your LDAP repository that conform to the following rules (using the example group name grp1):
  - There is an entry in your LDAP repository that matches the following search filter, where the values groupofnames and groupofuniquenames are example values specified in ldap.group.dnattributes.
    Note: The proper value of ldap.group.dnattributes is a list of what objectclasses signify is a group in your LDAP schema.
```
ldapsearch ... "(&(cn=grp1)(|(objectclass=groupofnames)
(objectclass=groupofuniquenames)))"
```
  - As part of the LDAP entry for "grp1," there are a series of attributes that match the following, where the values member and uniquemember are example values of ldap.group.memberAttributes.
    Note: The proper value of ldap.group.memberAttributes is a list of what objectclasses signify is a membership in a group. The values of these entries are the Distinguished Names (DN) of your users.
```
ldapsearch ... "(&(cn=grp1)(|(objectclass=groupofnames)
(objectclass=groupofuniquenames)))" member uniquemember 
```
    Example:
```
ldapsearch -x -h myldapserver -D cn=root -w rootpw
"(&(cn=grp1)(|(objectclass=groupofnames)(objectclass=groupofuniquenames)))" 
member uniquemember
```
```
dn: cn=group1,ou=myunit,o=myorg,c=US 
member: cn=user1, ou=otherunit, o=myorg, c=US
member: cn=user12, ou=otherunit, o=myorg, c=US 
```
    If an object of the type listed in ldap.group.dnattributes is a member of the group being searched, then it will be recursively searched in the same fashion, up to a depth of ldap.group.search.depth
  - First IBM HTTP Server uses the ldap.group.name.filter and ldap.user.cert.filter to translate the CN provided for the user and the group into distinguished names (DN). Next, IBM HTTP Server searches using the group DN as a base for entries whose value is the user DN.
    Example:
```
ldapsearch ... -b "cn=grp1,ou=myunit,o=myorg,c=US" 
"|((member=cn=user1,ou=otherunit,o=myorg,c=US) 
(uniquemember=cn=user1,ou=otherunit,o=myorg,c=US))"
```
- Authorization based on LDAP attributes of user. Use LDAP to check user passwords and verify that the user matches a set of attributes (the attribute that identifies the user as being able to access the resource is a part of the users own LDAP entry).
  Example:
```
LDAPRequire filter "(&(jobtitle=accountant)(location=newyork))"
```
  To use this form of LDAPRequire, the IBM HTTP Server must use the ldap.user.cert.filter to translate the CN provided for the user into a DN. IBM HTTP Server must also search using the user DN as a base and use the search filter provided in the LDAPRequire directive. If any results are returned, authorization succeeds.
  
  Example:
```
ldapsearch ... -b "cn=user1,ou=otherunit,o=myorg,c=US" "(&(jobtitle=accountant)
(location=newyork))" 
```
  Some attributes (sometimes called Dynamic Roles) in LDAP are calculated dynamically by the LDAP server and might have different semantics that are not valid in a search filter. Such values would fail if used in the preceding example and cannot be used for authorization on IBM HTTP Server.
- Authentication only: Use LDAP to check user passwords only.
  You can use the Require directive to limit to specific users or maintain a flat group file using AuthGroupFile.
Edit the ldap.prop configuration file. If you do not have one yet, you can use the ldap.prop.sample file that ships with IBM HTTP Server. If you have questions about the correct values, check with your LDAP server administrator. Update the following directives with values that are correct for your environment:
1. Enter the Web server connection information.
2. When using SSL, or LDAPS, or LDAP over SSL:
  - Change ldap.transport to an SSL value
  - Change ldap.URL to include the LDAPS protocol and the proper port value, for example, 636.
  - Configure the SSL key database to be used, for example:
```
ldap.key.fileName=/path_to/key.kdb
```
```
ldap.key.file.password.stashFile=/path_to/stashfile
```
    Where stashfile is created by the bin/ldapstash command.
```
ldap.key.label=label
```
    Where label is the value appearing in IKEYMAN for the referenced key.kdb.

Results

Searches that use the mod_ibm_ldap directives maintain a pool of server connections that authenticate as the ldap.application.dn user. The first connection is created when the first LDAP-protected request is received. Connections will be held open a specified number of seconds (ldap.idleConnection.timeout) for subsequent searches on that connection or connections for other requests.

If you are reading logs or looking at an IP trace, the following sequence of events should occur:

IBM HTTP Server starts.
If LDAP_TRACE_FILE is set, it will have a few entries for LDAP_obtain_config
The first request for LDAP-protected resource is received.
IBM HTTP Server binds to LDAP using the ldap.application.dn username and the password stashed in ldap.application.password.stashFile (Application Connection)
IBM HTTP Server performs a search over this connection to translate the username typed in by the user, or the contents of their client certificate, into a Distinguished Name (DN) using the user.*.filter settings.
IBM HTTP Server binds to the LDAP server as username/password provided by the client to check authentication (This is a user connection to the LDAP server)
If any LDAPRequire directives are in effect for this request, IBM HTTP Server processes them in the manner described in the preceeding procedure.
IBM HTTP Server unbinds the user connection
The application connection is maintained for the next request