The PAC-LDAP authorization module enables Caching Proxy to access a Lightweight Directory Access Protocol (LDAP) server when performing authorization or authentication routines. The module consists of two component sets: a pair of shared libraries that add LDAP functionality to Caching Proxy API and a Policy Authentication Control (PAC) daemon. A ServerInit directive within the ibmproxy.conf file instructs the shared library to initialize one or more PAC daemons when Caching Proxy starts up. The shared libraries read a paccp.conf file to determine the number and characteristics of the PAC daemons. During initialization, the daemon reads the pac.conf file for configuration directives and the pacpolicy.conf for policy information. Then, either an Authentication directive within the ibmproxy.conf file instructs the proxy server to call the shared library whenever authentication is required, or an Authorization directive usurps Caching Proxy workflow during standard HTTP request processing.
The process of authentication determines if a supplied set of credentials - user name and password - are valid. This process includes verifying that a user is in the registry and that the supplied password matches the password stored in the registry. These are the actions performed by using the PAC-LDAP module during the authentication step.
When the PAC-LDAP authorization module is enabled for authentication, it becomes the default repository from which user IDs, passwords, and groups are retrieved. As an HTTP request passes through Caching Proxy workflow, each Protect directive compares the requested URL to its request template. If a match occurs, the Protect directive invokes a protection schema, which includes the server ID, the type of authentication to use, masking rules to apply to the requesting client, and the locations of the passwords and groups files. If the passwords file is not defined, then the user ID and password are retrieved via the PAC-LDAP authorization module. Type 0, 1, 2, and 3 policies define authentication schemes. If authentication passes, the request is served; otherwise, Caching Proxy returns a 401 error to the client.
The process of authorization determines if a user has the necessary permission to access a protected resource. When the PAC-LDAP module is used, this includes applying authorization rules residing in the pacpolicy.conf file for the HTTP request.
When the PAC-LDAP authorization module is enabled for authorization, authorization rules within the pacpolicy.conf file are applied to the HTTP request. As the HTTP request passes through Caching Proxy workflow, each Protect directive compares the requested URL to its request template. If a match occurs, the Protect directive invokes a protection schema. In this case, the protection schema is the authorization routine usurped by the PAC-LDAP authorization module. The Authorization directive compares the requested URL to its request template, and, if a match occurs, the PAC-LDAP authorization module is invoked. Type 4 policies defined within the pacpolicy.conf file further refine the authentication required for various URL requests.
LDAP provides interactive access to X.500 directories with a minimal consumption of system resources. The IANA has assigned TCP port 389 and UDP port 389 to LDAP. For more information, refer to RFC 1777, which defines LDAP.
Examples of supported LDAP clients are: the IBM Tivoli LDAP client and the IBM SecureWay LDAP client.
All components of the PAC-LDAP authorization module are automatically installed when the Caching Proxy system of WebSphere® Application Server, Version 8.5 is installed. On Linux and UNIX systems, a Caching Proxy library (./lib/) directory, a PAC-LDAP authorization module library (./lib/plugins/pac/) directory, a binary (./bin/) directory, and a configuration (./etc/) directory are created within the /opt/ibm/edge/cp/ directory. Symbolic links are then created from the /usr/lib/, /usr/sbin/, and /etc directories to these product-specific ones.
Directory structure
Linux and UNIX directory | Windows directory | Content |
---|---|---|
/opt/ibm/edge/cp | C:\Program Files\IBM\edge\cachingproxy\cp | Caching Proxy base directory (cp_root) |
cp_root/sbin | C:\Program Files\IBM\edge\cachingproxy\cp\Bin\ | Caching Proxy binaries and scripts |
/usr/sbin/ | Symbolic links to cp_root/sbin/ | |
cp_root/etc/ | C:\Program Files\IBM\edge\cachingproxy\cp\etc\ | Caching Proxy configuration files |
/etc/ | Symbolic links to cp_root/etc/ | |
cp_root/lib/ | C:\Program Files\IBM\edge\cachingproxy\cp\lib\plugins\ | Caching Proxy libraries |
cp_root/lib/ plugins/pac/ | C:\Program Files\IBM\edge\cachingproxy\cp\lib\plugins\pac\ | PAC-LDAP authorization module libraries |
/usr/lib/ | Symbolic links to cp_root/lib/ and cp_root/lib/ plugins/pac/ | |
cp_root/server_root/pac/data/ | C:\Program Files\IBM\edge\cachingproxy\cp\server_root\pac\data\ | PAC-LDAP authorization module data storage |
cp_root/server_root/ pac/creds/ | C:\Program Files\IBM\edge\cachingproxy\cp\server_root\pac\creds\ | PAC-LDAP authorization module credentials |
LDAP Plug-in files
Linux and UNIX file name | Windows file name | Description |
---|---|---|
libpacwte.so | pacwte.dll | shared library |
libpacman.so | pacman.dll | shared library |
pacd_restart.sh | pacd_restart.bat | PAC daemon restart script |
paccp.conf, pac.conf, pacpolicy.conf | paccp.conf, pac.conf, pacpolicy.conf | configuration and policy files |
To enable secure sockets layer (SSL) connections between the PACD daemon and the LDAP server, you should install the GSKit package that is required by the LDAP client package. GSKit 7 is required and provided by default on the Caching Proxy machine, but it may not be the version that is required by the LDAP client on the machine. It is possible to use different GSKit versions on the same machine for different processes.
Place the GSKit key file to $pacd_creds_dir/pac_keyring.kdb and the password to $pacd_creds_dir/pac_keyring.pwd.
On Linux systems, the LD_PRELOAD environment variable must be configured as follows in order to enable SSL connections between the PACD daemon and the LDAP server. Set the variable to the following value:
LD_PRELOAD=/usr/lib/libstdc++-libc6.1-1.so.2
The GSKit requirement referenced previously in this section also applies to Linux systems.
On Red Hat Enterprise Linux 4.0 systems, the PACD process does not start when Caching Proxy is configured to use the ITDS 6.0 LDAP plug-in for authentication. The following error message results:
"error while loading shared libraries:
/usr/lib/libldapiconv.so: R_PPC_REL24 relocation at 0x0fb58ad0
for symbol 'strpbrk' out of range"
There is a current restriction that ITDS 6.0 does not support RHEL 4.0 systems.
The PACD process does not start on AIX systems due to unresolved links when using the ITDS LDAP client. When starting the PACD process, the following error might occur:
exec(): 0509-036 Cannot load program /usr/sbin/pacd
because of the following errors:
0509-022 Cannot load module /usr/lib/libpacman.a.
0509-150 Dependent module libldap.a could not be loaded.
0509-022 Cannot load module libldap.a.
To work around this problem for ITDS version 5 of the LDAP client, create the following symbolic:
ln -s /usr/lib/libibmldap.a /usr/lib/libldap.a
To work around this problem for ITDS version 6 of the LDAP client, create the following symbolic:
ln -s /opt/IBM/ldap/V6.0/lib/libibmldap.a /usr/lib/libldap.a
Three directives, ServerInit, Authorization or Authentication, and ServerTerm must be added to the API directives section of the ibmproxy.conf file to initialize the PAC-LDAP authorization module. To create these directives, either manually edit the ibmproxy.conf file, or if the proxy server is already running, connect to the Configuration and Administration forms with an Internet browser and open the API Request Processing form (Click Server Configuration -> Request Processing-> API Request Processing). Each directive must appear on a single line in the proxy configuration file, regardless of whether or not the examples given in this section contain line breaks for clarity.
Note that prototype directives (in the form of comments) are given in the API section of the ibmproxy.conf file. These API directives are in a purposeful order. When adding API directives to enable new features and plug-in modules, order the directives as shown in the prototype section of the configuration file. Alternatively, uncomment and edit, if necessary, API directives to include support for each desired function or plug-in.
The ServerInit directive has three arguments: (1) the fully qualified path of the shared library, (2) the function call, and (3) the fully qualified path of the paccp.conf file. The first and second arguments are delimited by a colon (:). The second and third arguments are delimited by a space. The first and third arguments are system specific and depend on where the plug-in components are installed. The second argument is hard-coded into the shared library and must be typed exactly as shown. When creating a ServerInit directive using the API Request Processing form, both the second and third arguments must be entered in the Function Name field. The third argument is displayed in the IP Template column.
The Authorization directive has three arguments: (1) a request template, (2) the fully qualified path of the shared library, and (3) the function name. HTTP requests are compared to the request template to determine whether the application function is called. The request template can include a protocol, domain, and host; can be preceded by a slash (/); and can use an asterisk (*) as a wildcard. For example, /front_page.html , http://www.ics.raleigh.ibm.com , /pub*, /*, and * are all valid. The function name is the name given to your application function within the program. It is hard coded and must be typed exactly as shown. The first two arguments are delimited by a space. The last two arguments are delimited by a colon (:).
The Authentication directive has two arguments: (1) the fully qualified path of the shared library and (2) the function name. These arguments are delimited by a colon (:). The first argument is system specific and depends on where the shared library is installed. The URL template for the first argument must start at the document root (/) when using Caching Proxy as a reverse proxy. The second argument is hard-coded into the shared library and must be typed exactly as shown.
The ServerTerm directive has two arguments: (1) the fully qualified path of the shared library and (2) the function name. These arguments are delimited by a colon (:). The first argument is system specific and depends on where the shared library is installed. The second argument is hard-coded into the shared library and must be typed exactly as shown. This directive terminates the PAC daemon when the proxy server shuts down. If the owner of the daemon is different from the owner of the proxy server, the proxy server might be unable to stop the daemon, in which case an administrator must manually stop the daemon.
ServerInit path_of_shared_library:pacwte_auth_init path_of_conf_policy_file
Linux and UNIX example:
ServerInit /usr/lib/libpacwte.so:pacwte_auth_init /etc/pac.conf
Windows example:
ServerInit C:\Program Files\IBM\edge\cachingproxy\cp\lib\plugins\
pac\pacwte.dll:pacwte_auth_init C:\Progra ~1\IBM\edge\cp
Authorization request-template path_of_shared_library:pacwte_auth_policy
Linux and UNIX example:
Authorization http://* /usr/lib/libpacwte.so:pacwte_auth_policy
Windows example:
Authorization http://* C:\Program Files\IBM\edge\cachingproxy\cp\lib\plugins\
pac\pacwte.dll:pacwte_auth_policy
Authentication BASIC path_of_shared_library:pacwte_auth_policy
Linux and UNIX example:
Authentication BASIC /usr/lib/plugins/pac/libpacwte.so:pacwte_auth_policy
Windows example:
Authentication BASIC C:\Program Files\IBM\edge\cachingproxy\cp\lib\plugins\
pac\pacwte.dll:pacwte_auth_policy
ServerTerm path_of_shared_library:pacwte_shutdown
Linux and UNIX example:
ServerTerm /usr/lib/libpacwte.so:pacwte_shutdown
Windows example:
ServerTerm BASIC C:\Program Files\IBM\edge\cachingproxy\cp\lib\plugins\
pac\bin\pacwte.dll:pacwte_shutdown
The PAC-LDAP authorization module configuration and policy files must be manually edited with a text editor. A directive name is separated from its first argument by a colon (:). Multiple arguments are delimited by commas (,). Remarks are included in the configuration and policy file to assist in editing it. Key policy directives are shown below.
The paccp.conf file is read by the shared libraries during the initialization of Caching Proxy and contains the definitions ([PAC_MAN_SERVER] stanza) of each PAC daemon that will start. Each PAC daemon must have its own [PAC_MAN_SERVER] stanza.
[PAC_MAN_SERVER]
hostname: # name of PAC daemon
port: # port pacd is listening on
[PACWTE_PLUGIN]
hostname_check:[true|false] # enables DNS lookup. Must have
# DNS lookup turned on for ibmproxy to work.
The pac.conf file specifies the LDAP server with which the PAC daemon attempts to connect.
[PAC_MAN_SERVER]
hostname: # name of PAC daemon
port: # port pacd is listening on
conn_type:ssl # comment out if you do not use SSL
authentication_sequence: [primary|secondary|none]
authorization_sequence: [primary|secondary|none]
[LDAP_SERVER]
hostname: # LDAP Server hostname
port:389 # Port LDAP is listening on
ssl_port:636 # SSL port used by the LDAP server
admin_dn: # User with permission to access the LDAP server
# specify admin_dn:NULL to enable anonymous binding
search_base: # Portion of LDAP tree to search for policy info
# If not required, specify search_base:NULL
search_key: # ID field to search
[CACHE]
cred_cache_enabled [TRUE|FALSE] # turn credentials cache on
cred_cache_min_size:100 # minimum number of credentials to cache in pacd
cred_cache_max_size:64000 # maximum number of credentials to cache in pacd
cred_cache_expiration:86400 # when a credential expires
policy_cache_enabled:[TRUE|FALSE] # turns policy cache on/off
policy_cache_min_size:100 # min. number of policy related items to cache
policy_cache_max_size:64000 # max. number of policy related items to cache
policy_cache_expiration:86400 # when a policy related item expires
Every LDAP policy uses the following template within the configuration and policy file. Each policy must begin with the uppercase keyword POLICY in brackets.
[POLICY]
default_policy:[grant|deny] # describes the default policy for users
# that are not described in the POLICY section
pac_client_hotname: # the instances of Caching Proxy that are allowed
# to use a policy list
id: # the id for the LDAP entry or ip/hostname
# (wildcard supported, such as *.ibm.com)
grant:[true|false] # true means to grant access, false means
# to deny access
type:[0|1|2|3|4] # 0 LDAP entry that is a group,
# 1 LDAP entry that is not a group,
# 2 IP address
# 3 hostname
# 4 URL
propagate:[true|false] # true means that the access rights (grant
# or deny) will be propagated to all
# descendants or members
stop_entry:[entry|NULL] # Propagation of the access right stops
# at this entry. If the id is a group,
# stop_entry must be set to NULL.
# stop_entry may be applied to an IP
# address or hostname. Each stop_entry
# must be on its own line
exception_entry:[entry|NULL] # Assignment of the access right skips
# these entries, but continues through their
# subtrees. This may be a list of entries.
# exception_entry may be applied to a group,
# IP address, or hostname. Each
# exception_entry must be on its own line.
Exception_type:
Exception:
The wildcard (*) is supported only for the last position of an IP address or the first position of a host name in the id and stop_entry directives. Wildcards are not supported in the exception_entry. Wildcards are not supported for any LDAP entries in any fields.
Multiple policies are supported, and the value false always takes priority if policies conflict. In other words, a single denial in any policy blocks access. The order in which the policies are listed in the configuration and policy file is irrelevant and does not establish a priority.
For a set of policy examples, refer to the pacpolicy.conf file in the configuration files directory.
Create a plain text file named pac_ldap.cred in /cp_root/server_root/pac/creds. This file contains the password corresponding to the user name in the admin_dn directive, which is in the pac.conf file.
The PAC daemon encrypts the password the first time that it reads the file.
To create the file pac_ldap.cred on Linux and UNIX platforms, issue the following commands:
cd cp_root/server_root/pac/creds
echo "password" > pac_ldap.cred
chown nobody pac_ldap.cred
chgrp nobody pac_ldap.cred
(on SUSE Linux, use chgrp nogroup pac_ldap.cred.)
To create the file on a Windows platform, type the password in a text file and store the file in the server_root\pac\creds\ directory.
The LDAP authorization daemon runs as the pacd process. You can restart the LDAP authorization daemon without interrupting Caching Proxy by using scripts that are provided. Run the pacd script as follows:
/usr/sbin/pacd_restart.sh pacd_user_id
C:\Program Files\IBM\edge\cachingproxy\cp\Bin\pacd_restart.bat CP_install_root
kill -15 pacd_process_ID
On HP-UX: The PAC-LDAP plug-in and pacd may not load all their dependent shared libraries at runtime. Before using them, ensure that the system variables are set as follows
SHLIB_PATH=/usr/lib:/usr/IBMldap/lib
PATH=/usr/IBMldap/bin:$PATH
PATH=/usr/IBMldap/bin
/usr/IBMldap/is the default installation path for the LDAP client on HP-UX. Please adjust PATH and SHLIB_PATH accordingly if the LDAP client is installed in a different location. Without setting these variables, the following errors may occur:
"Serverinit Error: server did not load functions
from DLL module /opt/ibm/edge/cp/lib/plugins/pac/libpacwte.sl"
"/usr/lib/dld.sl: Can't find path for shared library: libibmldap.sl
/usr/lib/dld.sl: No such file or directory
Abort"
On Linux: For SUSE Linux Enterprise Server 9, the ldd pacd may report that the libldap.so is not found. To work around this problem, create the following symbolic:
ln -s /usr/lib/libldap.so.19 /usr/lib/libldap.so
On AIX: When starting pacd with IBM Tivoli Directory Server 5.2, the PAC-LDAP module may be unable to load resulting in the following error:
exec(): 0509-036 Cannot load program /usr/sbin/pacd because of the following errors:
0509-022 Cannot load module /usr/lib/libpacman.a.
0509-150 Dependent module libldap.a could not be loaded.
0509-022 Cannot load module libldap.a.
To work around this problem, create the following symbolic:
ln -s /usr/lib/libibmldap.a /usr/lib/libldap.a
Could not extract a value for: Uid, return code:3
This
error will be displayed even when the LDAP authentication is functioning
correctly and can be disregarded.