Use the following list of procedures to upgrade the previous release to OpenSSO Enterprise 8.0.
Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR
Modifying ssoUpgradeConfig.properties and AMConfig.properties.bak
Configuring Open SSO Enterprise 8.0 Against the Existing Access Manager or Federation Manager Schema
Upgrading the Existing Access Manager or Federation Manager Schema
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.
Log in to the host machine as super user (root).
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 |
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
Unzip opensso_enterprise_80.zip.
The upgrade scripts and related files are in the zip-root/opensso/upgrade directory.
Check the permissions on the ssopre80upgrade and ssoupgrade scripts. If these scripts do not have the execute permission, reset the permissions using chmod.
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.
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.
This procedure assumes you are still logged in to the host machine as super user.
Create a staging directory for the new WAR.
Do not create the staging directory in the tmp directory.
# mkdir /staging |
Extract the files from opensso.war into the staging directory.
# cd /staging # jar xvf /zip-root/opensso/deployable-war/opensso.war |
(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.
Be sure to remove the file you are replacing.
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 * |
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.
For an Access Manager 7.1 or a Federation Manager WAR deployment, undeploy the appropriate WAR (amserver.war for Access Manager or federation.war for Federation Manager) using the web container console or command line interface. For information, see the documentation for the web container.
For a Java Enterprise System installer deployment of Access Manager 7.1 or Access Manager 7 2005Q4, undeploy all web applications (amcommon, amconsole, ampassword and amserver) by executing the amconfig script with DEPLOY_LEVEL=26 as input in the amsamplesilent file. For more information, see Chapter 2, Running the Access Manager amconfig Script, in Sun Java System Access Manager 7.1 Postinstallation Guide.
After you undeploy the appropriate WAR file or undeploy all web applications, remove the classpath for the old Access Manager or Federation Manager libraries.
For example, if using Application Server 9.1, edit /opt/SUNWappserver/appserver/domains/domain1/config/domain.xml to remove all paths containing /opt/SUNWam/. Remove all entries containing SUNWam and SUNWma.
/opt/SUNWam/lib/xmlsec.jar
/etc/opt/SUNWam/config
/opt/SUNWam/lib
/opt/SUNWam/locale
/opt/SUNWam/lib/am_sdk.jar
/opt/SUNWam/lib/ldapjdk.jar
/opt/SUNWam/lib/am_services.jar
/opt/SUNWam/lib/am_sso_provider.jar
/opt/SUNWam/lib/swec.jar
/opt/SUNWam/lib/acmecrypt.jar
/opt/SUNWam/lib/iaik_ssl.jar
/opt/SUNWam/lib/iaik_jce_full.jar
/opt/SUNWam/lib/am_logging.jar
/opt/SUNWam/lib/jce1_2_1.jar
/opt/SUNWma/lib/wireless_rendering.jar
/opt/SUNWma/lib/wireless_rendering_util.jar
/opt/SUNWma/lib/mobile_services.jar
/opt/SUNWma/lib/ccpp-1_0.jar
/opt/SUNWma/lib/ccpp-ri-1_0.jar
/opt/SUNWma/lib/jena-1.4.0.jar
/opt/SUNWma/lib/rdffilter.jar
/opt/SUNWma/lib/locale
/opt/SUNWam/lib/mobile_identity.jar
When deployed on a Linux system, the entries are:
/etc/opt/sun/identity/config
/opt/sun/identity/lib
/opt/sun/identity/locale
/opt/sun/identity/lib/am_sdk.jar
/opt/sun/share/lib/ldapjdk.jar
/opt/sun/identity/lib/am_services.jar
/opt/sun/identity/lib/am_sso_provider.jar
/opt/sun/identity/lib/swec.jar
/opt/sun/identity/lib/acmecrypt.jar
/opt/sun/identity/lib/iaik_ssl.jar
/opt/sun/identity/lib/iaik_jce_full.jar
/opt/sun/identity/lib/am_logging.jar
/opt/sun/mobileaccess/share/lib/wireless_rendering.jar
/opt/sun/mobileaccess/share/lib/wireless_rendering_util.jar
/opt/sun/mobileaccess/share/lib/mobile_services.jar
/opt/sun/mobileaccess/share/lib/ccpp-1_0.jar
/opt/sun/mobileaccess/share/lib/ccpp-ri-1_0.jar
/opt/sun/mobileaccess/share/lib/jena-1.4.0.jar
/opt/sun/mobileaccess/share/lib/rdffilter.jar
/opt/sun/mobileaccess/share/lib/locale
/opt/sun/identity/lib/mobile_identity.jar
See OpenSSO issue 4032 for more information.
In this procedure, deploy the new OpenSSO Enterprise 8.0 WAR created in Creating a Staging Directory and OpenSSO Enterprise 8.0 Upgrade WAR.
This procedure assumes you are still logged in to the host machine as super user.
Be sure to follow the container-specific instructions in Chapter 2, Deploying the OpenSSO Enterprise Web Container, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide before deploying the WAR — in particular, read Adding Security Permissions For a Web Container in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
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.
Restart the OpenSSO Enterprise web container.
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:
Backing up existing Access Manager or Federation Manager files (such as logs and configuration files).
Removing the Access Manager 7.1 or Access Manager 7 2005Q4 packages (except on Windows systems).
Removing the Federation Manager 7.0 packages.
Removing the SAMLv2 Plug-in package.
Updating the /var/sadm/install/productregistry file to reflect the removal of the Java Enterprise System Access Manager packages.
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.
This procedure assumes you are still logged in to the host machine as super user.
Copy (and rename by adding the .bak extension) 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/ |
This step is needed for the next procedure, Modifying ssoUpgradeConfig.properties and AMConfig.properties.bak.
If upgrading a Linux-based installation, copy the ssoupgrade file to a new directory (for example /tmp/ssoupgrade). After executing ssopre80upgrade add values for the following attributes in the ssoupgrade file and return the modified script to the /zip-root/opensso/upgrade/scripts directory for execution in Upgrading the Existing Access Manager or Federation Manager Schema.
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
Change to the /zip-root/opensso/upgrade/scripts directory.
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 |
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.
If upgrading a Linux installation remember to edit ssoupgrade and return it to the /zip-root/opensso/upgrade/scripts directory.
In preparation for the final procedures in the upgrade process, modify two properties files.
ssoUpgradeConfig.properties is used by the ssoupgrade script.
AMConfig.properties.bak defines an encryption method not supported by OpenSSO Enterprise 8.0.
This procedure assumes you are still logged in to the host machine as super user.
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 |
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/ |
Change to the /zip-root/opensso/upgrade/config/ directory.
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
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.
Save ssoUpgradeConfig.properties.
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.
Change the value of com.iplanet.security.SecureRandomFactoryImpl from com.iplanet.am.util.JSSSecureRandomFactoryImpl to com.iplanet.am.util.SecureRandomFactoryImpl.
Change the value of com.iplanet.security.SSLSocketFactoryImpl from com.iplanet.services.ldap.JSSSocketFactory to netscape.ldap.factory.JSSESocketFactory.
Change the value of com.iplanet.security.encryptor from com.iplanet.services.util.JSSEncryption to com.iplanet.services.util.JCEEncryption.
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.
Save AMConfig.properties.bak.
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.
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.
This procedure assumes you have deployed the OpenSSO Enterprise WAR.
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.
On the Configuration Options page, click Create New Configuration.
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.
Click Next to continue.
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.
Click Next to continue.
On the Configuration Data Store Settings, do the following:
Check First Instance.
For Configuration Data Store, check Sun Java System Directory Server.
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
Click Next to continue.
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
Click Next to continue.
On the Site Configuration page, check No and click Next to continue.
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.
Click Next to continue.
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.
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.
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.
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.
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.
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/ |
Log on as super user (root).
Change to the zip-root/opensso/upgrade/scripts directory.
(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
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.
Run the ssoupgrade script.
Solaris and Linux systems: ./ssoupgrade
Windows: ssoupgrade.bat
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.
Restart the Open SSO Enterprise web container.
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