Agent for SharePoint Guide › SessionLinker Reference

SessionLinker Reference

This section contains the following topics:

How the SessionLinker Works

What the SessionLinker Does Not Support

Single Session Cookie Enforcement

Enable Wildcard Cookie Names

Maintain Links to Multiple Cookies

SessionLinker Troubleshooting

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.

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

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® Agent for SharePoint.
• 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® Agent for SharePoint 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® Agent for SharePoint.
• 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.