10.7 Upgrading Identity Applications

This section provides information about upgrading Identity Applications and supporting software, which includes updating the following components:

Identity Manager User Application
Self-Service Password Reset (SSPR)
Tomcat, JDK, and ActiveMQ
PostgreSQL database
One SSO Provider (OSP)

IMPORTANT:Identity Manager 4.8 requires Identity Applications and OSP installed on the same computer. When upgrading to this version, use OSP that is installed when Identity Applications are upgraded and then copy the OSP settings from your existing OSP server to the new OSP server. For more information, see Post-Upgrade Tasks for Identity Applications Components.

This section provides information about the following topics:

10.7.1 Considerations for Upgrade

The Identity Applications upgrade process can vary based on how you want to upgrade the identity applications components. The following considerations apply before you upgrade Identity Applications:

Before you begin with the upgrade process for Identity Applications, you must create the igaworkflowdb if you are using Oracle or MS SQL databases and assign all the privileges to the idmadmin user to own the databases.
If your Identity Applications and SSPR are installed on different servers, you can choose to upgrade SSPR separately.
During upgrade, ensure to verify and then modify the database name and other default values, as appropriate.

Identity Manager supports a local installation of OSP on the Identity Applications server. The upgrade program does not support a standalone upgrade of OSP to this version and installs a new copy of OSP while upgrading Identity Applications. To restore your existing OSP settings to the newly installed OSP, see One SSO Provider in the Post-Upgrade Tasks for Identity Applications Components.

Table 10-1 Upgrade Process for Identity Applications

Identity Applications Deployment	Upgrade Process
Identity Applications, SSPR, and OSP are installed on the same server	To upgrade all the components, follow the steps from Upgrading Identity Applications.
Identity Applications and OSP are installed on the same server. SSPR is installed on a different server.	To upgrade Identity Applications and OSP, follow the steps from Upgrading Identity Applications. To upgrade SSPR on a different server, follow the steps from Upgrading SSPR.
Identity Applications are installed on a different server than SSPR and OSP. In this case, SSPR can be installed on the Identity Applications server or a separate server. However, OSP must be installed on the Identity Applications server.	To upgrade Identity Applications and OSP, follow the steps from Upgrading Identity Applications. To upgrade SSPR on a different server, follow the steps from Upgrading SSPR. Launch configuration update utility and provide details of the new server where OSP is installed. In this case, the new server is the server where Identity Applications is installed. For more information, see SSO Clients Parameters.

10.7.2 System Requirements

The upgrade process creates a backup of the current configuration for the installed components. Ensure that your server has sufficient space to store the backup and additional free space available for upgrade. For more information, see the NetIQ Identity Manager Technical Information website.

10.7.3 Understanding the Upgrade Program

The upgrade process reads the configuration values from the existing components. This information includes ism-configuration.properties, server.xml, SSPRConfiguration and other configuration files. When you use these configuration files, the upgrade process internally invokes the upgrade program for the specified components. The upgrade program also creates a backup of the current installation.

10.7.4 Upgrading PostgreSQL

Perform the following steps to upgrade PostgreSQL:

Download and extract the Identity_Manager_4.8_Linux.iso from the NetIQ Downloads website.
Navigate to the /common/scripts directory.
Run the following command:

./pg-upgrade.sh
Specify the following details to complete the installation:

Existing Postgres install location: Specify the location where PostgreSQL is installed. The default location is /opt/netiq/idm/postgres.

NOTE:Ensure that the postgres user has appropriate permissions to the /opt/netiq/idm/postgres directory.

Existing Postgres Data Directory: Specify the location of the PostgreSQL data directory. The default location is /opt/netiq/idm/postgres/data.

Existing Postgres Database Password: Specify the PostgreSQL password.

New Postgres Data Directory: Specify the new PostgreSQL data directory. For example, /opt/netiq/idm/postgres_new/data.

10.7.5 Upgrading the Identity Applications Components

Upgrading the Driver Packages for Identity Applications

You must stop Tomcat and update the packages for the User Application Driver and Role and Resource Service drivers to the latest version. For information about upgrading packages to the latest version, see Upgrading Installed Packages of the NetIQ Designer for Identity Manager Administration Guide.

After upgrading the User Application driver packages, you must manually add the workflow templates package:

In Designer, navigate to the User Application driver > Properties.
Click Packages, then click the .
Select the Show only applicable package versions check box.
Select the Create Workflow Templates.
Click OK and then click Finish to complete the installation.
Deploy the User Application driver.

IMPORTANT:If any Email notifications template is installed or upgraded as part of User Application Driver upgrade, then you need to deploy Default Notification Collection object.

Upgrading Identity Applications

The following procedure describes how to upgrade Identity Applications.

Download the Identity_Manager_4.8_Linux.iso from the NetIQ Downloads website.
Mount the downloaded .iso.
Run the following command:

./install.sh
Read through the license agreement.
Enter y to accept the license agreement.
Specify whether you want to upgrade the Identity Applications. The available options are y and n.
If you proceed with the upgrade, specify the following details:
OSP Installation Folder for Backup

This applies only when you have OSP and Identity Applications on the same server.

Specify the OSP backup folder to store the OSP backup data.

SSPR Installation Folder

This applies only when you have SSPR and Identity Applications on the same server.

Specify the SSPR installation folder.

SSPR not found on system. Do you want to install & configure it?
This applies only when you have Identity Applications and SSPR on different servers.

If you select y, then SSPR will be installed on the same server as Identity Applications. You need to copy the existing customization settings to the new SSPR installed server.
SSPR Configuration Password: Specify the SSPR configuration password.

One SSO Server DNS/IP Address: Specify the IP address of the server where OSP is installed.

One SSO Server SSL Port: Specify the OSP SSL port.
If you select n, then SSPR will not be installed and Identity Applications will be upgraded.
User Application Installation Folder

Specify the User Application installation folder.

Identity Applications One SSO Service Password

Specify the One SSO password. The specified password will update the Client Secrets for all the clients that you have configured in the Configuration Update utility. If required, you can reset the password for the respective clients from the Configuration Update utility. For more information, see SSO Clients Parameters.

Identity Applications Database JDBC jar file

Specify the database JAR file. For example, if you are using PostgresQL database and it is installed on the same server, the default location of the existing database jar file is /opt/netiq/idm/postgres/postgresql-9.4.1212.jar.

Create Schema for Identity Applications

Specify when you want to create database schema. The available options are Now, Startup, and File. The default option is Now.

NOTE:You must create igaworkflowdb if you are using msSQL or Oracle assigning the idmadmin user all the privileges for this database.

Identity Applications Database User Password

Specify the database user password.

Identity Applications Database Administrator Password

Specify the database administrator password.
Start Tomcat. If you opt to create the database schema immediately, select Now.

systemctl start netiq-tomcat.service

(Optional) During upgrade, in case you select the Startup or Write to file option for creating the database schema, you must perform the required steps for migration of data to the workflow database. The following sections provide details on the data migration when you are using the Startup or Write to file options.
Restart the NGINX service.

systemctl restart netiq-nginx.service

Database Startup

IMPORTANT:Follow the procedure in this section to migrate data to the workflow database using the workflow migration utility provided with the Identity Manager 4.8 Linux and Windows ISO files. However, an updated workflow migration tool is now available in the Identity Applications Tools Patch 1 package (1.0.0.0100). This patch adds a new workflow migration command utility with new options to assist you in faster migration. It also addresses a key issue with the database migration failure when migrating large databases. You can download this patch from the Software License and Download portal. We recommend that you use the latest workflow migration utility for a smooth database migration. For more information, see NetIQ Identity Manager 4.8 Identity Applications Tools Patch 1 Release Notes.

Perform the following steps to migrate data while using the Startup option:

Copy the WorkflowMigration.zip file from the <location where you have mounted the ISO>/user_application/IDM_Tools/ directory to /home directory and unzip the file.
Copy the jdbc.jar (for example, sqljdbc42.jar) file to /home/WorkflowMigration/WEB-INF/lib/ directory and rename the file as jdbcDriver.jar.
Stop the Roles and Resource Service driver.
Start Tomcat.

Run the following commands to export the data:

NOTE:Ensure that the database user has all the privileges to modify the database.

[postgres]  /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -e test.zip -surl jdbc:postgresql://ip:port/idmuserappdb -suser idmadmin -spwd ***** -sdb postgres

[oracle] /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -e test.zip -surl jdbc:oracle:thin:@IP:1521:idmdb -suser idmadmin -spwd ***** -sdb oracle

[mssql] /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -e test.zip -surl "jdbc:sqlserver://IP:1433;DatabaseName=idmuserappdb" -suser idmadmin -spwd ***** -sdb mssql

Run the following commands to import the data:

[postgres]  /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -i test.zip -durl jdbc:postgresql://ip:port/igaworkflowdb -duser idmadmin -dpwd ***** -ddb postgres

[oracle]   /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -i test.zip -durl jdbc:oracle:thin:@IP:1521:igaworkflowdb -duser idmadmin -dpwd ***** -ddb oracle

[mssql] /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -i test.zip -durl "jdbc:sqlserver://IP:1433;DatabaseName=igaworkflowdb" -duser idmadmin -dpwd ***** -ddb mssql

Start the Roles and Resource Services driver.

Write to SQL File

Perform the following steps to migrate data while using the Write to SQL option:

Copy the WorkflowMigration.zip file from the <location where you have mounted the ISO>/user_application/IDM_Tools/ directory to /home directory and unzip the file.
Copy the jdbc.jar (for example, sqljdbc42.jar) file to /home/WorkflowMigration/WEB-INF/lib/ directory and rename the file as jdbcDriver.jar.
Execute the ua_databaseschema.sql and wfe_databaseschema.sql scripts using an admin tool such as pgAdmin and verify whether the schema is created properly.

NOTE:While executing the ua_databaseschema.sql and wfe_databaseschema.sql using pgAdmin tool, ensure to comment out the first line in both the SQL files. For example, Starting Liquibase at Fri, 11 Oct 2019 15:59:26 IST (version 3.7.0 built at 2019-07-16 02:32:57) line should be commented out before executing the SQL files.

Run the following commands to export the data:

NOTE:Ensure that the database user has all the privileges to modify the database.

[postgres]  /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -e test.zip -surl jdbc:postgresql://ip:port/idmuserappdb -suser idmadmin -spwd ***** -sdb postgres

[oracle] /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -e test.zip -surl jdbc:oracle:thin:@IP:1521:idmdb -suser idmadmin -spwd ***** -sdb oracle

[mssql] /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -e test.zip -surl "jdbc:sqlserver://IP:1433;DatabaseName=idmuserappdb" -suser idmadmin -spwd ***** -sdb mssql

Run the following commands to import the data:

[postgres]  /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -i test.zip -durl jdbc:postgresql://ip:port/igaworkflowdb -duser idmadmin -dpwd ***** -ddb postgres

[oracle]   /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -i test.zip -durl jdbc:oracle:thin:@IP:1521:igaworkflowdb -duser idmadmin -dpwd ***** -ddb oracle

[mssql] /opt/netiq/common/jre/bin/java -jar Workflow-Migration.jar -i test.zip -durl "jdbc:sqlserver://IP:1433;DatabaseName=igaworkflowdb" -duser idmadmin -dpwd ***** -ddb mssql

Start Tomcat.

Upgrading SSPR

Use this method when SSPR is installed on a different server than the identity applications server in an Advanced Edition.

This is the only method to upgrade SSPR in a Standard Edition.

To upgrade SSPR:

Download the Identity_Manager_4.8_Linux.iso from the NetIQ Downloads website.
Mount the downloaded .iso.
From the root directory of the .iso file, navigate to the sspr directory.
Run the following command:

./install.sh
Read through the license agreement.
Enter y to accept the license agreement.
Specify y to upgrade SSPR.
Specify Identity Vault Administrator Password and complete the upgrade.

10.7.6 Post-Upgrade Tasks for Identity Applications Components

Perform the following tasks before starting to use Identity Applications:

Manually delete the previous version of Tomcat and ActiveMQ services. For example, run the following commands:

/etc/init.d/idmapps_tomcat_init

/etc/init.d/idmapps_activemq_init
You must manually restore the customized settings for Tomcat, SSPR, OSP, and Kerberos.
A certificate with CN as Identity Applications should be present in the keystore (idm.jks) of the Identity Applications server. As part of enhanced Java security, now Identity Applications requires trusted certificate to communicate with OSP.
Use the existing Identity Applications keystore file to import the signed certificate to idm.jks. For example:

./keytool -import -alias mycerts -keystore /opt/netiq/idm/apps/tomcat/conf/idm.jks -file /opt/certs/chap8.der

NOTE:This step is required for upgrading 4.6.x to 4.8.

If you are upgrading Identity Applications in a clustered environment, then you must perform the following steps after upgrading Identity Applications:

Navigate to the /opt/netiq/idm/apps/tomcat/conf directory and add the following line in the Context tag of the context.xml file:

<Manager notifyListenersOnReplication="true" expireSessionsOnShutdown="false" className="org.apache.catalina.ha.session.DeltaManager"/>

Navigate to the /opt/netiq/idm/apps/tomcat/conf directory and add the following lines in the Cluster tag of the server.xml file:

<Channel className="org.apache.catalina.tribes.group.GroupChannel">
            <Membership className="org.apache.catalina.tribes.membership.McastService"
                        address="228.0.0.4"
                        port="45564"
                        frequency="500"
                        dropTime="3000"/>
            <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
                      address="auto"
                      port="5000"
                      selectorTimeout="100"
                      maxThreads="6"/>

            <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
              <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
            </Sender>
            <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
            <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
            <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/>
          </Channel>

          <Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
                 filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/>

          <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
                    tempDir="/tmp/war-temp/"
                    deployDir="/tmp/war-deploy/"
                    watchDir="/tmp/war-listen/"
                    watchEnabled="false"/>

          <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>

If your database is configured over SSL, replace ssl=true with sslmode=require in the server.xml file from PATH located at /opt/netiq/idm/apps/tomcat/conf/.

For example, change
```
jdbc:postgresql://<postgres db>:5432/idmuserappdb?ssl=true
```
to
```
jdbc:postgresql://<postgres db>:5432/idmuserappdb?sslmode=require
```

Tomcat

In a cluster environment, manually uncomment the Cluster tag in server.xml and copy osp.jks on to all nodes from the first node located at /opt/netiq/idm/apps/osp_backup_<date>.
If you have customized keystore files, include the correct path in the new server.xml file.

SSPR

If Identity Applications and SSPR are deployed on different servers, and you choose to restore the existing SSPR customized settings to the new server where SSPR is installed, ensure that you modify the SSPR settings on the new SSPR server by using the ConfigUpdate utility. For more information, see SSO Clients Parameters.

One SSO Provider

If Identity Applications and OSP are deployed on different servers in your pre-upgrade setup, copy the existing OSP settings to the new server where OSP is installed (Identity Applications server), then run the merge_jars method from the installation kit on this server to restore your settings.

Stop Tomcat on the server where you upgraded Identity Applications. (OSP is installed with Identity Applications upgrade)
Restore the customization.
1. Navigate to the OSP installation directory in your existing OSP server and locate the osp-custom-resource.jar file.
  
  For example, /opt/netiq/backup_idm/osp/osp-extras/l10n-resources/osp-custom-resource.jar.
2. Copy the osp-custom-resource.jar file to a location on the server where you upgraded Identity Applications.
3. Navigate to <location where you have mounted the Identity_Manager_4.8_Linux.iso>/osp/scripts/merge_cust_loc.sh.
  
  This script contains merge_jars method that takes care of merging the existing customization with the newly installed OSP.
4. Open a command prompt and run the following command:
```
merge_jars ${IDM_BACKUP_FOLDER in the remote OSP server}/tomcat/lib/osp-custom-resource.jar ${IDM 4.8_OSP_INSTALLED_HOME}/osp-extras/l10n-resources/osp-custom-resource.jar)
```
  For example:
```
merge_jars /opt/netiq/backup_idm/osp/osp-extras/l10n-resources/osp-custom-resource.jar /opt/netiq/idm/apps/osp/osp-extras/l10n-resources/osp-custom-resource.jar
```
  where backup_idm directory contains OSP settings in the existing OSP server.
Start Tomcat on the new server where OSP is installed.

For updating other settings, see SSO Clients Parameters.

Kerberos

The upgrade utility creates a new Tomcat folder on your computer. If any of the Kerberos files such as keytab and Kerberos_login.config resided in the old Tomcat folder, copy those files to the new Tomcat folder from the backed-up folder.

10.7.7 Verifying the Version Numbers After Upgrade

After upgrading to Identity Manager 4.8, verify that the components are upgraded to the following versions:

Tomcat – 9.0.22
ActiveMQ – 5.15.9
Java – 1.8.0_222
One SSO Provider – 6.3.6
Self-Service Password Reset – 4.4.0.3