Installation and Upgrade Guides › SiteMinder Upgrade Guide › Upgrading from CA SiteMinder® r12.x › How to Migrate from r12.x › Upgrade an r12.x Policy Server

Upgrade an r12.x Policy Server

The following sections detail how to upgrade an r12.x Policy Server on Windows and UNIX.

Before You Upgrade

Before you upgrade a Policy Server, consider the following items:

• (Optional) If the environment contains multiple smkeydatabase instances, be sure to synchronize all content. Synchronizing resolves data inconsistencies that can prevent the Policy Server installer from automatically migrating content to the certificate data store.
• You upgrade the Policy Server using the installation media on the Technical Support site.
• (Linux) Be sure that the required Linux libraries are installed to the Policy Server host system. For more information, see Required Linux Libraries.
• Remove the Policy Server from the environment. Removing the Policy Server prevents CA SiteMinder® Agents from contacting the Policy Server during the upgrade.
• Shut down all instances of the Policy Server Management Console.
• (UNIX) The user account upgrading the Policy Server must have executable permissions on the directory that contains the installation media. If the user account does not have these permissions, run the following command:

  chmod +x installation_media
  

  installation_media

  Specifies the Policy Server installation executable.

• (UNIX) If you execute the Policy Server across different subnets, it can crash. Run the Policy Server installer directly on the host system.
• (UNIX) Upgrade the Policy Server using an account with at least the same permissions as the user who installed the Policy Server. For example, if a root user installed the Policy Server, upgrade the Policy Sever using a root user.

Required Linux Libraries

Certain library files are required for components operating on Linux operating environments. Failure to install the correct libraries can cause the following error:

java.lang.UnsatisfiedLinkError 

If you are installing, configuring, or upgrading a Linux version of this component, the following packages are required on the host system:

Red Hat 5.x:

• compat–gcc-34-c++-3.4.6-patch_version.I386
• libstdc++-4.x.x-x.el5.i686.rpm
• libidn.so.11.rpm
• ncurses

Red Hat 6.x:

• libstdc++-4.x.x-x.el6.i686.rpm
• libidn-1.18-2.el6.i686
• libXext.i686.rpm
• libXrender.i686.rpm
• linXtst.i686.rpm
• libidn.so.11.rpm
• ncurses

Additionally, for Red Hat 6.x (64-bit):

All the RPM packages that are required for 64-bit Red Hat 6.x are 32-bit packages.

• libXau-1.0.5-1.el6.i686.rpm
• libxcb-1.5-1.el6.i686.rpm
• compat-db42-4.2.52-15.el6.i686.rpm
• compat-db43-4.3.29-15.el6.i686.rpm
• libX11-1.3-2.el6.i686.rpm
• libXrender-0.9.5-1.el6.i686.rpm
• libexpat.so.1 (provided by expat-2.0.1-11.el6_2.i686.rpm)
• libfreetype.so.6 (provided by freetype-2.3.11-6.el6_2.9.i686.rpm)
• libfontconfig.so.1 (provided by fontconfig-2.8.0-3.el6.i686.rpm)
• libICE-1.0.6-1.el6.i686.rpm
• libuuid-2.17.2-12.7.el6.i686.rpm
• libSM-1.1.0-7.1.el6.i686.rpm
• libXext-1.1-3.el6.i686.rpm
• compat-libstdc++-33-3.2.3-69.el6.i686.rpm
• compat-db-4.6.21-15.el6.i686.rpm
• libXi-1.3-3.el6.i686.rpm
• libXtst-1.0.99.2-3.el6.i686.rpm
• libXft-2.1.13-4.1.el6.i686.rpm
• libXt-1.0.7-1.el6.i686.rpm
• libXp-1.0.0-15.1.el6.i686.rpm
• libstdc++.i686.rpm
• compat-libtermcap.rpm
• libidn.i686.rpm
• ncurses

Disable XML Signature Wrapping Checks Before a Policy Server Upgrade

SAML 2.0 artifact transactions fail in CA SiteMinder® federation (legacy or partnership) deployments after you upgrade the Policy Server at the Service Provider.

The following conditions result in failed transactions:

• CA SiteMinder® federation is deployed is at the Service Provider site.
• SAML 2.0 HTTP-Artifact SSO is configured.
• Signature verification at the Service Provider is configured for the assertion or the artifact resolve response.
• The Policy Server setting that prevents XML signature wrapping attacks is enabled.

When the Policy Server tries to verify that the signature of the artifact response, the SSO transaction fails.

To prevent artifact SSO from failing, temporarily turn off the signature vulnerability check. Disable the check after you upgrade the Policy Server at the Service Provider site but before you put the Policy Server into service.

Follow these steps:

1. Navigate to the xsw.properties file. Locate the file in the following directory:

   siteminder_install_dir\config\properties\xsw.properties

   siteminder_install_dir is the location where you installed the Policy Server.

2. Open the file in a text editor, and set the DisableXSWCheck to true (DisableXSWCheck=true). Setting the value to true disables the vulnerability check.
3. After the entire deployment is at version 12.52 SP1, and the Policy Server is running, return the DisableXSWCheck setting to false (DisableXSWCheck=false). Setting the value to false enables the signature vulnerability check.

Verify the Back Channel User Name is Unique for Each SAML Partnership

During an HTTP-Artifact single sign-on transaction, the asserting party returns the assertion to the relying party over a secured back channel. You can require an entity to authenticate to access the back channel. If you select Basic as the authentication method for the back channel, a user name is needed.

Before you upgrade, verify that each federated partnership within the same SAML profile uses a unique user name for the incoming back channel. No two SAML 2.0 or two SAML 1.x partnerships can share an incoming back channel user name.

Note: A SAML 1.x and a SAML 2.0 partnership can share an incoming back channel user name, but it is not recommended.

If there are partnerships of the same protocol that share an incoming back channel user name, do the following steps before you upgrade:

1. Deactivate one of the partnerships.
2. Change the back channel user name that is defined in that partnership.
3. Inform the remote partner of the change.
4. Reactivate the partnership.

Upgrade a Policy Server on Windows

Follow these steps:

1. Exit all applications that are running.
2. Navigate to the installation media.
3. Double–click installation_media.

   installation_media

   Specifies the name of the Policy Server installation executable.

4. Considering the following items when running the installer:
   • The installer prompts you to select the components. When selecting components:
     • Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
     • During the upgrade, leave the policy store check box on the configuration wizard cleared to preserve your existing policy store. However, the configuration wizard prompts you for the encryption key for the advanced authentication server. This key is stored on each Policy Server, but all Policy Servers require the same key.
     • If you are upgrading another (nth) Policy Server, use the same encryption key for the Advanced Authentication server that you used previously.
   • If the installer detects a smkeydatabase, it:
     • Backs up the smkeydatabase.
     • Attempts to migrate the content to the certificate data store.

     Important! If the migration of the smkeydatabase fails, do not return the Policy Server to the environment. Returning the Policy Server after a failed migration causes all transactions that require the certificate data to fail.

5. Review the installation settings and click Install.

   The Policy Server is upgraded. The selected components are configured for use with the Policy Server.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

Upgrade a Policy Server Using a GUI on UNIX

Follow these steps:

1. Exit all applications that are running.
2. Execute the following script in a ksh shell from the CA SiteMinder® installation directory:

   ../ca_ps_env.ksh
   

   Note: Be sure that there is a space between the periods.

3. Open a shell and navigate to the installation executable.
4. Enter the following command:

   ./installation_media
   

   installation_media

   Specifies the name of the Policy Server installer executable.

5. Considering the following items when running the installer:
   • The installer prompts you to select the components. When selecting components:
     • Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
     • During the upgrade, leave the policy store check box on the configuration wizard cleared to preserve your existing policy store. You manually upgrade an existing policy store. However, the configuration wizard prompts you for the encryption key for the advanced authentication server. This key is stored on each Policy Server, but all Policy Servers require the same key. You manually upgrade an existing policy store.
     • If you are upgrading another (nth) Policy Server, use the same encryption key for the Advanced Authentication server that you used previously.
   • If the installer detects a smkeydatabase, it:
     • Backs up the smkeydatabase.
     • Attempts to migrate the content to the certificate data store.

     Important! If the migration of the smkeydatabase fails, do not return the Policy Server to the environment. Returning the Policy Server after a failed migration causes all transactions that require the certificate data to fail.

6. Review the installation settings and click Install.

   The Policy Server is upgraded. The selected components are configured for use with the Policy Server.

7. Click Done.
8. Execute the following script in a ksh shell from the CA SiteMinder® installation directory:

   ../ca_ps_env.ksh
   

   Note: Be sure that there is a space between the periods.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

Upgrade a Policy Server on UNIX Using a Console

Follow these steps:

1. Exit all applications that are running.
2. Execute the following script in a ksh shell from the CA SiteMinder® installation directory:

   ../ca_ps_env.ksh
   

   Note: Be sure that there is a space between the periods.

3. Open a shell and navigate to the installation executable.
4. Enter the following command:

   ./installation_media -i console
   

   installation_media

   Specifies the name of the Policy Server installer executable.

5. Considering the following items when running the installer:

   The installer prompts you to select CA SiteMinder® components. Each component is prefixed with a number. Type numbers separated with a comma (,) to select one or more components. Enter only a comma to select none of the features.

   • Consider the following items when selecting components:
     • Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
     • During the upgrade, leave the policy store check box on the configuration wizard cleared to preserve your existing policy store. You manually upgrade an existing policy store. However, the configuration wizard prompts you for the encryption key for the advanced authentication server. This key is stored on each Policy Server, but all Policy Servers require the same key.
     • If you are upgrading another (nth) Policy Server, use the same encryption key for the Advanced Authentication server that you used previously.
   • If the installer detects a smkeydatabase, it:
     • Backs up the smkeydatabase.
     • Attempts to migrate the content to the certificate data store.

     Important! If the migration of the smkeydatabase fails, do not return the Policy Server to the environment. Returning the Policy Server after a failed migration causes all transactions that require the certificate data to fail.

6. Review the installation settings and press Enter.

   The Policy Server is upgraded. The selected components are configured for use with the Policy Server.

7. Click Done.
8. Execute the following script in a ksh shell from the CA SiteMinder® installation directory:

   ../ca_ps_env.ksh
   

   Note: Be sure that there is a space between the periods.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

Modify a Customized JVMOptions File

During a Policy Server upgrade, the existing JVMOptions.txt file is renamed to JVMOptions.txt.backup. A new JVMOptions.txt file is created.

If the original file included customized parameters, be sure to modify the newly created file to include these customized parameters.

For any Apache-based agents, add the SiteMinder/resources directory to the CLASSPATH in the JVMOptions.txt file, as shown in the following example:

-Djava.class.path=C:/Program Files (x86)/CA/siteminder/resources;

Custom Server–Side Code Requirements

Your Policy Server operating system determines whether recompiling custom server–side code is required. Use the following table to identify the requirement:

Troubleshoot a Policy Server Upgrade

If you experience problems during the upgrade:

• You can locate the Policy Server installation log file in siteminder_home\siteminder\install_config_info.

  siteminder_home

  Specifies the Policy Server installation path.

• You can locate the smkeydatabase migration log (smkeydatabaseMigration.log) in siteminder_home\log.

  Note: A Policy Server upgrade and a smkeydatabase migration are separate processes. If the smkeydatabase migration fails, the Policy Server upgrade does not fail.