Previous Topic: How a Parallel Upgrade WorksNext Topic: Using FIPS-Compliant Algorithms


How to Configure a Parallel Environment

Complete the following procedures to configure a parallel environment:

  1. Review the parallel environment key management options to determine how to implement single sign–on.
  2. Create the 12.52 environment.
  3. Do one of the following:
  4. Migrate the r12.x policy store data. Use the 12.52 version of the XPSImport utility to import 12.52 default policy objects to the 12.x policy store using the following command
    XPSImport smpolicy.xml -npass
    
  5. If your r12.x environment contains smkeydatabases:
    1. Synchronize all instances.
    2. Migrate the content of a smkeydatabase to the 12.52 certificate data store.
  6. If you are managing legacy federation (Federation Security Services) objects in your r12.x environment, migrate the assertion issuer ID.
  7. 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:

Common Key Store Deployment

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

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 the r12.x common key store deployment

Multiple Key Store Deployment

Existing r12.x Policy Servers can use an r12.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:

r12.x Web Agents polling their respective r12.x 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 r12.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:

  1. 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 r12.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.

  2. A policy store.
  3. An Administrative UI.
  4. One or more Web Agents.
  5. 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:

How to Separate a Key Store from a Policy Store

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

  1. 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.
  2. Use the set–up Policy Server host system to create a separate r12.x key store instance. Consider the following items:
  3. Disable dynamic agent key generation in the r12.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.

  4. Export the agent keys from the r12.x policy/key store.
  5. Import the agent keys in to the r12.x key store.
  6. Configure all Policy Servers to use the separate key store.
  7. If you disabled dynamic agent key generation, re–enable it.
Disable Dynamic Agent Key Generation

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

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:

  1. Log in to the r12.x Administrative UI.
  2. Click Administration, Policy Server.
  3. Click Key Management, Agent Key Management.
  4. Select the Use Static Agent Key option.
  5. Click Submit.

    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:

  1. Log in to a r12.x Policy Server host system. Be sure that this Policy Server is configured with the collocated policy/key store.
  2. Run the following command to export only the keys from the policy store:
    smkeyexport -dadministrator -wpassword -ofile_name
    

    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 the utility, see the r12.x Policy Server Administration Guide.

    Example:

    smkeyexport -dsuperuser -wpassword -oagentkeys
    

    The agent keys are exported from the collocated policy/key store.

  3. 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:

  1. Log in to the r12.x set–up Policy Server host system.
  2. 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 r12.x Policy Server Administration 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 r12.x key store maintains single sign–on across both environments.

Follow these steps:

  1. Identify the Policy Server that is nominated to generate agent keys dynamically. Configure this Policy Server with the key store last.
  2. Complete the following steps 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. Complete one of the following steps:
      • (LDAP) Enter the required connection information in the LDAP Key Store section.
      • (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.
  3. 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:

  1. Log in to the r12.x Administrative UI.
  2. Click Administration, Policy Server.
  3. Click Key Management, Agent Key Management.
  4. Select the Use Dynamic Agent Key option.
  5. Click Submit.

    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:

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:

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

    Specifies the Policy Server installation path.

  3. Copy the following file
    smkeydatabase.properties
    
  4. 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 r12.x version of the properties file to the directory.
    4. Open the 12.52 and r12.x properties file in a text editor.
    5. Edit the database location path in the r12.x version to match the path in the 12.52 version.

      Example:

      The r12.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 r12.x file to reference the following path:

      DBLocation=C\:/Program Files/CA/siteminder/smkeydatabase
      
    6. Save the r12.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
      
  5. Return to the r12.x Policy Server host system and copy the contents of the smkeydatabase directory.

    Note: The default location of this directory is siteminder_home.

  6. Return to the 12.52 Policy Server host system and complete the following steps:
    1. Add the contents of the r12.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:

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

    Specifies the Policy Server installation path.

  2. Copy the following file:
    AMAssertionGenerator.properties
    
  3. Log in to an 12.52 Policy Server host system and go to the following location:
    siteminder_home\config\properties
    
  4. Rename the 12.52 version of the assertion generator properties file to the following value:
    newAMAssertionGenerator.properties
    
  5. Add the r12.x version of the properties file to the directory.

    The migration is complete.

Migrate the r12.x Policies

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

Although not required, if you migrate the policy store data before you begin managing the 12.52 policy store, you can avoid the possibility of conflicts associated with duplicate objects.

To migrate policies

  1. Use the r12.x version of the XPSExport utility to export the r12.x policy store data. For more information about the r12.x version of XPSExport, see the r12.x Policy Server Administration Guide.
  2. Use the 12.52 version of the XPSImport utility to import the policy data into the 12.52 policy store. For more information about the 12.52 version of XPSImport, see the Policy Server Administration Guide.

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:

Depending on the mode you select when using XPSExport, these objects may be added to the new environment or can overwrite existing settings. Be sure that you do not adversely affect environment settings when importing the objects.

Note: For more information about the XPSExport modes of export, see the Policy Server Administration Guide.

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 r12.x and 12.52 Policy Servers to the same user stores, single sign–on fails.