11.3 Upgrading Identity Applications

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

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

After the upgrade, the components are upgraded to the following versions:

Tomcat – 8.5.40
ActiveMQ – 5.15.9
Java 8 Update 222
One SSO Provider – 6.3.4
Self-Service Password Reset – 4.4.0.3
Identity Applications – 4.8
Identity Reporting – 6.5

This section provides information about the following topics:

11.3.1 Understanding the Upgrade Program

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

11.3.2 Prerequisite for Upgrade

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

For example, change

jdbc:postgresql://<postgres db>:5432/idmuserappdb?ssl=true

jdbc:postgresql://<postgres db>:5432/idmuserappdb?sslmode=require

11.3.3 System Requirements

The upgrade process creates a back-up of the current configuration for the installed components. Ensure that your server has sufficient space to store the back-up and additional free space available for upgrade.

11.3.4 Upgrading the PostgreSQL Database

IMPORTANT:The upgrade process may take time depending on the size of the database. Therefore, plan your upgrade accordingly.

Stop the PostgreSQL service that is running on your server.
Rename the postgres directory from C:\Netiq\idm\apps.

For example, rename postgres to postgresql_old.
Remove the old service by executing the following command:

sc delete <postgres service name>
Install PostgreSQL version supported on your operating system.

You must choose a location other than the current installation location of PostgreSQL.
1. Mount the Identity_Manager_4.8_Windows.iso image file and navigate to the \common\postgres_tomcat directory.
2. Run the TomcatPostgreSQL.exe file.
  
  Select only PostgreSQL option during installation.
NOTE:
- Do not provide any database details in PostgreSQL details page. Ensure that Create database login account and Create empty database are deselected.
- Ensure that you have the Administrator privileges for the old and new PostgreSQL installation directories.
Stop the newly installed PostgreSQL service. Go to Services, search for <PostgreSQL version number> service, and stop the service.

NOTE:Appropriate users can perform stop operations after providing valid authentication.
Change the permissions for the newly installed PostgreSQL directory by performing the following actions:

Create a postgres user:
1. Go to Control Panel > User Accounts > User Accounts > Manage Accounts.
2. Click Add a user account.
3. In the Add a User page, specify postgres as the user name and provide a password for the user.
Provide permissions to postgres user to the existing and newly installed PostgreSQL directories:
1. Right click the PostgreSQL directory and go to Properties > Security > Edit.
2. Select Full Control for the user to provide complete permissions.
3. Click Apply.
Access the PostgreSQL directory as postgres user.
1. Log in to the server as postgres user.
  
  Before logging in, make sure that postgres can connect to the Windows server by verifying if a remote connection is allowed for this user.
2. Delete the data directory from the new postgres install location. For example, C:\NetIQ\idm\apps\postgres\data
3. Open a command prompt and set PGPASSWORD by using the following command:
```
set PGPASSWORD=<your pg password>
```
4. Change to the newly installed PostgreSQL directory.
5. Execute initdb as postgres database user.
  
  initdb.exe -D <new_data_directory> -E UTF8 -U postgres
  
  For example,
  
  initdb.exe -D C:\NetIQ\idm\apps\postgres\data -E UTF8 -U postgres

Upgrade PostgreSQL from new PostgreSQL bin directory. Run the following command and click Enter.

NOTE:Ensure that you set the Method type from md5 to trust in the pg_hba.conf located at C:\NetIQ\idm\apps\postgres\data\ directory.

pg_upgrade.exe --old-datadir "C:\NetIQ\idm\apps1\postgres\data" --new-datadir "C:\NetIQ\idm\apps1\postgresql962\data" --old-bindir "C:\NetIQ\idm\apps1\postgres\bin" --new-bindir "C:\NetIQ\idm\apps1\postgresql962\bin"

After successful upgrade, replace pg_hba.conf and postgresql.conf files located in the new postgres data directory (C:\NetIQ\idm\apps\postgres\data) with the files from the old postgres directory.
Start the upgraded PostgreSQL database service.

Go to Services, search for <PostgreSQL version number> service, and start the service.

NOTE:Appropriate users can perform start operations after providing valid authentication.
Disable the old PostgreSQL service to ensure that the service does not automatically start.
(Optional) Delete the old data files from the bin directory of the newly installed PostgreSQL service.
1. Login as postgres user.
2. Navigate to the bin directory and run analyze_new_cluster.bat and delete_old_cluster.bat files.
  
  For example: C:\NetIQ\idm\apps\postgresql\bin
NOTE:You must run this step only if you want to delete the old data files.

11.3.5 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 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.

11.3.6 Upgrading Identity Applications

The following procedure describes how to upgrade the following components:

Identity Applications
OSP
Tomcat
PostgreSQL
SSPR (if installed on the same computer as Identity Applications)
ActiveMQ

Perform the following steps to upgrade Identity Applications:

Download the Identity_Manager_4.8_Windows.iso from the NetIQ Downloads website.
Mount the downloaded .iso.
Navigate to the <ISO installed location>\IdentityApplications folder and run the install.exe.
Select the language that you want to use for the installation and click OK.
In the Introduction page, click Next.
Read and accept the license agreement and then click Next.

The installed components and their versions are displayed.
Select Identity Applications and click Next.
Specify the configuration settings for Identity Applications. For more information, see Configuration Worksheet for Identity Applications.
NOTE:
- NetIQ recommends you to create the Workflow database using the Identity Manager installer, if you have installed the PostgreSQL database on the same server as Identity Applications.
- While Upgrading, you must manually specify the database JDBC JAR file. For example, if you are using PostgresQL database, you need to specify the location of the database JAR file which is located outside the tomcat\lib folder.
In the pre-upgrade summary page, review the settings and click Upgrade.

Depending on where you installed the components, the process creates the backup directory in that location and appends a time stamp (indicating the time of backup) to the backed-up directory.

For example,

Tomcat – C:\NetIQ\idm\apps\tomcat_backup_02262018_033634
OSP and SSPR - C:\NetIQ\idm\apps\osp_sspr_backup_02262018_033634
ActiveMQ - C:\NetIQ\idm\apps\activemq_backup_02262018_033634
User Application - C:\NetIQ\idm\apps\UserApplication_backup_02262018_033634
Identity Reporting - C:\NetIQ\idm\apps\IdentityReporting_backup_02262018_033634

11.3.7 Post-Upgrade Tasks

If you have Identity Applications and SSPR on different servers, then you must import the SSPR trusted certificate with the CN as Identity Applications to the cacerts of Identity Applications server.

You must also restore the customized settings for Tomcat, SSPR, OSP, or Identity Applications, manually.

Perform the post-upgrade steps for the required components:

Java

Verify the certificates in newly upgrade JRE location: jre\lib\security\cacerts with your older JRE location. Manually import the missed certificates into your cacerts.

Import java cacerts using keytool command:
```
keytool -import -trustcacerts -file Certificate_Path -alias ALIAS_NAME -keystore cacerts
```
NOTE:After upgrade, JRE is stored in the identity applications install location. For example: C:\NetIQ\idm\apps\jre
Restart the Identity Vault.
Verify JRE home location is tomcat\bin\setenv.bat.
Launch Configuration Update utility and verify the path of your cacerts.

Tomcat

(Conditional) To restore the customized files from the backup taken earlier by the upgrade process, perform the following tasks:
- Restore customized https certificates. To restore these certificates, copy the Java Secure Socket Extension (JSSE) contents from the backed up server.xml to the new server.xml file in the \tomcat\conf directory.
- Do not copy the configuration files from the backed-up Tomcat directory to the new Tomcat directory. Start with the default configuration of the new version and make changes as needed. For more information, see this Apache Website.
  
  Verify that new server.xml file has the following entries
```
<Connector port="8543" protocol="HTTP/1.1" 
       maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
       clientAuth="false" sslProtocol="TLS" 
       keystoreFile="path_to_keystore_file"
       keystorePass="keystore_password" />

```
  or
```
<Connector port="8543" protocol="org.apache.coyote.http11.Http11NioProtocol" 
       maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
       clientAuth="false" sslProtocol="TLS" 
       keystoreFile="path_to_keystore_file"
       keystorePass="keystore_password" />

```
  NOTE:On 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 C:\netiq\idm\apps\osp_backup_<date>.
- If you have customized keystore files, include the correct path in the new server.xml file.
- Import identity applications certificates into the Identity Vault at C:\NetIQ\eDirectory\jre\lib\security\cacerts.
  
  For example, you can use the following keytool command to import certificates into Identity Vault:
```
keytool -importkeystore -alias <User Application certificate alias> -srckeystore <backup cacert> -srcstorepass changeit -destkeystore C:\NetIQ\eDirectory\jre\lib\security\cacerts
```
(Conditional) Navigate to the User Application and restore the customized settings manually by reading the backed-up configuration.

Identity Applications

While upgrading Identity Applications from 4.6 SP4 to 4.8, you must ensure that Dcom.novell.afw.wf.engine-id=IDMProv parameter is present in the setenv file inside tomcat/bin folder. In case this parameter is missing after upgrading Identity Applications, you must manually add the parameter in the setenv file and restart the Tomcat server.

One SSO Provider

By default, the LogHost entry located in the logevent.conf file is set to localhost.

To modify the LogHost entry, manually restore the customized OSP configurations from the backup taken during the upgrade process.

Self-Service Password Reset

After upgrading SSPR, update SSO client parameter using Configuration Update Utility. For more information, see SSO Clients Parameters.

To update the SSPR configuration details, perform the following steps:

Log in to SSPR portal as an administrator.
Update the audit server details:
1. Navigate to YourID > Configuration Editor, specify the configuration password.
2. Select Settings > Auditing > Audit Forwarding > Syslog Audit Server Certificates.
3. Import these certificates from the sever and click Save.
Import the LocalDB into SSPR:
1. Navigate to YourID > Configuration Manager from the drop-down menu.
2. Click LocalDB.
3. Click Import (Upload) LocalDB Archive File.
(Conditional) To restrict configuration for SSPR:
1. Navigate to YourID > Configuration Manager from the list.
2. Click Restrict Configuration.
Configure administrator permissions for SSPR, see Post-Installation Steps.

To verify that the upgrade is successful, launch the upgraded components.

For example, launch the Identity Manager Dashboard, click About. Check whether the application displays the new version, such as 4.8.0.

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 these files to the new Tomcat folder from backed-up folder.