Web Agent Guides › Web Agent Configuration Guide › Session Protection › How to Link a Client Certificate to a Session (UNIX)

How to Link a Client Certificate to a Session (UNIX)

For IIS 7.x (Windows only) and Apache-based web servers, you can link a client certificate with a CA SiteMinder® session. This feature verifies that the following identities match:

• The identity of the user that is associated with a CA SiteMinder® session.
• The identity of the client certificate that is used in the transaction.

If these items do not match, the product blocks transactions.

To use this feature, do the following tasks:

• Configure all web servers so that they acquire the client certificate automatically. Especially when the logon‑server is separate from the policy‑enforcement point.

Use an X.509 Certificate authentication scheme (other authentication schemes are not supported).

The following graphic describes how link a client certificate to a session:

Follow these steps:

1. Add the plug-in to the WebAgent.conf file.
2. Set the agent configuration parameters.
3. Enable the SSLOptions directive in the Apache-based web server.

Add the Plug–in

Adding the plug-in is the first step linking client certificates to sessions.

Follow these steps:

1. Log in to the system hosting your agent.
2. Open the following file with a text editor:

   WebAgent.conf
   

3. Locate the following line:

   LoadPlugin="web_agent_home/bin/libHttpPlugin.so"
   

4. Add a line immediately following the line on Step 3.
5. Add the following text to the new line.

   LoadPlugin="web_agent_home/bin/libCertSessionLinkerPlugin.so"
   

   Note: The libCertSessionLinkerPlugin must follow the libHttpPlugin.

6. Save the file.
7. Restart the web server.

   The plug-in is added. Continue by adding your configuration parameters.

Set the agent configuration parameters after adding the plug-in.

Follow these steps:

1. Using the Administrative UI, open the agent configuration object that you want.

   Change the values of the following parameters:

   CslCertUniqueAttribute

   Lists the attributes of the certificate by which it is uniquely identified. The following certificate attributes are available:

   • version
   • serialnumber
   • signaturealgorithm
   • issuerdn
   • subjectdn
   • validitystart
   • validityend

   Note: The sequence of the values in in this parameter does not matter.

   Default: Disabled (only the serialnumber and the issuerdn attributes are matched).

   CslMaxCacheEntries

   Specifies the maximum number of entries that the agent cache contains.

   Note: For any Apache-based servers operating on UNIX, we recommend setting the value of the singleprocessmode parameter to no. This setting creates a multi‑process cache which shares information across multiple requests. This setting improves performance when the Apache-based server runs in pre‑fork mode.

   Default: 1000

2. For any Apache-based servers, if the following parameter exists, verify that the value is no:

   SingleProcessMode

   Specifies if the CSL cache is only available to a single process on an Apache-based server (worker mode). To make the cache available to a single process only, set this value to yes. On UNIX operating environments, Apache-based servers operate in pre‑fork mode, where a separate process handles each request. We recommend setting this value to no on UNIX operating environments so that the CSL cache is shared among multiple requests.

   Default: No (pre‑fork mode, multi‑process cache).

   Options: Yes (worker mode, single-process cache).

3. Save the changes and close your agent configuration object.

   Continue by enabling the SSLOptions directive.

Enable the SSLOptions directive in the Apache-based Web server

The next step is enabling the SSLOptions directive of your Apache‑based server. Enabling this directive makes the certificate attributes available as environment variables.

Add the following entry into the http.conf file of your Apache-based server.

SSLOptions +StdEnvVars