Policy Server Guides › Policy Server Configuration Guide › Enhanced Session Assurance with DeviceDNA™ › How to Configure Enhanced Session Assurance with DeviceDNA™ During an Upgrade

How to Configure Enhanced Session Assurance with DeviceDNA™ During an Upgrade

Enhanced Session Assurance with DeviceDNA™ helps prevent unauthorized users from hijacking legitimate sessions with stolen cookies. The session clients are validated using the unique DeviceDNA™ that the product collects from the system of the user. This validation assures that the client who initiated the session is the same client that is requesting access. Users lacking valid DeviceDNA™ are denied access to protected resources.

The following graphic describes how to configure Enhanced Session Assurance with DeviceDNA™ during an upgrade:

Follow these steps:

1. Review the limitations.
2. Do one of the following steps:
   • If you store audit logs in a relational database, go to Step 3.
   • If you store audit logs as text files, go to Step 4.
3. Upgrade your audit store (database) with the following steps:
   1. Stop your Policy Server with one of the following steps:
      • Stop your Policy Server on a Windows operating environment.
      • Stop your Policy Server on a UNIX/Linux operating environment.
   2. Run the appropriate upgrade script for your database with one of the following procedures:
      • Run the audit‑store upgrade script for Oracle databases.
      • Run the audit‑store upgrade script for SQL Server databases.
      • Run the audit‑store upgrade script for IBM DB2 databases.
      • Run the audit‑store upgrade script for MySQL databases.
   3. Start the Policy Server using one of the following procedures:
      • Start your Policy Server on a Windows operating environment.
      • Start your Policy Server on a UNIX/Linux operating environment.
4. Configure your CA SiteMinder® SPS environment.
5. Configure your CA SiteMinder® environment.
6. Create session assurance end points.
7. Pick the appropriate step for your policy model from the following list:
   • For policy domains, add end points to your realms.
   • For applications (EPM), add end points to your application components.
8. For CA SiteMinder® Federation, enable enhanced session assurance on your partnerships.

Limitations of Enhanced Session Assurance with DeviceDNA™

Enhanced Session Assurance with DeviceDNA™ does not support the following items:

Web 2.0 clients

Web 2.0 applications are built on technologies like AJAX which create web requests that cannot be re‑directed to the CA SiteMinder® SPS. Web 2.0 clients include non‑browser‑based clients (such as a Flickr client on a mobile device). In both cases, some requests could occur which cannot be re‑directed to the CA SiteMinder® SPS instance which hosts the authentication flow application. Because of this situation, Enhanced Session Assurance with DeviceDNA™ cannot support for Web 2.0 clients. The login page for Web 2.0 applications can be protected. However, not all requests (such as those involving AJAX) can be protected Enhanced Session Assurance with DeviceDNA™.

Custom Agents

Agents that are created with the CA SiteMinder® SDK do not support Enhanced Session Assurance with DeviceDNA™.

Clients that do not support JavaScript and cookies

The DeviceDNA™ scripts on the CA SiteMinder® SPS are Javascripts that extract the information specific to the web clients. This client information associates a session with the device or client. Without support for JavaScript, the DeviceDNA™ cannot be collected and thus Enhanced Session Assurance with DeviceDNA™ cannot associate the session with the device or client. Enhanced Session Assurance with DeviceDNA™ is not supported for clients like Telnet or Lynx.

Post Preservation

Enhanced Session Assurance with DeviceDNA™ operates using re‑directs to the Authentication Flow application on the CA SiteMinder® SPS. This application contains the DeviceDNA™ scripts. The Authentication Flow application currently does not support POST data. Therefore, the POST requests are not re‑directed to the Authentication Flow application.

Shared Workstations

Any shared workstation has the same DeviceDNA™ signature for every user. For example, suppose that one user hijacks a valid SMSESSION cookie from another user of the shared workstation. If the hijacker replays the stolen SMSESSION cookie from the same shared workstation, the product cannot detect the difference. Enhanced Session Assurance with DeviceDNA™ provides protection when a hijacker attempts to replay the stolen SMSESSION cookie from a different device.

Authentication/Authorization web services

Web service client applications handle the authentication and authorization web services (which push back any redirects or responses they receive from the Agent API calls). However, the calling client cannot handle the redirects that are involved in Enhanced Session Assurance with DeviceDNA™ flow.

CA SiteMinder® Federation

The following configurations do not support Enhanced Session Assurance with DeviceDNA™:

• The SP side of a SAML 2.0 partnership.
• SAML 2.0 HTTP-POST binding on the IdP side of a partnership.

Agent configuration parameters

The following agent configuration parameters do not support Enhanced Session Assurance with DeviceDNA™:

• SecureURL
• TargetAsRelativeURI

Note: Do not set these parameters when using Enhanced Session Assurance with DeviceDNA™. The target URL that these parameters typically contain is already included in a token request that Enhanced Session Assurance uses with DeviceDNA™.

Stop a Windows Policy Server

Stop your Policy Server before continuing. Stopping a Policy Server has the following results:

• The Policy Server is temporarily removed from your environment.
• Agents who need authorization or authentication decisions cannot contact the stopped Policy Server. Those Agents can still connect to other Policy Servers that are available.
• All logging activity stops.

Follow these steps:

1. Log in to the Policy Server host system.

   Note: Use an account with administrator privileges.

2. Click Start, Programs, SiteMinder, SiteMinder Policy Server Management Console.
3. Click the Stop button.
4. Click OK.

   The Policy Server stops and the console closes.

Stop a UNIX Policy Server

Stopping a Policy Server has the following results:

• The Policy Server is temporarily removed from your environment.
• Agents who need authorization or authentication decisions cannot contact the stopped Policy Server. Those Agents can still connect to other Policy Servers that are available.
• All logging activity stops.

Follow these steps:

1. Log in to the system hosting the Policy Server with the same user account that installed the Policy Server originally.
2. Stop all Policy Server processes, with one of the following actions:
   • Open the Management Console, click the Status tab, and then click the Stop buttons.
   • Use the following script. This script also stops the UNIX executive so that the processes do not restart automatically.

     installation_path/siteminder/stop-all
     

   The Policy Server logs all UNIX executive activity in the installation_directory/log/smexec.log file. Log entries are always appended to the existing log file.

Audit Store Upgrade Scripts

After you stop the Policy server, run the appropriate audit‑store upgrade script for your database vendor. Pick the script from the following list:

• An Oracle database.
• A Microsoft SQL Server database.
• An IBM DB2 database.
• A MySQL database.

Run the Audit Store Upgrade Script for Oracle Databases

After you stop the Policy Server, upgrade the audit log schema. This upgrade is accomplished using a script.

Follow these steps:

1. Log in to the Oracle database with sqlplus or some other Oracle utility as the user who administers the Policy Server database information.

   Note: We recommend that you do not upgrade a CA SiteMinder schema with the SYS or SYSTEM users. If necessary, create an Oracle database user, such as SMOWNER, and upgrade the schema as that user.

2. If you are upgrading from 12.5, import the following script:

   $NETE_PS_ROOT/db/SQL/sm_oracle_logs_upgrade_12.5_to_12.51.sql
   

3. Import the following script:

   $NETE_PS_ROOT/db/SQL/sm_oracle_logs_upgrade_12.51_to_12.52.sql
   

   Note: Some environment variables could possibly not function in the SQL utility that Oracle provides. If you experience problems importing the script using the utility, specify an explicit path.

   The audit store schema is upgraded.

4. Start your Policy Server with one of the following procedures:
   • Start your Policy Server on a Windows operating environment.
   • Start your Policy Server on a UNIX/Linux operating environment.

Run the Audit Store Upgrade Script for Microsoft SQL Server Databases

After you stop the Policy Server, upgrade the audit log schema. This upgrade is accomplished using a script.

Follow these steps:

1. Do one of the following tasks:
   • If you are upgrading from version 12.5, go to Step 2.
   • If you are upgrading from version 12.51, go to Step 10.
2. Open the following file in a text editor:

   installation_directory\db\SQL\sm_mssql_logs_upgrade_12.5_to_12.51.sql
   

3. installation_directory
4. Specifies the location in the file system where the Policy Server is installed.
5. Copy the contents of the entire file.
6. Start the Query Analyzer and log in as the user who administers the Policy Server database.
7. Select the database instance from the database list.
8. Paste the schema from the sm_mssql_logs_upgrade_12.5_to_12.51.sql file into the query.
9. Execute the query.
10. Open the following file in a text editor:

    installation_directory\db\SQL\sm_mssql_logs_upgrade_12.51_to_12.52.sql
    

    installation_directory

    Specifies the location in the file system where the Policy Server is installed.

11. Copy the contents of the entire file.
12. Start the Query Analyzer and log in as the user who administers the Policy Server database.
13. Select the database instance from the database list.
14. Paste the schema from the sm_mssql_logs_upgrade_12.51_to_12.52.sql file into the query.
15. Execute the query.

    The audit store schema is upgraded.

16. Start your Policy Server with one of the following procedures:
    • Start your Policy Server on a Windows operating environment.
    • Start your Policy Server on a UNIX/Linux operating environment.

Run the Audit Store Upgrade Script for IBM DB2 Databases

Upgrade the CA SiteMinder® audit log schema. This upgrade is accomplished using a script.

Follow these steps:

1. Log in to the system that is hosting the Policy Server.
2. Navigate to the following directory:

   installation_directory\db\tier2\DB2\
   

   installation_directory

   Specifies the location in the file system where the Policy Server is installed.

3. Do one of the following tasks:
   • If you are upgrading from version 12.5, go to Step 4.
   • If you are upgrading from version 12.51, go to Step 6.
4. Open the following file and copy the contents to a text editor:

   sm_db2_log_upgrade_12.5_to_12.51.sql
   

5. Paste the contents into a query and execute the query.

   Note: For more information executing a query, see the IBM documentation.

   The audit store schema is upgraded.

6. Open the following file and copy the contents to a text editor:

   sm_db2_log_upgrade_12.51_to_12.52.sql
   

7. Paste the contents into a query and execute the query.

   Note: For more information executing a query, see the IBM documentation.

   The audit store schema is upgraded.

8. Start your Policy Server with one of the following procedures:
   • Start your Policy Server on a Windows operating environment.
   • Start your Policy Server on a UNIX/Linux operating environment.

Run the Audit Store Upgrade Script for MySQL Databases

Upgrade the CA SiteMinder® audit log schema. This upgrade is accomplished using a script.

Follow these steps:

1. Log in to the Policy Server host system.
2. Navigate to the following location:

   installation_directory\db\tier2\MySQL.
   

   installation_directory

   Specifies the location in the file system where the Policy Server is installed.

3. Do one of the following tasks:
   • If you are upgrading from version 12.5, go to Step 4.
   • If you are upgrading from version 12.51, go to Step 9.
4. Open the following file in a text editor:

   sm_mysql_logs_upgrade_12.5_to_12.51.sql
   

5. Locate the following lines:

   DROP FUNCTION IF EXISTS `databaseName`.`getdate` $$
   CREATE FUNCTION `databaseName`.`getdate` () RETURNS DATE
   

6. Replace each instance of 'databaseName' with the name of the database functioning as the audit store.
7. Copy the contents of the entire file.
8. Paste the file contents into a query and execute the query.
9. Open the following file in a text editor:

   sm_mysql_logs_upgrade_12.51_to_12.52.sql
   

10. Locate the following lines:

    DROP FUNCTION IF EXISTS `databaseName`.`getdate` $$
    CREATE FUNCTION `databaseName`.`getdate` () RETURNS DATE
    

11. Replace each instance of 'databaseName' with the name of the database functioning as the audit store.
12. Copy the contents of the entire file.
13. Paste the file contents into a query and execute the query.

    The audit store schema is upgraded.

14. Start your Policy Server with one of the following procedures:
    • Start your Policy Server on a Windows operating environment.
    • Start your Policy Server on a UNIX/Linux operating environment.

Start a Windows Policy Server

Start the Policy Server. Starting Policy Server has the following results:

• Agents contact the Policy Server for authorization or authentication decisions.
• Logging begins.

Follow these steps:

1. Click Start, Programs, SiteMinder, SiteMinder Policy Server Management Console.

   The console opens with the Status tab selected.

2. Click the Start buttons.
3. Click OK.

   The Policy Server starts.

Start a UNIX Policy Server

Starting Policy Server has the following results:

• Agents contact the Policy Server for authorization or authentication decisions.
• Logging begins.

Start all Policy Server processes, with one of the following actions:

• Open the Management Console, click the Status tab, and then click the Start buttons.
• Use the following script. This script also starts the UNIX executive.

  installation_path/siteminder/start-all
  

The Policy Server logs all UNIX executive activity in the installation_directory/log/smexec.log file. Log entries are always appended to the existing log file.

Configure your CA SiteMinder® SPS Environment for Enhanced Session Assurance with DeviceDNA™

Enhanced Session Assurance with DeviceDNA™ requires a CA SiteMinder® SPS to operate.

1. Do one of the following tasks:
   • If you do not have a CA SiteMinder® SPS, install version 12.52.
   • If you have a CA SiteMinder® SPS, upgrade it to 12.52.

     Note: For more information about installing or upgrading the CA SiteMinder® SPS, see the CA SiteMinder® SPS Administration Guide, An installation video is also available online.

2. Record the advanced authentication server encryption key from your CA SiteMinder® SPS installation or upgrade. Your CA SiteMinder® Policy Servers in your environment need this key later.
3. For single sign-on environments using multiple cookie domains, you need the fully qualified domain name (FQDN) of the cookie provider domain. Use this FQDN for the ServerName setting when you run the configuration wizard. For example, if your cookie domain is sso.example.com then set the value of the ServerName to sso.example.com in the CA SiteMinder® SPS configuration wizard.
4. Add the following value to the IgnoreExt configuration parameter for your CA SiteMinder® SPS:

   .sac

5. Enable the encryption by configuring the JVM with the JSafeJCE Security Provider using the following steps:
   1. Log on to the CA SiteMinder® SPS computer.
   2. Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files package of the Java version you are using from the Oracle website.
   3. Navigate to the following location:

      Windows

      JVM_HOME\lib\security

      UNIX

      JVM_HOME/lib/security

      JVM_HOME

      Defines the location where Java Runtime Environment (JRE) is installed in JDK of your installation.

   4. Patch the following files with the files from the JCE Unlimited Strength Jurisdiction Policy Files package:
      • local_policy.jar
      • US_export_policy.jar

      The JVM is configured.

Configure Your CA SiteMinder® Environment for Enhanced Session Assurance with DeviceDNA™

Enhanced Session Assurance with DeviceDNA™ requires certain components and settings in your CA SiteMinder® environment.

Follow these steps:

1. Install or upgrade your Policy Server to version 12.52.
2. If you do not have a session store, configure one.

Create Enhanced Session Assurance with DeviceDNA™ end points

Enhanced Session Assurance with DeviceDNA™ silently redirects users to the authentication flow application end points hosted on the CA SiteMinder® SPS to collect DeviceDNA™ information. This DeviceDNA™ information validates their sessions.

For performance reasons, we recommend creating one end point for each geographic area in your organization. For example, if you have offices in New York and Chicago, create an end point for each office.

Configure these end points on your CA SiteMinder® SPS before adding Enhanced Session Assurance with DeviceDNA™ to your policies or applications.

Follow these steps:

1. From the Administrative UI, click Global, Session Assurance Endpoints.
2. Click Create Session Assurance Endpoint.
3. Enter a descriptive name and an optional description.
4. Complete the following fields:

   Web Server Name

   Specifies the name of the CA SiteMinder® SPS server which collects the DeviceDNA™ to authenticate users.

   Port

   Specifies the port number on which the CA SiteMinder® SPS is listening for redirections. Configure this port for a secure connection (using SSL).

   Default: 443

   Target

   Specifies the URL of the CA SiteMinder® SPS to which the users are silently re‑directed. This server collects the DeviceDNA™ of the user. The product uses DeviceDNA™ to validate the sessions that are associated with the user.

   DeviceDNA™ Refresh Interval

   Specifies the number of seconds for which the DeviceDNA™ that is associated with a user remains valid. Users without valid DeviceDNA™ are re–directed to the Enhanced session assurance end point where the server obtains current DeviceDNA™ for the user.

   The DeviceDNA™ refresh‑interval governs the collection of DeviceDNA™. Any request occurring after the expiration of DeviceDNA™ refresh‑interval is re‑directed to the Authentication Flow application to re‑collect the DeviceDNA™.

   The DeviceBinder is a session property that identifies the user that is associated with the session. The DeviceBinder and the client side Device ID have been linked during the authentication process. A unique DeviceHash and an expiration time form this property.

   Default: 300 seconds (5 minutes)

5. Click Submit.

Add endpoints to your realms

To protect resources in realms using Enhanced Session Assurance with DeviceDNA™, add one session assurance end point to the realm.

Note: Your realms do not need to be persistent for Enhanced Session Assurance with DeviceDNA™ to work.

Follow these steps:

1. From the Administrative UI, click Policies, Domain, Realms.
2. Click the edit icon of the realm that you want.
3. Under Session, click the Enable check box next to Enhanced Session Assurance.
4. Click Lookup Endpoint.
5. Pick the endpoint that you want.
6. Click OK.
7. Click Submit.
8. Repeat Steps 2 through 6 for any other realms with resources that you want to protect with the session assurance feature.

Add end points to your application components

To protect components in applications using Enhanced Session Assurance with DeviceDNA™, add one enhanced session assurance end point to the component of the associated application.

Follow these steps:

1. From the Administrative UI, click Policies, Application, Applications.

   A list of applications appears.

2. Click the edit icon of the application that you want.

   The Modify Application: dialog appears.

3. Do one of the following steps:
   • If your application has only one component, click Advanced Settings.
   • If your application has several components, click the edit icon of the component that you want. Click Advanced Settings.
4. Under Session, select the Enable check box next to Enhanced Session Assurance.
5. Click Lookup Endpoint.

   A list of end points appears.

6. Pick the end point that you want.
7. Click OK.
8. Click Submit.

   The Modify Application dialog closes and a confirmation message appears.

9. Repeat Steps 2 through 7 for any other applications with resources that you want to protect with the session assurance feature.

Enable Enhanced Session Assurance with DeviceDNA™ on your partnerships

If you use CA SiteMinder® Federation, you can also enable Enhanced Session Assurance with DeviceDNA™ on the following partnerships:

• The IdP side of an SP to IdP partnership (HTTP-Redirect binding only).
• The Producer side of a Consumer to Producer partnership.
• The AP side of an RP to AP partnership.

Follow these steps:

1. From the Administrative UI, click Federation, Partnership Federation, Partnerships.
2. Click the Action button to the left of the partnership that you want, and then pick Deactivate.
3. Click the same Action button again, and then pick Modify.
4. Click the SSO and SLO tab.
5. Click the following check box:

   Enable Session Assurance

   Protects the resources that are specified in the realm (of the Policy domain model) or the component (of the application model). You can also protect the authentication requests of certain CA SiteMinder® Federation partnerships. The session assurance end point collects the DeviceDNA™ from the user and validates the session.

   Limits: This feature requires session assurance end points.

   A list of end points appears.

6. Click the check box of the end point that you want.
7. Click Save.
8. Repeat Steps 2 through 7 on any other partnerships that you want.
9. (For local authentication mode only) enable Enhanced Session Assurance with DeviceDNA™ on the realm that is associated with authentication URL (Redirect.jsp).