Agent for SharePoint Guide › Advanced Options › How to Use the Session Linker

How to Use the Session Linker

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

Part of this synchronization process uses cookies from the third-party application. The SessionLinker requires certain information about these third-party cookies to link the sessions.

Follow these steps:

1. Enable the session linker.
2. Pick the procedure that matches your agent configuration method from the following list:
   • For agents using an Agent Configuration object (ACO) on a Policy Server, follow these steps:
     1. Open the Administrative UI.
     2. Set the SessionLinker parameter in an Agent Configuration object.
   • For agents using a local configuration file on the, set the Session parameter in a local configuration file.

Enable the SessionLinker

Because the SessionLinker operates on a server, enable it on the server first.

Follow these steps:

1. Log in to the server that runs your Agent for SharePoint.
2. Open the following file with a text editor:

   Agent-for-SharePoint_Home\proxy-engine\conf\defaultagent\WebAgent.conf
   

   Agent-for-SharePoint_Home

   Indicates the directory where the CA SiteMinder Agent for SharePoint is installed.

   Default: (Windows) [32-bit] C:\Program Files\CA\Agent-for-SharePoint

   Default: (Windows) [64-bit] C:\CA\Agent-for-SharePoint
   Default: (UNIX/Linux) /opt/CA/Agent-for-SharePoint

3. Locate the following line that applies to your operating environment::

   (Windows) #LoadPlugin="Agent-for-SharePoint_Home\agentframework\bin\SessionLinkerPlugin.dll"
   

   (UNIX/Linux) #LoadPlugin="Agent-for-SharePoint_Home\agentframework\bin\LibSessionLinkerPlugin.so
   

4. Delete the # character at the beginning of the line.
5. Save the file and close the text editor.

   The SessionLinker is enabled.

Open the Administrative UI to Change Policy Server Objects

Change the objects on your Policy Server by opening the Administrative UI.

Follow these steps:

1. Open the following URL in a browser.

   https://host_name:8443/iam/siteminder/adminui
   

   host_name

   Specifies the fully qualified Administrative UI host system name.

2. Enter your CA SiteMinder superuser name in the User Name field.
3. Enter the CA SiteMinder superuser account password in the Password field.

   Note: If your superuser account password contains one or more dollar‑sign ($) characters, replace each instance of the dollar-sign character with $DOLLAR$ in the Password field. For example, if the CA SiteMinder superuser account password is $password, enter $DOLLAR$password in the Password field.

4. Verify that the proper server name or IP address appears in the Server drop-down list.
5. Select Log In.

Set the SessionLinker Parameter in an Agent Configuration Object

A configuration parameter controls the SessionLinker. Add the SessionLinker parameter to your Agent Configuration object (ACO) if the configuration settings for your agents are centrally managed on a Policy Server.

Follow these steps:

1. From the Administrative UI, click the Infrastructure, Agent Configuration Objects.
2. Click the edit icon in the line Agent Configuration Object you want.
3. Click Add.

   The Create Parameter dialog appears.

4. Type the following text in the Name field:

   SessionLinker
   

5. Click the Value field, and then add the following settings (on one line):

   Important! Use semicolons (;) to separate each SessionLinker setting. For example, Cookie=cookie_name;NOBLOT;URL=url_value;

   COOKIE=cookie_name;

   Specifies the name of the cookie from the third-party (foreign) application. If cookie names change, use an asterisk as a wildcard character. For example, if the cookies from your third party begin with APSESSION, use APPSESSION for the value of this setting.

   Examples: Cookie Names

   • COOKIE=APPSESSION;
   • COOKIE=APP*;
   • COOKIE=APPLICATION*;

   BLOT | NOBLOT;

   (Optional) Specifies how the SessionLinker responds to invalid sessions. If the value of this parameter is set to BLOT, the user is granted access. The third party (foreign) session cookie is not passed through the web server to the target page. If the value of this parameter is set to NOBLOT, the user is redirected to URL specified in the URL setting. If the value of this setting is NOBLOT, set the URL parameter.

   Default: BLOT

   Limits: BLOT, NOBLOT

   URL=url_value;

   Specifies a URL to where users are redirected when the value of the SessionLinker parameter contains NOBLOT. Users are directed to this URL and no the target page.

   Example: URL=/InvaidSessionWarning.jsp

   ORPHANTIMEOUT=seconds

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

   Default: 86400 (24 hours)

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

   COOKIESCOPE=number_of_characters;

   (Optional) Specifies the number of characters in a URL, so that cookies used in more than area of a website can be distinguished. Suppose different applications use the same 15-character URL string as a prefix for naming its cookies. Use a larger value for the cookiescope setting. The larger number distinguishes between specific resources in other locations.

   Examples of URLs and corresponding values:

   • /scripts/wgate/ (15-character prefix string)
   • /scripts/wgate/abc (18-character string)
   • /scripts/wgate/xyz (18-character string)

   OPTIONS=USE_HOST_LINKS;

   Instructs the SessionLinker to link sessions for each virtual host defined in the server.conf file of your Agent for SharePoint.

   Default: USE_HOST_LINKS

   Example: Cookie=cookie_value;BLOT;Orphantimeout=1440;OPTIONS=USE_HOST_LINKS;

6. Click OK.
7. Click Submit.

   The SessionLinker parameter is added to your Agent Configuration Object.

Set the SessionLinker Parameter in a Local Configuration File

A configuration parameter controls the SessionLinker. Add the SessionLinker parameter to your local configuration file If the configuration settings for your agents are stored on each server.

Follow these steps:

1. Log in to the server that runs your Agent for SharePoint.
2. Open the following file with a text editor:

   Agent-for-SharePoint_Home\proxy-engine\conf\defaultagent\LocalConfig.conf
   

3. Locate the following line:

   SessionGracePeriod="30"
   

4. Add line after the previous line.

   Note: The order of the parameters in the LocalConfig.conf file does not matter, but having then in alphabetical order makes them easier to find.

5. Type the following text:

   SessionLinker="
   

6. Add the following settings (on one line):

   Important! Use semicolons (;) to separate each SessionLinker setting. For example, Cookie=cookie_name;NOBLOT;URL=url_value;

   COOKIE=cookie_name;

   Specifies the name of the cookie from the third-party (foreign) application. If cookie names change, use an asterisk as a wildcard character. For example, if the cookies from your third party begin with APSESSION, use APPSESSION for the value of this setting.

   Examples: Cookie Names

   • COOKIE=APPSESSION;
   • COOKIE=APP*;
   • COOKIE=APPLICATION*;

   BLOT | NOBLOT;

   (Optional) Specifies how the SessionLinker responds to invalid sessions. If the value of this parameter is set to BLOT, the user is granted access. The third party (foreign) session cookie is not passed through the web server to the target page. If the value of this parameter is set to NOBLOT, the user is redirected to URL specified in the URL setting. If the value of this setting is NOBLOT, set the URL parameter.

   Default: BLOT

   Limits: BLOT, NOBLOT

   URL=url_value;

   Specifies a URL to where users are redirected when the value of the SessionLinker parameter contains NOBLOT. Users are directed to this URL and no the target page.

   Example: URL=/InvaidSessionWarning.jsp

   ORPHANTIMEOUT=seconds

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

   Default: 86400 (24 hours)

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

   COOKIESCOPE=number_of_characters;

   (Optional) Specifies the number of characters in a URL, so that cookies used in more than area of a website can be distinguished. Suppose different applications use the same 15-character URL string as a prefix for naming its cookies. Use a larger value for the cookiescope setting. The larger number distinguishes between specific resources in other locations.

   Examples of URLs and corresponding values:

   • /scripts/wgate/ (15-character prefix string)
   • /scripts/wgate/abc (18-character string)
   • /scripts/wgate/xyz (18-character string)

   OPTIONS=USE_HOST_LINKS;

   Instructs the SessionLinker to link sessions for each virtual host defined in the server.conf file of your Agent for SharePoint.

   Default: USE_HOST_LINKS

   Example: Cookie=cookie_value;BLOT;Orphantimeout=1440;OPTIONS=USE_HOST_LINKS;

7. At the end of the line, type a double-quotation mark (").
8. Save the file, and then close the text editor.

   The SessionLinker parameter is added to your local configuration file.

9. Repeat Steps 1 through 8 on all servers running your Agent for SharePoint that use local configuration.