Verify That Existing Federated SAML Partnerships Do Not Have the Same Backchannel Username

Installation and Upgrade Guides › SiteMinder Upgrade Guide › Upgrading from r12.x › How to Migrate from r12.x › Red Hat Directory Server as a Key Store › Verify That Existing Federated SAML Partnerships Do Not Have the Same Backchannel Username

Verify That Existing Federated SAML Partnerships Do Not Have the Same Backchannel Username

Verify that no existing partnerships have incoming backchannel usernames (within the same protocol) that are the same before upgrading.

That is, no two SAML 2.0 partnerships can share an incoming backchannel username. Similarly, no two SAML 1.0 partnerships can share an incoming backchannel username. A SAML 1.0 and a SAML 2.0 partnership can share an incoming backchannel username but it is not recommended.

If you do have partnerships of the same protocol that share an incoming backchannel username, do the following steps before you upgrade:

Deactivate one of the partnerships.
Change the backchannel username that is defined in that partnership.
Inform the remote partner of the change.
Reactivate the partnership.

Upgrade a Policy Server on Windows

Follow these steps:

Review Before You Upgrade.
Exit all applications that are running.
Navigate to the installation media.
Double–click installation_media.

installation_media

Specifies the name of the Policy Server installation executable.

The Policy Server installer starts.

Note: For a list of installation media names, see the Policy Server Release Notes.
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.
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:

Review Before You Upgrade.
Exit all applications that are running.
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.
Open a shell and navigate to the installation executable.
Enter the following command:
```
./installation_media
```
installation_media

Specifies the name of the Policy Server installer executable.

The Policy Server installer starts.

Note: For a list of installation media names, see the Policy Server Release Notes.
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.
Review the installation settings and click Install.
The Policy Server is upgraded. The selected components are configured for use with the Policy Server.
Click Done.
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:

Review Before You Upgrade.
Exit all applications that are running.
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.
Open a shell and navigate to the installation executable.
Enter the following command:
```
./installation_media -i console
```
installation_media

Specifies the name of the Policy Server installer executable.

The Policy Server installer starts.

Note: For a list of installation media names, see the Policy Server Release Notes.
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.
Review the installation settings and press Enter.
The Policy Server is upgraded. The selected components are configured for use with the Policy Server.
Click Done.
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

Policy Server Upgrade Creates a New 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.

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:

Operating System	Required?
Microsoft Windows and UNIX	No. Recompiling the custom code is optional.
Red Hat Linux	Yes. Upgrade the SDK and recompile the custom code using GCC 3.4.

Operating System

Required?

Microsoft Windows and UNIX

No. Recompiling the custom code is optional.

Red Hat Linux

Yes.

Upgrade the SDK and recompile the custom code using GCC 3.4.

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.

Upgrade an r12.x Web Agent

Upgrading Web Agents is the second step in the migration process.

CA SiteMinder® r12.x Web Agents can communicate with an 12.52 Policy Server. Therefore, upgrade a Policy Server to r12.5 before upgrading a Web Agent to 12.52.

Before You Upgrade an r12.x Web Agent

Before you upgrade Web Agents:

(UNIX) Be sure that you upgrade the Web Agent with the same account that was used to install it. If you use a different account, the upgrade can fail.
Be sure that the Policy Server is configured.
Identify the required administrator and Policy Server object names.
Identify the Web Agent requirements.

Ensure the Policy Server is Configured

Before you upgrade the Web Agent:

Be sure that the Policy Server can connect to the Web Agent host system.
Be sure that the Policy Server is running before registering trusted hosts. You start the Policy Server on the Status tab of the Policy Server Management Console.

Identify the Required Administrator and Policy Server Object Names

Before upgrading the Web Agent, you need the following information from the Policy Server administrator.

Name of the CA SiteMinder® Administrator allowed to register hosts.
Name of the Host Configuration Object.
Name of the Agent Configuration Object.

Identify the Web Agent Requirements

For more information about patches and other Web Agent requirements, see the Web Agent Installation Guide.

Upgrade an r12.x Web Agent

Use the 12.52 web agent installer to upgrade a web agent.

Agents that require option pack functionality must be upgraded to 12.52 before installing the 12.52 Web Agent Option Pack.
Note: For more information about upgrading a web agent, see the Web Agent Installation Guide. For more information about installing the 12.52 Web Agent Option Pack, see the Web Agent Option Pack Guide.
If you have deployed Advanced Password Services, a web agent upgrade retains all LANG (translation) and CFG (configuration) files. The default 12.52 versions of the files are installed to agent_home\samples.

agent_home

Specifies the web agent installation path.

Custom Agent Requirements

To determine if you are required to recompile your custom agent, use the following table:

Agent Type	Required?
CA SiteMinder® agent	Operating system–specific. If the agent operating system has reached end–of–life, you must recompile the custom agent. Upgrade the CA SiteMinder® SDK and recompile the agent on a supported operating system.
Third–party agent	Vendor–specific. Contact your third–party vendor to determine whether the agent is supported.

Agent Type

Required?

CA SiteMinder® agent

Operating system–specific.

If the agent operating system has reached end–of–life, you must recompile the custom agent.

Upgrade the CA SiteMinder® SDK and recompile the agent on a supported operating system.

Third–party agent

Vendor–specific.

Contact your third–party vendor to determine whether the agent is supported.

How to Upgrade an r12.x Policy Store

Complete the following procedures to upgrade an r12.x policy store to 12.52:

Stop all Policy Servers that are communicating with the policy store.
Import the policy store data definitions.
Import the default policy store objects.
If you managed your r12.x legacy federation environment using the FSS Administrative UI, run the XPS sweeper utility to complete the migration of your legacy federation objects.
Start all Policy Servers that are communicating with the policy store.

Stop all Policy Severs

Stopping all of the Policy Servers that are communicating with the policy store helps to prevent policy store corruption during the upgrade.

Follow these steps:

Log in to the Policy Server host system.
Complete one of the following steps:
- (Windows)
  1. Open the Policy Server Management Console and click Stop.
  2. Click OK to close the console.
- (UNIX) Use the following supplied script:
```
install_path/siteminder/stop-all
```
  install_path
  
  Specifies the Policy Server installation path.
Repeat this procedure for each Policy Server that is communicating with the policy store.

Import the Policy Store Data Definitions

Importing the policy store data definitions defines the types of objects that can be created and stored in the policy store.

Follow these steps:

Open a command window and navigate to siteminder_home\xps\dd.

siteminder_home

Specifies the Policy Server installation path.
Run the following command:
```
XPSDDInstall SmMaster.xdd
```
XPSDDInstall

Imports the required data definitions.

Import the Default Policy Store Objects

Importing the default policy store objects configures the policy store for use with the Administrative UI and the Policy Server.

Consider the following items:

Be sure that you have write access to siteminer_home\bin. The import utility requires this permission to import the policy store objects.

siteminder_home

Specifies the Policy Server installation path.
Before running a CA SiteMinder® utility or executable on Windows Server 2008, open the command line window with administrator permissions. Open the command line window this way, even if your account has administrator privileges. For more information, see the release notes for your CA SiteMinder® component.

Follow these steps:

Open a command window and navigate to siteminder_home\db.
Import one of the following files:
- To import smpolicy.xml, run the following command:
```
XPSImport smpolicy.xml -npass
```
- To import smpolicy–secure.xml, run the following command:
```
XPSImport smpolicy-secure.xml -npass
```
Note: You use either file to configure a new policy store and upgrade an existing store. When imported as part of an upgrade, the file does not overwrite existing default objects that were modified. Both files include the default policy store objects. These objects include the default security settings in the default Agent Configuration Object (ACO) templates. The secure file provides more restrictive security settings.

–npass

Specifies that no passphrase is required. The default policy store objects do not contain encrypted data.

The default policy store objects are imported.

Run the XPS Sweeper Utility

If you managed your Federation Security Services (legacy federation) objects using the FSS Administrative UI, run the XPS sweeper utility (XPSSweeper) to complete the migration of these objects.

Follow these steps:

Log in to the Policy Server host system.
Run the following command to make available your legacy federation objects to the Administrative UI:
```
XPSSweeper
```
All legacy federation created using the FSS Administrative UI are available in the Administrative UI.

Start all Policy Servers

Starting all Policy Servers resumes communication between all of the Policy Servers and the upgraded policy store.

Follow these steps:

Log in to the Policy Server host system.
Complete one of the following steps:
- (Windows)
  1. Open the Policy Server Management Console and click Start.
  2. Click OK to close the console.
- (UNIX) Use the following supplied script:
```
install_path/siteminder/start-all
```
  install_path
  
  Specifies the Policy Server installation path.
Repeat this procedure for each Policy Server that is communicating with the policy store.

The policy store is upgraded.

Upgrade an r12.x Administrative UI

The following sections detail how to upgrade the Administrative UI on Windows and UNIX.

Before You Upgrade

Consider the following items before you upgrade the Administrative UI:

Important! Review the Administrative UI upgrade paths.
Upgrade the Administrative UI using the installation media on the Technical Support site.
Note: For a list of installation media names, see the Policy Server Release Notes.
(Embedded JBoss installations only) Extract the contents of the prerequisite installer into the same directory that you extracted the contents of the Administrative UI installer. The contents of each installer zip file must be in the same location as the layout.properties file. The layout.properties file, which is included with the Administrative UI installation zip, must always be co-located with both executables or the installation fails.
(Windows) Run the installer from the Administrative UI host system. Do not run the installer from a mapped network share or UNC path.
(Linux) Be sure that the required Linux libraries are installed to the Administrative UI host system. For more information, see Required Linux Libraries.
Important! (UNIX) Depending on your permissions, run the following command to add executable permissions to the directory that contains the installation media:
```
chmod -R+x directory
```
directory

Specifies the directory that contains the installation media.
(UNIX) If you execute the Administrative UI installer across different subnets, it can crash. Run the Administrative UI installer directly on the host system.

More information:

Locate the Installation Media

Installation Media Names

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 libraries 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

Red Hat 6.x:

libstdc++-4.x.x-x.el6.i686.rpm

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

Note: 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

Upgrade the Administrative UI on Windows

Follow these steps:

(Embedded JBoss setups only). Verify that you extracted the prerequisite installer zip into the same directory that you extracted the Administrative UI installer zip. The layout.properties file, included with the Administrative UI installation zip, must be located in the same directory as both executables.
Note: If you move the prerequisite or Administrative UI installation executables after extracting the zips, move the layout.properties file to the same location.
Exit all applications that are running.
Stop the application server that is hosting the Administrative UI.
Note: For information about stopping and starting the embedded JBoss application server, see the r12.x Policy Server Installation Guide. For information about stopping an existing application server, see the vendor-specific documentation.
For embedded JBoss installations only, run the following executable and follow the installer prompts. Otherwise, skip to the next step.
```
adminui-pre-req-version-cr-win32.exe
```
Run the following executable:
```
ca-adminui-version-cr-win32.exe
```
Follow the installer prompts and confirm upgrade of the Administrative UI.
Review the installation settings and click Install.
For existing application servers, restart the application server after the installation is complete.
Note: The embedded JBoss application server automatically restarts after the installation is complete.

The Administrative UI is upgraded.

Upgrade the Administrative UI on UNIX

You can install the Administrative UI on UNIX platforms in GUI or Console mode.

Follow these steps:

(Embedded JBoss setups only). Verify that you extracted the prerequisite installer zip into the same directory that you extracted the Administrative UI installer zip. The layout.properties file, included with the Administrative UI installation zip, must be located in the same directory as both executables.
Note: If you move the prerequisite or Administrative UI installation executables after extracting the zips, move the layout.properties file to the same location.
Exit all applications that are running.
Stop the application server that is hosting the Administrative UI.
Note: For information about stopping and starting the embedded JBoss application server, see the r12.x Policy Server Installation Guide. For information about stopping an existing application server, see the vendor-specific documentation.
For embedded JBoss installations only, run the prerequisite installer. Otherwise, skip to the next step.
1. Open a shell and navigate to one of the following prerequisite installation executables:
```
adminui-pre-req-version-cr-linux.bin
adminui-pre-req-version-cr-sol.bin
```
2. Enter the command for the appropriate mode:
  GUI Mode
```
./prerequisite_installation_media
```
  Console Mode
```
./prerequisite_installation_media -i console
```
3. Follow the prerequisite installer prompts.
Open a shell and navigate to one of the following installation executables:
```
ca-adminui-version-cr-linux.bin
```
```
ca-adminui-version-cr-sol.bin
```
Enter the command for the appropriate mode:
GUI Mode
```
./installation_media
```
Console Mode
```
./installation_media -i console
```
Follow the prompts and confirm the upgrade of the Administrative UI.
Review the installation settings and click Install.
Start the application server that is hosting the Administrative UI.
Note: For information about stopping and starting the embedded JBoss application server, see the r12.x Policy Server Installation Guide. For information about stopping an existing application server, see the vendor-specific documentation.

The Administrative UI is upgraded.

Upgrade an r12.x Report Server

If you are using a Report Server version that is previous to r12.0 SP3 CR4, the simplest path to the 12.52 reporting environment is to uninstall the installed version, and then install and configure the 12.52 reporting components.

If you are using a Report Server r12.0 SP3 CR4 or higher, an upgrade is not required. However, if you want localized reports, you require the 12.52 reporting templates. So, run the 12.52 version of the Report Server Configuration Wizard for the reporting templates.

The Report Server uses data in the policy store and the CA SiteMinder® audit database to compile policy analysis and audit–based reports. The report database contains no information that these reports require. As a result, a migration from an r12.x report database to an 12.52 report database is not necessary.

Complete the following process to install and configure the 12.52 reporting components:

(Optional) Export existing reports.
Important! Existing reports are stored in the report database. If you require existing reports for historical purposes, use the Administrative UI to view the reports and export them to a temporary location. For more information about viewing reports, see the Policy Server Administration Guide.
Delete the connection between Report Server and the Administrative UI.
Note: For more information, see the Policy Server Installation Guide.
Uninstall the r12.x Report Server.
Note: For more information, see the r12 SP2 Policy Server Installation Guide. Uninstalling the Report Server does not remove the tables in the report database. Access the report database and remove all tables manually.
Install and configure 12.52 reporting, which includes:
1. Installing the Report Server.
2. Installing the CA SiteMinder® report templates.
3. Registering the Report Sever.
4. Configuring connectivity between the Report Server and a CA SiteMinder® audit database.
Note: For more information, see the Policy Server Installation Guide.