How to Configure a Parallel Environment

Installation and Upgrade Guides › SiteMinder Upgrade Guide › Upgrading from r6.x › How to Configure a Parallel Environment

How to Configure a Parallel Environment

Complete the follow procedures to configure a parallel environment:

Review the parallel environment key management options to determine how to implement single sign–on.
Create the 12.52 environment.
Complete one of the following steps:
- Be sure that both environments meet the common key store single sign–on requirements.
- Be sure that both environments meet the multiple key store single sign–on requirements.
If your r6.x environment contains smkeydatabases:
1. Synchronize all instances.
2. Migrate the content of a smkeydatabase to the 12.52 certificate data store.
If you are managing legacy federation (Federation Security Services) objects in your r6.x environment, migrate the assertion issuer ID.
(Optional) Migrate the r6.x policy store data.
Review the user directory single sign–on requirements.

More information:

Certificate Data Management

Synchronize Key Database Instances

Parallel Environment Key Management Options

Managing CA SiteMinder® keys to maintain single sign–on between the existing environment and 12.52 environment is critical to a successful parallel upgrade. Two CA SiteMinder® key management options are available. The option you deploy depends on how you implement one or more key stores across both environments. The options include:

Multiple policy stores with a common key store
Multiple policy stores with separate key stores

Common Key Store Deployment

All Policy Servers can use a single key store for key rollover. The following figure illustrates:

r6.x Policy Servers connecting to an r6.x policy store.
12.52 Policy Servers connecting to an 12.52 policy store.
A common r6.x key store maintaining key data for all Policy Servers. The common key store lets agents that are associated with all Policy Server share keys. Sharing the keys enables single sign–on between both environments.
Important! The r6.x key store must be configured separately from the r6.x policy store.
All Policy Servers connecting to a common key store to retrieve new keys.
Important! The 12.52 Policy Servers must be configured with the r6.x key store. r6.x Policy Servers cannot communicate with an 12.52 key store.
All Web Agents polling their respective Policy Server to retrieve new keys.

Note: Although not illustrated, policy store and key store data can be replicated for failover. The database or directory server type determines how you replicate data. For more information about key management in a master/slave environment, see the Policy Server Administration Guide.For more information about replicating data, see your vendor–specific documentation.

Graphic showing an r6.x common key store deployment

Multiple Key Store Deployment

Existing r6.x Policy Servers can use an r6.x key store for key rollover, while 12.52 Policy Servers can use an 12.52 key store for key rollover. The following figure illustrates:

r6.x Policy Servers connecting to an r6.x policy store.
12.52 Policy Servers connecting to an 12.52 policy store.
r6.x Policy Servers connecting to an r6.x key store to retrieve new keys.
12.52 Policy Servers connecting to an 12.52 key store to retrieve new keys.
A CA SiteMinder® administrator using the Administrative UI to configure static Agent and Session keys for each key store.
Important! If all key stores do not use the same Agent and Session keys, single sign–on fails.
r6.x Web Agents polling their respective r6.x Policy Servers to retrieve new keys.
12.52 Web Agents polling their respective 12.52 Policy Servers to retrieve new keys.

Note: Although not illustrated, policy store and key store data can be replicated for failover. The database or directory server type determines how you replicate data. For more information about key management in a master/slave environment, see the Policy Server Administration Guide. For more information about replicating data, see your vendor–specific documentation.

Graphic showing an r6.x multiple key store deployment

Create the 12.52 Environment

You can configure an 12.52 environment independently of the existing environment. Install and configure the 12.52 components in the following order:

One or more Policy Servers.
Important! If you are maintaining single sign–on with a common key store, all Policy Servers must use the same encryption key. If you do not know the value of the encryption key, you can reset the r6.x value in the policy store. Use the new value when installing 12.52 Policy Servers.

Note: For more information about resetting the policy store encryption key, see the Policy Server Administration Guide.
A policy store.
An Administrative UI.
One or more Web Agents.
A Report Server

Note: For more information about installing a Policy Server, a policy store, an Administrative UI, and a Report Server, see the Policy Server Installation Guide. For more information about installing Web Agents, see the Web Agent Installation Guide.

Common Key Store Single Sign–on Requirements

If you are deploying a common key store, do the following or single sign–on fails:

Be sure that the r6.x policy and key store are configured separately:
- If the r6.x environment is configured with a separate key store, leave the key store version at r6.x. 12.52 Policy Servers can communicate with an r6.x key store, but r6.x Policy Servers cannot communicate with an 12.52 key store.
- If the r6.x environment is configured with a collocated policy/key store, separate the r6.x keys in to a separate r6.x key store.
Configure all Policy Servers to use the common r6.x key store.
Be sure that all Policy Servers use the same encryption key. If you do not know the value of the encryption key, you can reset the r6.x value in the policy store. Use the new value when installing an 12.52 Policy Server.
Note: For more information about resetting the policy store encryption key, see the Policy Server Administration Guide.
Nominate a single Policy Server to generate dynamic Agent keys. Disable Agent key generation for the remaining Policy Servers.
Note: For more information about dynamically generating Agent keys, see the Policy Server Administration Guide.

More information:

Reset the r6.x Policy Store Encryption Key

How to Separate a Key Store from a Policy Store

Complete the following procedures to separate the key store from the policy store:

Install or locate a set–up Policy Server. A set–up Policy Server is a Policy Server that is not configured with the collocated policy/key store.
- If a Policy Server is configured with the collocated store, you cannot use it to configure the new key store instance. The required CA SiteMinder® utilities available on the Policy Server host system are configured to manage the collocated store.
- The set–up Policy Server makes available a separate set of the required utilities. The separate set lets you configure the key store without interfering with the collocated store.
Use the set–up Policy Server host system to create a separate r6.x key store instance. Consider the following items:
- The key store only requires the default policy store schema. For more information about importing the default policy store schema, see the r6.x Policy Server Installation Guide.
- The key store does not require that you:
  - Set the CA SiteMinder® superuser password.
  - Import the default policy store objects.
Disable dynamic agent key generation in the r6.x environment.
Note: If your environment uses static keys, this step is not required. However, be sure that a CA SiteMinder® administrator does not generate a random agent key after you export the keys from the policy store.
Export the agent keys from the r6.x policy/key store.
Import the agent keys in to the r6.x key store.
Configure all Policy Servers to use the separate key store.
If you disabled dynamic agent key generation, re–enable it.

Disable Dynamic Agent Key Generation

Before the key store separation is complete, the r6.x environment is operating with two key stores:

Some Policy Servers use the agents keys in the collocated policy/key store.
Some Policy Servers use the agent keys in the separate key store.

Disabling dynamic agent key generation prevents a Policy Server from generating keys after you export them for the separate store. Stopping the Policy Server from generating keys prevents single sign–on issues that can occur when the keys are not synchronized in all stores.

Follow these steps:

Log in to the r6.x Policy Server user interface.
Select Tools, Manage Keys.
Select the Use Static Agent Key option.
Click Apply.
The Policy Server is configured to use a static key. The Policy Server does not generate keys automatically.

Export the Agent Keys

You export the keys from the collocated policy/key store to make them available to the separate key store.

Follow these steps:

Log in to a r6.x Policy Server host system. Be sure that this Policy Server is configured with the collocated policy/key store.
Run the following command to export only the keys from the policy store:
```
smobjectexport -ffile_name -x
```
Important! 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.

Note: For more information about these modes and arguments, see the r6.x Policy Server Installation Guide.

Example:
```
smobjexport -fagentkeys -x
```
The agent keys are exported from the collocated policy/key store.
Copy the file that contains the agent keys to the set–up Policy Server host system.

Import the Agent Keys

You import the keys from the collocated policy/key store to make them available to the separate key store.

Follow these steps:

Log in to the r6.x set–up Policy Server host system.
Run the following command to import the agent keys in to the separate key store:
```
smobjimport -ffile_name -k
```
Important! 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.

Note: For more information about these modes and arguments, see the r6.x Policy Server Installation Guide.

Example:
```
smobjimport -fagentkeys -k
```
The agent keys are imported in to the separate key store.

Configure all Policy Servers to use the Key Store

Configuring all Policy Servers in the parallel environment to use a common r6.x key store maintains single sign–on across both environments.

Follow these steps:

Identify the Policy Server that is nominated to generate agent keys dynamically. Configure this Policy Server with the key store last.
Complete the following procedure for all other Policy Servers in the environment:
1. Log in to the Policy Server host system.
2. Open the Policy Server Management Console.
3. Click the Data tab.
4. Select Key Store from the Database list and clear the Use Policy Store database option.
5. Select the key store type from the Storage list.
6. Do one of the following steps:
  1. (LDAP) Enter the required connection information in the LDAP Key Store section.
  2. (ODBC) Enter the data source information in the Data Source Information section.
7. Test the Connection.
8. Click OK.
9. Restart the Policy Server to configure the Policy Server to use the key store.
Configure the Policy Server that is nominated to generate agent keys to use the key store.

Re–enable Dynamic Agent Key Generation

If you disabled dynamic agent key generation, re–enable the functionality for the Policy Server that is nominated to generate agent keys. Complete this procedure only after all Policy Servers in the environment are configured to use the new key store.

Follow these steps:

Log in to the r6.x Policy Server user interface.
Select Tools, Manage Keys.
Select the Use Dynamic Agent Key option.
Click Apply.
The nominated Policy Server is enabled to generate keys dynamically.

You have completed the required tasks to separate the key store from the policy store.

Multiple Key Store Single Sign–on Requirements

If you are deploying multiple key stores, do the following or single sign–on fails:

Disable dynamic Agent key generation for all Policy Servers.
Be sure that a CA SiteMinder® administrator has the necessary Policy Server User Interface and Administrative UI permissions to specify the same static Agent key and the same session ticket in the r6.x and 12.52 key store.
Note: For more information about delegating administrator permissions, see the Policy Server Configuration Guide.
Important! Be sure that the same static Agent key and the same session ticket are configured in the r6.x and 12.52 key stores.
Note: For more information about configuring a static Agent key and session ticket, see the Policy Server Administration Guide.

Migrate Keys and Certificates

If your environment contains one or more smkeydatabases, migrate their contents to the 12.52 certificate data store.

Follow these steps:

Be sure that all r6.x smkeydatabases are synchronized.
Log in to an r6.x Policy Server host system and go to the following location:
```
siteminder_home\config\properties
```
siteminder_home

Specifies the Policy Server installation path.
Copy the following file:
```
smkeydatabase.properties
```
Log in to an 12.52 Policy Server host system and complete the following steps:
1. Go to the following location:
```
siteminder_home\config\properties
```
2. Rename the 12.52 version of the smkeydatabase properties file to the following value:
```
newsmkeydatabase.properties
```
3. Add the r6.x version of the properties file to the directory.
4. Open the 12.52 and r6.x properties file in a text editor.
5. Edit the database location path in the r6.x version to match the path in the 12.52 version.
  Example:
  
  The r6.x file references the following path:
```
DBLocation=C\:/Program Files/netegrity/siteminder/smkeydatabase
```
  The 12.52 file references the following path:
```
DBLocation=C:/Program Files/CA/siteminder/smkeydatabase
```
  Update the r6.x file to reference the following path:
```
DBLocation=C\:/Program Files/CA/siteminder/smkeydatabase
```
6. Save the r6.x properties file and close the 12.52 properties file.
7. Create the following directory at the root of the Policy Server installation:
```
smkeydatabase
```
  Example:
```
C:\Program Files\CA\SiteMinder\smkeydatabase
```
Return to the r6.x Policy Server host system and copy the contents of the smkeydatabase directory.
Note: The default location of this directory is siteminder_home.
Return to the 12.52 Policy Server host system and complete the following steps:
1. Add the contents of the r6.x smkeydatabase directory to the 12.52 smkeydatabase directory you created.
2. Use the following migration utility to migrate the smkeydatabase to the certificate data store.
```
smmigratecds
```
3. After a successful migration, remove the smkeydatabase properties file and the smkeydatabase directory.
The migration is complete.

More information:

Migrate a CA SiteMinder® Key Database Manually

Migrate the Assertion Issuer ID

If you are managing legacy federation (Federation Security Services) objects in your r12.x environment, migrate the assertion issuer ID from the r12.x Producer to the 12.52 Producer. Migrating the ID prevents SAML 1.1 transactions from failing on the Service Provider.

Follow these steps:

Log in to an r6.x Policy Server host system and go to the following location:
```
siteminder_home\config\properties
```
siteminder_home

Specifies the Policy Server installation path.
Copy the following file:
```
AMAssertionGenerator.properties
```
Log in to an 12.52 Policy Server host system and go to the following location:
```
siteminder_home\config\properties
```
Rename the 12.52 version of the assertion generator properties file to the following value:
```
newAMAssertionGenerator.properties
```
Add the r6.x version of the properties file to the directory.
The migration is complete.

Migrate the r6.x Policies

If you plan on using the 12.52 deployment to protect r6.x resources, we recommend migrating your policy store data to the 12.52 policy store.

You can avoid the possibility of conflicts that are associated with duplicate objects by migrating policy store data before you begin managing the 12.52 policy store.

Follow these steps:

Use the r6.x version of the smobjexport utility to export the r6.x policy store data.
Note: For more information about the r6.x version of the smobjexport utility, see the r6.x Policy Server Installation Guide.
Use the 12.52 version of the smobjimport utility to import the policy data into the 12.52 policy store.
When moving CA SiteMinder® policies from one environment to another, either as part of an upgrade or a policy migration, some objects that are environment–specific are included in the export file. Examples of these objects include:
- Trusted hosts
- HCO Policy Server settings
- Authentication scheme URLs
- Password services redirects
- Redirect responses

User Directory Single Sign–on Requirements

Be sure that the CA SiteMinder® user directory objects you create in both environments have the same names. If you use different names to point r6.x and 12.52 Policy Servers to the same user stores, single sign–on fails.