HTTP Server for i

Secure, powerful, and complete

Overview

Getting Started

Documentation

Support

Introduction

This article describes why a user might want to use LDAP with their HTTP server, and also provides some tips on configuring the HTTP server to take advantage of LDAP. It will cover Protection statements and masks, group files, the LDAP configuration, and using LDAP over an SSL connection. 

HTTP and LDAP

Lightweight Directory Access Protocol (LDAP) is a directory service protocol that runs over TCP/IP,using non-secure or secure sockets (SSL). The LDAP directory service follows a client/server model, where one or more LDAP servers contain the directory data. This allows any LDAP-enabled application to store information once, such as user authentication information, and other applications using the LDAP server are able to request that information. The HTTP server can act as a client of an LDAP server, making requests for information. 

The HTTP Server uses the LDAP directory primarily for authentication. One of the advantages of using the LDAP server for authentication is that it allows the information to be shared by multiple LDAP clients, and stores the information in a platform independent fashion. This can prevent information from being duplicated within a network. The LDAP directory can also scale quite large, storing thousands or millions of entries. The HTTP server can take advantage of this size, and service much larger numbers of authenticated users than can be handled by other methods. 

The HTTP Server can also make requests of the LDAP server for the locations of HTTP configuration information that is stored on the LDAP server. This article will not specifically cover this portion of the LDAP support, but the information contained here may assist in using the LDAPInclude directive. 

Using the LDAPInfo directive

The LDAPInfo directive is used to provide the HTTP server with information about the LDAP servers in which LDAP configuration and authentication information are stored. This directive must occur before any LDAPInclude directives or protection setups which refer to this named setup. The LDAPInfo directive is a container that holds subdirectives that describe details of the LDAP directory and how to access it. This is the primary method to inform the HTTP server of the location of the directory, and how the entries in that directory are to be searched. 

Each LDAPInfo directive is given a label-name, and this label is used in Protection or LDAPInclude statements so the HTTP server will know the LDAP server from which to request the information. There can be multiple LDAPInfo statements in a single HTTP server configuration file. All of the LDAP subdirectives are described in the HTTP Server Webmaster's Guide. The following sections describe additional information about these directives that may be useful in using the HTTP server in conjunction with an LDAP server. 

Timeout Subdirectives

Any time the HTTP server attempts to contact an external server, there is the possibility that the connection will take a long time to complete. In the case where the connection is to an LDAP server, the requests could also take a long time. Depending on how the LDAP directory is built, it's location in the network, and on the size of the directory and it's entries, the default search timeouts may not be long enough. These subdirectives should be adjusted based on the performance of the LDAP server and the size of the directory to be searched. In general, the default value for SearchTimeout should be sufficient for most searches. 

Following is a list of the LDAP timeout subdirectives and their default values:

• IdleConnTimeout 10 Minutes
• WaitToRetryTimeout 30 Seconds
• SearchTimeout 2 Minutes
• CacheTimeout 5 Minutes

ServerAuthType

The ServerAuthType subdirective specifies the authentication type that will be used to connect the HTTP server to the LDAP server. The two valid values are None and Basic.

• None - allows for anonymous access if supported by the LDAP server.
• Basic - requires the IBM HTTP server to provide its distinguished name and password for authentication. The HTTP server uses the distinguished name in the ServerDN directive, and the password that is provided in the ServerPasswordStashFile directive.

ServerPasswordStashFile

This directive is used to specify the name of the file that contains the encrypted password to access the LDAP server. If Basic server authentication is required, a password should be entered on the web-based HTTP Configuration and Administration GUI Create/Change LDAP server setup forms. The configuration file will then be updated with the stash file name. 

Client Connection Subdirectives

The UserNameFilter and GroupNameFilter subdirectives are used to supply a template that is used to convert the user name or the group to a search filter for an LDAP entry that uniquely identifies a user or group. It's important that the LDAP search return a unique entry. If the filter returns more than one entry, authentication will fail since the HTTP server will not know which entry to use. 

For example, if the user entered "Ma Jo" with the default UserNameFilter, the search string would be "(&(objectclass=person)(cn=Ma* Jo*))". With this filter, the entries "cn=Marvin Jones" and "cn=Mary Jordan" would both match. The HTTP server would then fail authentication, since it cannot determine which user is attempting to access resources. 

The HTTP server provides default values for these filters, and if they are not sufficient to determine a unique entry, they should be changed to match the LDAP directory that will be used. 

The default UserNameFilter is:

UserNameFilter "(&(objectclass=person)(cn=%v1* %v2*))"

The default GroupNameFilter is: 

GroupNameFilter "(&(cn=%v1)(|(objectclass=groupofnames) (objectclass=groupofuniquenames)))"

Following is an example LDAPInfo directive, that will allow valid users to be checked against a group to determine if they are allowed to access a resource. The various timeout subdirectives are not described in the interest of saving space. The default timeout values will be used in this case. 
 

LDAPInfo LDAPServerA {
Host ldap.ibm.com
Transport TCP
ClientAuthType Basic
ServerAuthType Basicv ServerDN "cn=Administrator"
ServerPasswordStashFile /QIBM/USERDATA/HTTPSVR/LDAP/CONFIG/LDAPSERVERA.STASH
UserSearchBase "ou=department,o=company,c=US"
UserNameFilter "(&(objectclass=person)(cn=%v1 %v2))"
GroupSearchBase "ou=department,o=company,c=US"
GroupNameFilter "(&(objectclass=groupofnames)(cn=%v1))
GroupMemberAttrs "member" }

LDAP and the Protection directives

The protection setups that are used when using LDAP for authentication are generally the same as those used for other authentication methods. There are a few differences that should be described when using the protection subdirectives with LDAP and they are described below. For more details on protection, refer to the HTTP Server Documentation.

PasswdFile and GroupFile directives

To indicate to the HTTP server that LDAP will be used for authentication, use the string %%LDAP: labelname%% on the PasswdFile and GroupFile directives. When this string is specified on the PasswdFile directive, it will cause the HTTP server to contact the LDAP server described by the LDAP setup labelname to validate a user. When this string is used on the GroupFile directive, the HTTP server will know to contact LDAP to determine if the user is a valid member of a group specified on a mask directive or in an ACL file. When using the %%LDAP: labelname%% value on a GroupFile directive, the corresponding LDAPInfo statement must have appropriate GroupSearchBase, GroupNameFilter and GroupMemberAttrs directives set so that the HTTP server can build a specific LDAP search request to locate the group information and validate whether the user is a member of the group. 

Mask directives: Mask, GetMask, PutMask, PostMask, DeleteMask

The way to use LDAP users and groups on the various mask directives is very similar to the ways that are described in the HTTP Server for i WebMaster's Guide chapter on Protecting Your Server. To use an LDAP group name that contains the users you would like to authorize to this function, simply list the common name (cn) of the group defined in the LDAP directory . Multiple group names can be used, although they must all be on the same LDAP server. 

For example, this Protection setup will allow only members of the "exclusive" group to access the resource protected by this statement. The LDAP server described by the LDAPInfo LDAPServerA directive will be used to determine if the user is valid and a member of the group. 

Protection ExclusiveExample {
PasswdFile %%LDAP:LDAPServerA%%
GroupFile %% LDAP:LDAPServerA%%
ACLOverride Off
GetMask Exclusive@(*)
AuthType Basic
ServerID Exclusive_Group_Protection
UserID %%SERVER%%
}

To allow members of the group Restricted to access the resource, add it to the GetMask directive, as below: 

GetMask Exclusive@(*),Restricted

As for all users and groups on a mask directive, the @(*) is optional - if an address template is not supplied, it is implied that the resource is not restricted by the address of the client requester. 

LDAP users may also be specified on Mask statements. The user information that the user typed to authenticate will be compared to the user name on the mask statement, just as a validation list entry or an iSeries user profile would be. The previous example could be rewritten to restrict access to just two users by changing the GetMask directive, as follows: 

Protection ExclusiveExample {
PasswdFile %%LDAP:LDAPServerA%%
GroupFile %% LDAP:LDAPServerA%%
ACLOverride Off
GetMask "Marvin Jones", "Mary Jordan"
AuthType Basic
ServerID Exclusive_Group_Protection
UserID %%SERVER%%
}

Note that in this case, the names must be in quotes because they use both names, with an space separating them. If the user only had to enter one name, the statement could be rewritten as: 

GetMask Majones, Majordan

The iSeries uses Digital Certificate Manager (DCM) to associate applications with certificates. Where other platforms use keys and key ring files, the iSeries uses Application IDs to associate an application with a key database. When a connection to the LDAP server is made, the HTTP server uses the certificate associated with it's Application ID to do server authentication, which will verify whether the LDAP server is an application that the HTTP server can trust. 

The HTTP server will obtain an Application ID for the server instance when "Allow SSL Connections" is selected on the Security Configuration form. In order to use this Application ID, it must be associated with a certificate. Before you start your server, use the Digital Certificate Manager web page (there is a link to it from the HTTP Server Configuration and Administration page) to associate this ID with a certificate. 

Selecting "Allow SSL Connections" will cause the HTTP server to accept SSL connections from clients. If this is not desired, then deselect this option once the Application ID is obtained. The application ID will still be valid, and can still be used when opening connections to the LDAP server. If editing the configuration using WRKHTTPCFG, never delete the AppName directive. 

To communicate with a secure LDAP server, the HTTP server's LDAPInfo configuration must specifiy Transport SSL. If SSL is selected, the default Port will be 636. This value should match the SSL port of the LDAP server. 

Following are snippets of a configuration file where the HTTP server must use a secure LDAP server for user authenticiation, but the HTTP server will not accept SSL connections from clients The certificate associated with the application ID QIBM_HTTP_SERVER_LDAPINSTANCE will be used to verify that the LDAP server is an application that the HTTP server can trust. 

#Do not change or delete the following AppName directive
AppName QIBM_HTTP_SERVER_LDAPINSTANCE
SSLMode Off
SSLPort 443
SSLClientAuth Off
LDAPInfo LDAPServerA {
Host ldap.ibm.com
Transport SSL
ClientAuthType Basic
ServerAuthType Basic
ServerDN "cn=Administrator"
ServerPasswordStashFile /QIBM/USERDATA/HTTPSVR/LDAP/CONFIG/LDAPSERVERA.STASH
UserSearchBase "ou=department,o=company2,c=US"
UserNameFilter "(&(objectclass=person)(cn=%v1))"
GroupSearchBase "ou=department,o=company2,c=US"
GroupNameFilter "(&(objectclass=groupofnames)(cn=%v1))
GroupMemberAttrs "member"
}

To accept SSL connections from clients, the directives SSLMode and SSLClientAuth should be changed to On. 

Setting up an LDAP server on the iSeries

Operations Navigator is used to set up an iSeries LDAP directory server. Directory services (LDAP) supplies a configuration wizard in Operations Navigator that will walk you through the necessary configuration steps. To use this wizard, for your system select Network -> Servers -> TCP/IP. This should show you a list of TCP/IP servers. Select Directory, then Configure from the File menu. You will need to know how your directory tree is formatted, since you will have to supply a suffix or suffixes that describe your directory when configuring your server. You will also have to supply the iSeries library where your directory entries will reside, and the port that you will be using to communicate with clients of LDAP. 

To enable SSL, you must bring up the Properties dialog. If there is not currently a certificate associated with the LDAP application, then the SSL Enable option will be grayed out. To enable it, you must click on the Digital Certificate Manager button to use DCM to associate a certificate with the LDAP application. The LDAP server Application ID is QIBM_GLD_DIRSRV_SERVER. Select this application, then select the "Work with system certificate button". From there you can associate this application with a certificate. Once that is complete, the "SSL Enable" option in the Directory Properties should be available to be selected, and the SSL Port can be changed if necessary. 

More information on Directory Services (LDAP) can be found in the IBM Directory Server for i5/OS (LDAP).