LDAP directive migration

This article contains information to help with migration from existing directives that use the mod_ibm_ldap module to the use of the open source LDAP modules (mod_authnz_ldap and mod_ldap). Migration will ensure future support for your LDAP configuration.

Attention: Although many of the mod_ibm_ldap directives are located in the ldap.prop file, the open source LDAP directives are all located in the httpd.conf file.

The open source LDAP features are provided by two modules. The AuthLDAP directives are provided by the mod_authnz_ldap module and the LDAP directives are provided by the mod_ldap module. Both modules need to be loaded for the LDAP features to be available. Throughout the following section the generic name, mod_ldap, is used to reference the open source LDAP modules.


ldapCodePageDir

The mod_ldap module does not provide a directive for specifying a codepages directory. The codepages directory is automatically installed in the correct directory, and the codepages directory cannot be moved from its installed location.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldapCodePageDir /location/of/codepages


LDAPConfigfile

The mod_ldap module does not provide a directive for specifying an LDAP configuration file. Although there is no mod_ldap directive for specifying the LDAP configuration file, if you want to put your LDAP configuration in a separate file, you might use the Apache include directive.

Convert this: 
ldapConfigFile ldap.prop

to this: 

Include /location/of/ldap_conf/apache_ldap.conf

Another alternative for migrating the mod_ibm_ldap LDAPConfigfile directive is to use the mod_authn_alias module AuthnProviderAlias container to create one or more groupings of ldap directives, and then use them by referencing the alias labels where required


LdapRequire

The mod_ldap module provides the require directive, with LDAP extensions, for LDAP authentication security.

If you used require valid-user previously for IBM HTTP Server, you may leave this require directive in place without modification. For the highest level of LDAP authentication security, you should migrate require valid-user to a more specific form. For additional information, see the Apache documentation for these require directives: ldap-user, ldap-dn, ldap-attribute, ldap-group, ldap-filter, and valid-user.

Convert this: 
LdapRequire filter "(&(objectclass=person)(cn=*)(ou=OurUnit)(o=OurOrg))" 
LdapRequire group MyDepartment

to this: 

require ldap-filter &(objectclass=person)(cn=*)(ou=OurUnit)(o=OurOrg)
require ldap-group cn=MyDepartment,o=OurOrg,c=US


ldap.application.authType

The mod_ldap module does not provide a directive specifying an authentication type. If a value is specified for the AuthLDAPBindDN directive, then basic authentication is enabled. If a value is not specified for the AuthLDAPBindDN directive, then what was previously the None authentication type for the mod_ibm_ldap module, or anonymous, is enabled.

If a value is specified for the LDAPTrustedClientCert directive, then the certificate authentication type is used automatically. 
ldap.application.authType=[None | Basic | Cert]


ldap.application.DN

The mod_ldap module provides the AuthLDAPBindDN directive to determine the application authentication type.

If a value is specified for the AuthLDAPBindDN directive, then the value of the authType directive is Basic. If the AuthLDAPBindDN directive is not enabled, then the value for the authType directive is None. If a value is specified for the LDAPTrustedClientCert directive, then the value for the authType directive is Cert.

Important: AuthLDAPBindDN also takes the place of ldap.application.authType. Convert this: 
ldap.application.DN=cn=ldapadm,ou=OurDirectory,o=OurCompany,c=US

to this: 

AuthLDAPBindDN "cn=ldapadm,ou=OurDirectory,o=OurCompany,c=US"


ldap.application.password

The mod_ldap module provides the AuthLDAPBindPassword directive to specify a bind password. The value is stored in the configuration file in plain text. Therefore, you should restrict access to the configuration file

Convert this: 
ldap.application.password=mypassword

to this: 

AuthLDAPBindPassword mypassword


ldap.application.password.stashFile

The mod_ldap module does not provide a directive for stashing the password. The directive AuthLDAPBindPassword is the only means to specify a password, and the value is stored in the configuration file in plain text. Therefore, you should restrict access to the configuration file.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.application.password.stashfile=/path/to/stashfile.sth


ldap.cache.timeout

The mod_ldap module provides the LDAPCacheTTL directive to specify a timeout for the LDAP cache. The LDAPCacheTTL directive is globally scoped and must be located at the highest level of the configuration file. This is different from the mod_ibm_ldap module, because the ldap.cache.timeout directive could be located anywhere in the configuration file.

Convert this: 
ldap.cache.timeout=60

to this: 

LDAPCacheTTL 60

The default value is 600 seconds.


ldap.group.dnattributes

The mod_ldap module provides the AuthLDAPSubGroupClass directive to specify the object classes which identify groups. For the mod_ibm_ldap module all values were specified on a single directive line; but for the mod_ldap module, the values can either be specified all on one line or on multiple lines, with the directive and one value on each line.

Convert this: 
ldap.group.dnattributes=groupOfNames GroupOfUniqueNames

to this: 

AuthLDAPSubGroupClass groupOfNames
AuthLDAPSubGroupClass groupOfUniqueNames

These are the default values.


ldap.group.memberattribute

The mod_ldap module provides the AuthLDAPSubGroupAttribute directive to specify the labels which identify the subgroup members of the current group. For the mod_ibm_ldap module, you could only specify one label; but for the mod_ldap module, we can specify multiple labels either by listing all of the labels in one directive line or by providing multiple directive lines, with each label on a separate directive line.

Convert this: 
ldap.group.memberattribute=member

to this: 

AuthLDAPSubGroupAttribute member
AuthLDAPSubGroupAttribute uniqueMember


ldap.group.memberattributes

The mod_ldap module provides the AuthLDAPGroupAttribute directive to specify the labels which identify any member of the current group, such as a user or subgroup. For the mod_ibm_ldap module, you specified all labels on one directive line; but for the mod_ldap module, you may either specify them all on one directive line or specify each label on a separate directive line.

Convert this: 
ldap.group.membreattributes=member uniqueMember

to this: 

AuthLDAPGroupAttribute member
AuthLDAPGroupAttribute uniqueMember


ldap.group.name.filter

The mod_ldap module does not provide a directive to specify separate user and group filters. The mod_ldap module uses the filter that is provided at the end of the AuthLDAPURL directive. We can use the AuthnProviderAlias container directive, which is provided by the mod_authn_alias module, to create separate my_ldap_user_alias and my_ldap_group_alias aliases containing the required ldap directives. We can then use your group alias in locations where authorization is controlled by way of group membership.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.group.name.filter=(&(cn=%v1)(|(objectclass=groupofnames)(objectclass=groupofuniquenames)))


ldap.group.search.depth

The mod_ldap module provides the AuthLDAPMaxSubGroupDepth directive to limit the recursive depth pursued before stopping attempts to locate a user within nested groups.

Convert this: 
ldap.group.search.depth=5

to this: 

AuthLDAPMaxSubGroupDepth 5

The default value is 10.


ldap.group.URL

The mod_ldap module does not provide a directive for specifying an LDAP server for authorizing a group membership that is different from the LDAP server that is used to authenticate users.

You must also specify the LDAP group server in the AuthLDAPURL directive for the container. Ensure that you specify the correct filter for each group.

ldap.group.URL=ldap://groups_ldap.server.org:389/o=OurOrg,c=US
ldap.group.URL=ldaps://groups_ldap.server.org:636/o=OurOrg,c=US


ldap.idleConnection.timeout

The mod_ldap module does not provide a directive for specifying when established connections to the LDAP server, that have gone idle, should timeout. The mod_ldap module automatically detects when the LDAP server expires connections, but does not cause connections to expire.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.idleConnection.timeout=60


ldap.key.file.password.stashfile

If no password is specified in the LDAPTrustedGlobalCert directive, the mod_ldap module automatically uses a /path/to/keyfile.sth file (assuming that /path/to/keyfile.kdb is the keyfile that is specified in the LDAPTrustedGlobalCert directive).

For information about how to specify the keyfile password, see the Apache information for the LDAPTrustedGlobalCert directive. The value is stored in the configuration file in plain text. Therefore, you should restrict access to the configuration file.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.key.file.password.stashfile=/path/to/ldap.sth


ldap.key.fileName

The mod_ldap module provides the LDAPTrustedGlobalCert directive to specify the keyfile to be used when loading certificates. The mod_ldap module also uses these directives to specify the password in plain text in the configuration file. Therefore, you should restrict access to the configuration file.

Convert this: 
ldap.key.filename=/path/to/keyfile.kdb

to this: 

LDAPTrustedGlobalCert CMS_KEYFILE /path/to/keyfile.kdb myKDBpassword

LDAPTrustedGlobalCert SAF saf_keyring


ldap.key.label

The mod_ldap module provides the LDAPTrustedClientCert directive to specify which certificate to use from the KDB keyfile. If the default certificate is used, then you do not need to specify a value for these directives.

Convert this: 
ldap.key.label=certname_from_kdb

to this: 

LDAPTrustedClientCert CMS_LABEL certname_from_kdb


ldap.ReferralHopLimit

The mod_ldap module provides the LDAPReferralHopLimit directive to limit the number of referrals to chase before stopping attempts to locate a user in a distributed directory tree.

Convert this: 
ldapReferralHopLimit 5

to this: 

LDAPReferralHopLimit 5

The default value is 5.


ldapReferrals

The mod_ldap module provides the LDAPReferrals directive to enable or disable referral chasing when locating users in a distributed directory tree.

Convert this: 
ldapReferrals On

to this: 

LDAPReferrals On

The default value is On.


ldap.realm

The mod_ldap module provides the AuthName directive to specify the authorization realm.

Convert this:
ldap.realm=Some identifying text

to this:

AuthName Some identifying text


ldap.search.timeout

The mod_ldap module provides the LDAPSearchTimeout directive to specify when a search request should be abandoned.

Convert this:
ldap.search.timeout=10

to

LDAPTimeout 10

The default value is 10 seconds.


ldap.transport

The mod_ldap module provides the LDAPTrustedMode directive to specify the type of network transport to use when communicating with the LDAP server.

If no port is specified on the AuthLDAPURL directive, then the mod_ldap module ignores the LDAPTrustedMode directive, and specifies a network transport value of SSL. For more information, see the Apache documentation for the LDAPTrustedMode and AuthLDAPURL directives.

We can specify a value for the following network transport types.

  • None or TCP, which indicates no encryption. If no port is specified on the AuthLDAPURL directive, then port 389 is used.

  • SSL. If a value of None is specified, then port 636 is used.

  • TLS or STARTTLS. These open source types are not supported by IBM HTTP Server.

Convert this: 

ldap.transport=TCP (or SSL)

to this: 

LDAPTrustedMode NONE (or SSL)

If an ldaps://URL is specified, the mode becomes SSL and the setting of LDAPTrustedMode is ignored.


ldap.URL

The mod_ldap module provides the AuthLDAPURL directive for specifying the LDAP server hostname and port as well as the base DN to use when connecting to the server. The mod_ldap module also provides a means for specifying the user attribute, scope, user filter, and transport mode. For more information, see the Apache documentation for the AuthLDAPURL directives.

Convert this: 
ldap.URL=ldap://our_ldap.server.org:389/o=OurOrg,c=US
ldap.URL=ldaps://our_ldap.server.org:636/o=OurOrg,c=US

to this: 

AuthLDAPURL ldap://our_ldap.server.org:389/o=OurOrg,c=US?cn?sub?(objectclass=person)
AuthLDAPURL ldaps://our_ldap.server.org:636/o=OurOrg,c=US?cn?sub?(objectclass=person)


ldap.user.authType

The mod_ldap module does not provide a directive for specifying a user authentication type. The mod_ldap module authenticates users based on the user ID and password credentials provided.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.user.authType=Basic  [Basic | Cert | BasicIfNoCert]


ldap.user.cert.filter

The mod_ldap module does not provide a directive for filtering client certificates. The mod_ldap module does not work directly with client certificates.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.user.cert.filter=(&(objectclass=person)(cn=%v1)(ou=%v2)(o=%v3)(c=%v4))


ldap.user.name.fieldSep

The mod_ldap module does not provide a directive for parsing provided credentials into subcomponents. The mod_ibm_ldap module uses the ldap.user.name.fieldSep directive to specify the separator characters used to parse the credentials into the %v1, %v2, ...%vN tokens.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.user.name.fieldSep=/ ,


ldap.user.name.filter

The mod_ldap module does not provide a directive for specifying the user name filter. The mod_ldap module specifies the user name filter as part of the AuthLDAPURL directive.

The AuthLDAPURL directive combines the user attribute specified in the directive with the provided filter to create the search filter. The provided filter follows the standard search filter specification. The mod_ldap module also does not provide the %vx token parsing function available for the mod_ibm_ldap module.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.user.name.filter=(&(objectclass=person)(cn=%v1 %v2))


ldap.version

The mod_ldap module does not provide a directive for specifying the LDAP version. The mod_ldap module uses only LDAP version 3.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.version=2  (or 3)


ldap.waitToRetryConnection.interval

The mod_ldap module does not provide a directive for specifying an amount of time before retrying a failed connection attempt. The mod_ldap module does not have a timed delay between connection retries when a connection attempt fails. The connection attempt is automatically retried for a maximum of 10 times before a request fails.

When a new request needs to access the same LDAP server, the connection is retried for a maximum of 10 times again. The retry throttle is based on the volume of new requests sent to the LDAP server.

This mod_ibm_ldap directive has no mod_ldap equivalent:
ldap.waitToRetryConnection.interval=300


Related reference