Sun OpenSSO Enterprise 8.0 Upgrade Guide

Upgrading to OpenSSO Enterprise 8.0

Use the following list of procedures to upgrade the previous release to OpenSSO Enterprise 8.0.

  1. Getting OpenSSO Enterprise 8.0

  2. Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR

  3. Removing the Previously Installed Server Software

  4. Deploying the Open SSO Enterprise 8.0 WAR

  5. Running the Pre-Upgrade Script

  6. Modifying ssoUpgradeConfig.properties and AMConfig.properties.bak

  7. Configuring Open SSO Enterprise 8.0 Against the Existing Access Manager or Federation Manager Schema

  8. Upgrading the Existing Access Manager or Federation Manager Schema

Getting OpenSSO Enterprise 8.0

OpenSSO Enterprise 8.0 is distributed as a downloadable ZIP file named opensso_enterprise_80.zip. This ZIP file contains functionality originally developed for both Access Manager and Federation Manager functionality, as well as new OpenSSO Enterprise 8.0 features.

ProcedureTo Download and Unzip opensso_enterprise_80.zip

  1. Log in to the host machine as super user (root).

  2. Create a base directory in which to download and unzip opensso_enterprise_80.zip.

    This guide uses zip-root as the name of the base directory. You must have both read and write access to this directory.


    # mkdir /zip-root
    # cd /zip-root
    
  3. Download the opensso_enterprise_80.zip file from the following site to the zip-root directory.

    Sun Downloads site under View by Category, Identity Management, and then OpenSSO Enterprise: http://www.sun.com/download/index.jsp

  4. Unzip opensso_enterprise_80.zip.

    The upgrade scripts and related files are in the zip-root/opensso/upgrade directory.


    Note –

    Check the permissions on the ssopre80upgrade and ssoupgrade scripts. If these scripts do not have the execute permission, reset the permissions using chmod.


Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR

After unzipping opensso_enterprise_80.zip, you will find opensso.war in /zip-root/opensso/deployable-war. Now create a staging directory into which opensso.war can be exploded. If you customized any files in your previous Access Manager or Federation Manager deployment, you will need to apply these customizations to the files in the staging directory.


Note –

Even if you have not customized your previous deployment, you must create a staging directory as the path to this directory is used for input when running the upgrade scripts.


ProcedureTo Create a Staging Directory and OpenSSO Enterprise 8.0 WAR

Before You Begin

This procedure assumes you are still logged in to the host machine as super user.

  1. Create a staging directory for the new WAR.


    Caution – Caution –

    Do not create the staging directory in the tmp directory.



    # mkdir /staging
    
  2. Extract the files from opensso.war into the staging directory.


    # cd /staging
    # jar xvf /zip-root/opensso/deployable-war/opensso.war
    
  3. (Optional) Add any customized files from your previous Access Manager or Federation Manager deployment to the OpenSSO Enterprise WAR staging directory.

    For example, copy any modified JSP files for the Administration Console to the staging directory.


    Note –

    Be sure to remove the file you are replacing.


  4. Create a new WAR from the files in the staging directory.

    The name of the new WAR must use the same deployment URI as the previously installed Access Manager or Federation Manager instance. For example, if the previous instance is deployed with the /amserver URI, the new WAR must be named amserver.war.


    # jar cvf /zip-root/opensso/deployable-war/amserver.war *
    

Removing the Previously Installed Server Software

Remove previously installed software dependant on what was installed and how it was initially installed. You might have to do one or all of the following depending on your deployment.

Deploying the Open SSO Enterprise 8.0 WAR

In this procedure, deploy the new OpenSSO Enterprise 8.0 WAR created in Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR.

ProcedureTo Deploy the Open SSO Enterprise 8.0 WAR

Before You Begin
  1. Deploy the OpenSSO Enterprise WAR using your web container's administration console or command line interface.

    Use the same host name, port and URI (/amserver) on which the previous Access Manager or Federation Manager instance was deployed. In this example, amserver.war (created in Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR) is located in /zip-root/opensso/deployable-war.

  2. Restart the OpenSSO Enterprise web container.

Running the Pre-Upgrade Script

Run the ssopre80upgrade script (ssopre80upgrade.bat on Windows) when you are upgrading package based installations; for example, instances of Access Manager installed using Java Enterprise System (JES) 4 or JES 5 will put Access Manager packages on the host machine but a WAR that has been downloaded and deployed will not. ssopre80upgrade prepares the system for upgrade by:


Note –

Entering path names on Windows When you run the ssopre80upgrade.bat script, replace each backslash (\) in path names to a forward slash (/). For example, for C:\sun\opensso\config, you would enter C:/sun/opensso/config.


ProcedureTo Execute the ssopre80upgrade Script

Before You Begin
  1. Change to the /zip-root/opensso/upgrade/scripts directory.

  2. Run the ssopre80upgrade script.

    On Solaris and Linux systems, enter ./ssopre80upgrade. On Windows systems, enter ssopre80upgrade.bat. The script checks whether you are upgrading an instance of Access Manager or Federation Manager.


    # check_instance isFM is : false 
    # A log of the ssopreupgrade process can be found in 
    /var/sadm/install/logs/Sun_Java_System_Access_Manager_
    upgrade_log.03101744
  3. When prompted, accept the default values or provide information based on the deployment.

    • Directory Server fully qualified host name

    • Directory Server port

    • Top-level administrator DN (uid=amAdmin,ou=People,dc=sun,dc=com)

    • Top-level administrator (uid=amAdmin,ou=People,dc=sun,dc=com) password

    • Directory to store backup files (/opt/SUNWam)

    • OpenSSO Enterprise 8.0 configuration directory is the path to the configuration directory for the original instance of Access Manager that you are upgrading. For example: /etc/opt/SUNWam

    • OpenSSO Enterprise 8.0 upgrade directory is the path to the exploded OpenSSO ZIP. For example: /zip-root/opensso

    • OpenSSO Enterprise 8.0 staging directory is the path to the directory in which the OpenSSO WAR was exploded. For example: /staging

    • OPTIONAL: Access Manager installation directory (Windows only)

    • OPTIONAL: Federation Manager 7.0 staging directory (Federation Manager only)

    After the final value is entered, ssopre80upgrade removes the previous version of the server software and its packages.

Next Steps

If upgrading a Linux installation remember to edit ssoupgrade and return it to the /zip-root/opensso/upgrade/scripts directory.

Modifying ssoUpgradeConfig.properties and AMConfig.properties.bak

In preparation for the final procedures in the upgrade process, modify two properties files.

ProcedureTo Modify ssoUpgradeConfig.properties and AMConfig.properties.bak

Before You Begin

This procedure assumes you are still logged in to the host machine as super user.

  1. Rename the previous version's configuration files (AMConfig.properties and serverconfig.xml) using the .bak extension.


    # cp AMConfig.properties AMConfig.properties.bak
    # cp serverconfig.xml serverconfig.xml.bak
    
  2. Move the renamed configuration files (AMConfig.properties.bak and serverconfig.xml.bak) to the /zip-root/opensso/upgrade/config directory.


    # mv AMConfig.properties.bak /zip-root/opensso/upgrade/config/
    # mv serverconfig.xml.bak /zip-root/opensso/upgrade/config/
    
  3. Change to the /zip-root/opensso/upgrade/config/ directory.

  4. Open ssoUpgradeConfig.properties in a text editor and set the following properties.

    • XML_ENCODING: For example: XML_ENCODING=UTF-8

    • BASEDIR: The directory in which the OpenSSO Enterprise 8.0 ZIP is exploded. For example: BASEDIR=/zip-root/opensso

    • ORG_NAMING_ATTR: Organization naming attribute. Default is o. For example: ORG_NAMING_ATTR=o

    • USER_NAMING_ATTR: User naming attribute. Default is uid. For example: USER_NAMING_ATTR=uid

    • DEPLOY_URI: OpenSSO Enterprise deployment URI. For example: DEPLOY_URI=amserver

    • PAM_SERVICE_NAME:

      • Solaris systems: PAM_SERVICE_NAME=other

      • Linux systems: PAM_SERVICE_NAME=password


      Note –

      PAM is the Pluggable Authentication Module for Unix. The defined name is based on the operating system flavor.


    • DB_NAME: OpenSSO Enterprise back-end database. Default name: userRoot

    • INSTANCE_TYPE: Set to the instance type you are upgrading:

      • Access Manager: INSTANCE_TYPE=AM

      • Federation Manager: INSTANCE_TYPE=FM

    • LDAP_USER_PASS: amldapuser password

    • ORG_OBJECT_CLASS=sunismanagedorganization is the default.

    • USER_OBJECT_CLASS=inetorgperson is the default.

  5. Save ssoUpgradeConfig.properties.

  6. Open AMConfig.properties.bak in a text editor and make the following modifications.

    Earlier versions of OpenSSO Enterprise supported, by default, Java Security Services (JSS) encryption. Now, by default, OpenSSO Enterprise supports Java Cryptography Extension (JCE) encryption.

    1. Change the value of com.iplanet.security.SecureRandomFactoryImpl from com.iplanet.am.util.JSSSecureRandomFactoryImpl to com.iplanet.am.util.SecureRandomFactoryImpl.

    2. Change the value of com.iplanet.security.SSLSocketFactoryImpl from com.iplanet.services.ldap.JSSSocketFactory to netscape.ldap.factory.JSSESocketFactory.

    3. Change the value of com.iplanet.security.encryptor from com.iplanet.services.util.JSSEncryption to com.iplanet.services.util.JCEEncryption.


    Caution – Caution –

    If you use a web container not developed and branded by Sun Microsystems (something other than Glassfish, Web Server and Application Server), it is recommended to make this change.


  7. Save AMConfig.properties.bak.

Configuring Open SSO Enterprise 8.0 Against the Existing Access Manager or Federation Manager Schema

After you deploy the OpenSSO Enterprise WAR, configure the new OpenSSO Enterprise instance against the existing Access Manager or Federation Manager schema using the Configurator.


Note –

You can also use command-line configuration as described in Chapter 5, Configuring OpenSSO Enterprise Using the Command-Line Configurator, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.


ProcedureTo Configure OpenSSO Enterprise Against the Existing Access Manager or Federation Manager Schema

Before You Begin

This procedure assumes you have deployed the OpenSSO Enterprise WAR.

  1. Launch the GUI Configurator by entering the OpenSSO Enterprise URL in your browser.

    Use the format protocol://server-host:server-port/deployuri. For example: http://abc.example.com:8080/amserver.

  2. On the Configuration Options page, click Create New Configuration.

  3. On the Default User Password page, enter and confirm the amAdmin password.

    Use the same password as the one defined for the Access Manager or Federation Manager instance you are upgrading.

  4. Click Next to continue.

  5. On the Server Settings page, enter values for the following:

    • Server URL: Use the same value as the one defined for the Access Manager or Federation Manager instance you are upgrading

    • Cookie Domain: Use the same value as the one defined for the Access Manager or Federation Manager instance you are upgrading

    • Platform Locale: Use the same value as the one defined for the Access Manager or Federation Manager instance you are upgrading

    • Configuration Directory: Use the default value (/opensso) or specify another value.

  6. Click Next to continue.

  7. On the Configuration Data Store Settings, do the following:

    1. Check First Instance.

    2. For Configuration Data Store, check Sun Java System Directory Server.

    3. Specify the following Directory Server values from the existing Access Manager or Federation Manager instance:

      • SSL Enabled: Disable for the upgrade process.

      • Host Name

      • Port

      • Encryption Key

      • Root Suffix: Enter the root suffix defined by the installation of the older version being replaced.

      • Login ID: Directory Server Administrator DN

      • Password: Directory Server Administrator password

  8. Click Next to continue.

  9. On the User Data Store Settings page, do the following:

    Click Use Other User Data Store to specify Sun Java System Directory Server and specify the Directory Server values from the existing Access Manager or Federation Manager instance:

    • SSL Enabled: Disable for the upgrade process.

    • Directory Name: In this example, it is the same as the Host Name without the domain qualifiers.

    • Port:

    • Root Suffix: Use a different root from the one defined for the Configuration Data Store.

    • Login ID: Directory Server Administrator DN

    • Password: Directory Server Administrator password

    • User Data Store Type: Check LDAP with OpenSSO Schema

  10. Click Next to continue.

  11. On the Site Configuration page, check No and click Next to continue.

  12. On the Default Policy Agent User page, enter and confirm the password for the Policy Agent user.

    The default Policy Agent user is UrlAccessAgent. The password is usually the same as the password of amldapuser.

  13. Click Next to continue.

  14. Verify that the Configuration Summary Details are correct and click Create Configuration.

    When the configuration is complete, the Configurator displays a link to redirect you to the OpenSSO Enterprise administration console.

  15. Log in to the OpenSSO Enterprise Administration Console as amadmin using the Data Store authentication module and the password specified during configuration.

    The URL to access the Data Store authentication module is formatted as http://host:port/deployURI/UI/Login?module=DataStore. At this point, OpenSSO Enterprise is running against the existing Access Manager or Federation Manager schema (or DIT), which is known as coexistence mode.


    Tip –

    If upgrading from Legacy mode to Realm mode, a login at this point will fail. You should skip this step and login after completing Upgrading the Existing Access Manager or Federation Manager Schema.


Upgrading the Existing Access Manager or Federation Manager Schema

The ssoupgrade (or ssoupgrade.bat on Windows) script upgrades the Access Manager or Federation Manager schema (previously used to configure the deployed OpenSSO Enterprise WAR) to the OpenSSO Enterprise 8.0 schema.


Note –

Entering path names on Windows. When you run ssoupgrade.bat on Windows, replace each backslash (\) in path names to a forward slash (/). For example, you would enter C:/sun/opensso/config for C:\sun\opensso\config.


ProcedureTo Upgrade the Access Manager or Federation Manager Schema Using the ssoupgrade Script

Before You Begin

Before executing ssoupgrade, rename (by adding the .bak extension) and then copy the previous version's configuration files (AMConfig.properties and serverconfig.xml) to the /zip-root/opensso/upgrade/config directory.


# cp AMConfig.properties AMConfig.properties.bak
# mv AMConfig.properties.bak /zip-root/opensso/upgrade/config/
  1. Log on as super user (root).

  2. Change to the zip-root/opensso/upgrade/scripts directory.

  3. (Optional) Change the values for the following properties in the ssoupgrade script.

    If you don't run ssopre80upgrade these properties would not be updated to reflect the new configuration. This is most common in WAR based deployments for which you do not need to run ssopre80upgrade. Thus when upgrading WAR based deployments, ssoupgrade needs to be manually edited before executing it.

    • LIB_DIR=STAGING_DIR: path to the directory created in Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR. For example: LIB_DIR=/staging

    • CONFIG_DIR=OSSO_CONFIG_DIR: path to the configuration directory for the newly upgraded instance. For example: CONFIG_DIR=/amserver

    • UPGRADE_DIR=OSSO_UPGRADE_DIR: path to the upgrade directory in the exploded opensso.zip. For example: UPGRADE_DIR=/zip-root/opensso/upgrade


    Tip –

    The ssoupgrade script might need modification even if the ssopre80upgrade script was executed. Confirm that values for these properties have been swapped correctly before executing the script.


  4. Run the ssoupgrade script.

    • Solaris and Linux systems: ./ssoupgrade

    • Windows: ssoupgrade.bat

  5. When prompted, provide the following information.

    • Upgrade Base Directory: path to the directory created after exploding the opensso.zip. For example: /zip-root/opensso

    • OpenSSO Configuration Directory: path to the directory created after deploying the opensso.war. For example: /opensso

    • OpenSSO Staging Directory: path to the directory created in Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR. For example: /staging

    • Fully qualified host name of the machine on which the Directory Server is installed

    • Directory Server port number. For example: 389

    • Directory Manager DN. For example, cn=Directory Manager

    • Directory Manager password

    • OpenSSO Administrative User DN: the DN of amAdmin. By default, uid=amAdmin,ou=People,dc=sun,dc=com

    • OpenSSO Administrative User password (amAdmin password)

    • Enable Realms

      This prompt is displayed only if the existing instance is in Legacy mode or is an instance of Federation Manager. To migrate to Realm mode, enter y. Sun recommends that you migrate to Realm mode.

    After entering the script values, the process begins.

  6. Restart the Open SSO Enterprise web container.

Next Steps

Log in to the OpenSSO Enterprise Administration Console as amadmin using the Data Store authentication module and the password specified during configuration. The URL to access the Data Store authentication module is:

http://host:port/deployURI/UI/Login?module=DataStore