Using the PAC-LDAP authorization module
The PAC-LDAP authorization module enables Caching Proxy to access a Lightweight Directory Access Protocol (LDAP) server when performing authorization or authentication routines.
Overview
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. 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.
Authentication
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 that is stored in the registry. These are the actions that are 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 starts 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 retrievedby using 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.
Authorization
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 that reside 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 starts a protection schema. In this case, the protection schema is the authorization routine that is 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 started. Type 4 policies that are defined within the pacpolicy.conf file further refine the authentication that is required for various URL requests.
Lightweight Directory Access Protocol (LDAP)
LDAP provides interactive access to X.500 directories with a minimal consumption of system resources. The IANA assigns TCP port 389 and UDP port 389 to LDAP. For more information about LDAP, see RFC 1777.
Examples of supported LDAP clients are: the IBM Tivoli LDAP client and the IBM SecureWay LDAP client.
Installation
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 |
More requirements and restrictions for secure PACD-LDAP server connections
GSKit is required by LDAP client package
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.
LD_PRELOAD environment variable must be set for Linux systems
LD_PRELOAD=/usr/lib/libstdc++-libc6.1-1.so.2
The GSKit requirement referenced previously in this section also applies to Linux systems.
On Linux systems, the PACD process fails to start when using IBM Tivoli Directory Server (ITDS) 6.0 LDAP client
"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 Tivoli Directory Server 6.0 does
not support RHEL 4.0 systems.On AIX systems, the PAC-LDAP module is unable to load when using IBM Tivoli Directory Server (ITDS) LDAP client
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 Tivoli Directory
Server 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 Tivoli Directory
Server version 6 of the LDAP client, create the following symbolic: ln -s /opt/IBM/ldap/V6.0/lib/libibmldap.a /usr/lib/libldap.a
Editing the ibmproxy.conf file to enable the PAC-LDAP authorization module
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 the examples that are given in this section contain line breaks for clarity.
The 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 hardcoded into the shared library and must be typed exactly as shown. When creating a ServerInit directive by 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 that is given to your application function within the program. It is hardcoded 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 hardcoded 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 hardcoded 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
Editing the PAC-LDAP authorization module configuration files
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 help editing it. Key policy directives are shown here:
paccp.conf
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.
pac.conf
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
pacpolicy.conf
[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.
Creating pac_ldap.cred
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.
Starting and stopping pacd
- On Linux and UNIX platforms:
/usr/sbin/pacd_restart.sh pacd_user_id
- On Windows platforms:
C:\Program Files\IBM\edge\cachingproxy\cp\Bin\pacd_restart.bat CP_install_root
kill -15 pacd_process_ID
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. Adjust
the PATH and SHLIB_PATH accordingly if the LDAP client is installed
in a different location. Without setting these variables, the following
errors may occur: - After enabling the PAC-LDAP plug-in, the following message will
appear in the error log
"Serverinit Error: server did not load functions from DLL module /opt/ibm/edge/cp/lib/plugins/pac/libpacwte.sl"
- When attempting to start /usr/sbin/pacd the
following link error will display
"/usr/lib/dld.sl: Can't find path for shared library: libibmldap.sl /usr/lib/dld.sl: No such file or directory Abort"
ln -s /usr/lib/libldap.so.19 /usr/lib/libldap.so
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 is displayed even when the LDAP authentication is functioning
correctly and can be disregarded.