Administration Guide › Configuring CA SiteMinder® SPS › Configuring CA SiteMinder® SPS to Support the SessionLinker

Configuring CA SiteMinder® SPS to Support the SessionLinker

The SessionLinker synchronizes the CA SiteMinder® session with the third-party application session for better security. By default, CA SiteMinder® SPS installs SessionLinker in a disabled mode.

The following diagram describes how the CA SiteMinder® SPS administrator and policy administrator can configure CA SiteMinder® SPS to support the SessionLinker:

How the SessionLinker Works

The SessionLinker synchronizes a SiteMinder session with a third-party application session for better security. If a user logs out of SiteMinder, the SessionLinker invalidates the related session of the third-party application.

When a user authenticates, SiteMinder assigns a unique session identifier to that user session. The session identifier, called the SiteMinder Session ID, remains constant for that user for the life of the user session. If the user logs out of SiteMinder through the Logout URL, SiteMinder deletes the SMSESSION cookie that SiteMinder uses to track the SiteMinder Session ID.

The SessionLinker module takes application session cookies and associates them, one by one, with a SiteMinder session. Once associated, the application cookie (referred to here as the foreign cookie) can only be used in conjunction with that particular SiteMinder session. The SessionLinker prevents attempts by other SiteMinder sessions to use the same foreign session.

To understand the SessionLinker operation, associate the SiteMinder session and corresponding foreign cookies that SiteMinder tracks together in a table, as shown in the following example:

The SessionLinker uses the following process:

1. The SessionLinker receives a request from a web server.
2. The SessionLinker extracts the SiteMinder Session ID from the HTTP headers and the Foreign Cookie from all the incoming HTTP cookies.
3. The SessionLinker compares the values that are presented from the web server against the contents of the table to determine whether the request must be allowed, as shown in the following examples:
   1. If the Session ID is FIVE and the Foreign Cookie is RSTU, SessionLinker inserts these values into the table.
   2. If the Session ID is SIX and the Foreign Cookie is ABCD, SessionLinker blocks the request because the Foreign Cookie ABCD is already associated with Session ONE.
   3. If the Session ID is ONE and the Foreign Cookie is HIJK, the old session is orphaned and SessionLinker updates the table to associate Session ID ONE with HIJK. When a session is orphaned, the Foreign Cookie can no longer be presented by anyone. This feature allows the SessionLinker to support applications that update the cookie during the user session.

The entire process is repeated for each Foreign Cookie. The resulting table may appear as follows:

What the SessionLinker Does Not Support

The SessionLinker does not do any of the following tasks:

• Track cookies issued to the user throughout the CA SiteMinder® environment. Doing so would require a persistent data store that could be read from and written to by every web server employing SessionLinker. The massive number of reads and writes necessary to support this tracking would require substantial processing power and bandwidth, and is thus unmanageable.
• Destroy the cookies of an existing user when the user logs out of CA SiteMinder®. Because the cookies are not being tracked centrally, no mechanism knows which cookies to destroy. In addition, because of the way different web browsers handle cookies, the logout page cannot always determine which cookies the user has received. Finally, SessionLinker does not actually integrate with the CA SiteMinder® logout process.
• Terminate the session of an underlying application. To support this function, the SessionLinker would need to know how to terminate sessions in each of the applications – many of which do not have an exposed API to manage sessions. Because applications can be configured to terminate sessions after some amount of idle time, and there is little the overhead in leaving a session active, this function has not been implemented.

SessionLinker accomplishes the linking by preventing the user from presenting an invalid Foreign Session cookie.

Enable the SessionLinker

Enable the SessionLinker to synchronize the CA SiteMinder® session with the third-party application session. You can configure the SessionLinker ACO after you enable the feature.

Follow these steps:

1. Navigate to Virtual Hosts, Virtual Hosts, Add/Edit Virtual Host, Web Agent Configuration.
2. Select the Enable Session Linker option.
3. Click Save.
4. Restart the CA SiteMinder® SPS server.

Create the NPS_Session_Linker ACO

CA SiteMinder® SPS manages the SessionLinker configuration through an ACO. The SessionLinker ACO has the following syntax:

SessionLinker=Cookie=cookie_value;BLOT|NOBLOT;Orphantimeout=timeout_value;

Where

COOKIE=cookie name

Specifies the name of the cookie holding the foreign session. If cookie names may change, use an asterisk as a wildcard character.

BLOT|NOBLOT

(Optional) Specifies how the SessionLinker responds to invalid sessions. If you set the value of this parameter to BLOT, the user is granted access but the foreign session cookie is not passed through the web server to the target page. If you set the value of this parameter to NOBLOT, the foreign cookie is deleted from the request and the user is then redirected to the URL specified in the URL parameter. If you do not specify the URL in the URL parameter, the internal server error is displayed.

Default: BLOT

ORPHANTIMEOUT=seconds

Specifies the number of seconds that the SessionLinker maintains orphaned sessions.

Default: 86400 (the number of seconds in a 24 period)

Limits: Cannot be less than the maximum number of seconds that cookies from the third party (foreign) application are accepted.

To configure CA SiteMinder® SPS to support SessionLinker, create the ACO named SessionLinker in one of the following ways:

• Using the webagent.conf file
• Using the WAMU

Create the NPS_Session_Linker ACO Using webagent.conf

If you want to use the local configuration to create the SessionLinker ACO, create the ACO using the webagent.conf file.

Follow these steps:

1. Open the localconfigfile specified in the webagent.conf file.
2. Add the following command to the file:

   SessionLinker= Cookie=cookie_value;BLOT|NOBLOT;Orphantimeout=timeout_value;
   

3. Save the changes.

The SessionLinker ACO is created. The CA SiteMinder® SPS is configured to support the SessionLinker.

If you want to configure SessionLinker to work with cookies, see Working with Cookies. If you want to troubleshoot any errors that are caused by the SessionLinker, see Troubleshooting.

Create the NPS_Session_Linker ACO Using WAMUI

If you want to use the central configuration to create the SessionLinker ACO, the policy administrator must create the ACO through the WAMUI.

Follow these steps:

1. Open the WAMUI.
2. Add an ACO with the following details:

   Name: SessionLinker

   Value: Cookie=cookie_name;BLOT|NOBLOT;Orphantimeout=timeout_value;

3. Click Save.

The SessionLinker ACO is created. The CA SiteMinder® SPS is configured to support the SessionLinker.

If you want to configure SessionLinker to work with cookies, see Working with Cookies. If you want to troubleshoot any errors that are caused by the SessionLinker, see Troubleshooting.

Working with Cookies

Single Session Cookie Enforcement

In most cases, an application has a specific name that is always used for an associated session cookie. In other cases, the name of the cookie begins with a known string, such as ASPSESSIONID or MYAPPSESSION, and ends with a random or unpredictable suffix. In such cases, the SessionLinker prevents users from presenting more than one of these cookies and enforces the expected session linking.

If the SessionLinker detects multiple potential session cookies, it performs the following steps:

1. Blocks access to sessions
2. Destroys all the cookies
3. Redirects the user to a URL that you specify. If you do not specify a URL, the internal server error is displayed.

Enable Wildcard Cookie Names

You can add the following parameters of the ACO configured on the Policy Server to the configuration settings already selected:

COOKIE

Specifies that a cookies beginning with the specified name must be considered as a potential foreign session cookie. The cookie value may end in an asterisk (*). If you specify a cookie value other than a wildcard syntax, you must specify COOKIEPATH and COOKIEDOMAIN values that determine how to destroy the incoming cookies.

COOKIEPATH

Specifies the cookie path. If you specified a wildcard syntax for the COOKIE parameter, do not specify this parameter. The COOKIEPATH value depends on the session cookie, and has the following format:

COOKIEPATH=<Path for outbound cookies or cookies>

Default Value: /

Example: COOKIEPATH=/

COOKIEDOMAIN

Specifies the cookie domain. If you specified a wildcard syntax for the COOKIE parameter, you can specify this value in the following format:

COOKIEDOMAIN=<domain name for outbound cookie or cookies>

Default Value: Blank

Example: COOKIEDOMAIN=.ca.com

Determine Cookie Settings

To determine the cookie name settings, perform the following steps:

1. Access the application multiple times.
2. Note the cookies sent by the application.
3. Enable the warning prompts for cookies in a web browser.
4. Examine the warnings that appear.

COOKIE Setting

If the name of a session cookie for an application starts with the same text string but ends differently, specify a cookie name in the following format:

COOKIE=cookiename*

COOKIEDOMAIN Setting

The domain name of a cookie consists of any of the following items:

• The domain name of the web server prefixed by a leading period (.)
• The fully qualified computer name of the web server (myserver.example.com)
• A blank

The fully qualified computer name or a blank name are equivalent.

Note: Internet Explorer deletes the leading period before displaying a domain. So, we recommend that you test various configurations in a staging environment to determine the correct settings.

COOKIEPATH Setting

The path associated with a cookie is typically a directory, but could be a file or another string. Examine the path shown in the cookie warning dialog of your web browser. If the path shown is not a forward slash (/), enter the correct value for the COOKIEPATH setting.

Maintain Links to Multiple Cookies

Some web applications use more than one cookie simultaneously within the same area of the site. You can configure the SessionLinker to maintain links from a single CA SiteMinder® session to a number of cookies. A maximum of ten foreign session cookies can be linked to a single CA SiteMinder® session.

Follow these steps:

1. Determine the correct configuration string for each cookie.

   Note: Each configuration string requires at least a COOKIE directive, but any of the directives can be combined.

2. Assign an integer from 0 through 9 to each cookie.
3. Append the selected number to the directive name.

   Note: You can use any number for each set of directives but the settings for a single cookie require the same number.

4. Concatenate the separate configuration strings into a single string.

SessionLinker Troubleshooting

If an error occurs, consider the following possibilities to troubleshoot the error:

• Verify that the valid SMSESSION cookie and FOREIGN SESSION cookie are set at the user and are passed to the CA SiteMinder® SPS.
• If you enabled the SessionLinker using the webagent.conf file, verify that the web agent is enabled.
• Verify that the SessionLinker ACO syntax is correct.
• If agent tracing is enabled in the SessionLinker ACO, verify the logs and trace messages in the agent logs and trace.
• Verify that the CA SiteMinder® SPS loaded the SessionLinker plug-in binary properly. Check the agents.log file for log messages. If there are any errors, check if any dependent libraries exist for the SessionLinker plug-in library on the CA SiteMinder® SPS.
• If a request is rejected, verify that the session identifiers on CA SiteMinder® Policy Server (SMSESSION) and application web server (FOREIGN SESSION) are linked are the same user.