Upgrade from 4.2.0.3 to 4.2.0.4

This guide describes how to upgrade an existing RPM based OpenIAM deployment from v4.2.0.3 to v4.2.0.4 (RPM version). Please follow the steps in the order described below.

Download a new version of OpenIAM

To start, we must first download the RPM file for the latest version (4.2.0.4) from the OpenIAM website. Once you have the download URL, open a terminal window and download the file using the command shown below.

Note: You will need sudo permissions on your Linux host during the upgrade process.

wget <enter the download URL>

After the file has been downloaded, extract the contents of the RPM as shown below.

Extract an RPM Package Files

rpm2cpio <rpm_file_name> | cpio -idmv

As a result of this operation, you should see output similar to teh example below:

./etc/systemd/system/openiam-adapter@.service
./etc/systemd/system/openiam-auth.service
./etc/systemd/system/openiam-connector@.service
./etc/systemd/system/openiam-device.service
./etc/systemd/system/openiam-email.service
./etc/systemd/system/openiam-esb.service
./etc/systemd/system/openiam-groovy.service
./etc/systemd/system/openiam-idm.service
./etc/systemd/system/openiam-reconciliation.service
./etc/systemd/system/openiam-synchronization.service
./etc/systemd/system/openiam-ui.service
./etc/systemd/system/openiam-vault.service
./etc/systemd/system/openiam-workflow.service
./etc/systemd/system/redis-server.service
./tmp/openiam-tmproot/dependencies.tar.gz
./tmp/openiam-tmproot/openiam.tar.gz
./usr/bin/openiam-cli

Three new directories will be created

./etc
./tpm
./usr

Extract OpenIAM components

cd ./tmp/openiam-tmproot/
tar -zxvf openiam.tar.gz

You can find the files needed for the upgrade process in the directories shown below:

SQL scripts:

cd ./tmp/openiam-tmproot/openiam/conf/schema/

JAR files:

cd ./tmp/openiam-tmproot/openiam/services/bin/

WAR files:

cd ./tmp/openiam-tmproot/openiam/ui/webapps/

Groovy scripts:

cd ./tmp/openiam-tmproot/openiam/conf/iamscripts/

Upgrade OpenIAM

At a high level, we will perform the following steps:

  • Backup the current installation
  • Apply the new SQL scripts to upgrade the database schema
  • Update the .jar files
  • Update .war files under tomcat.

Backup OpenIAM

  1. Backup your dataabase by performing a DB duump. OpenIAM has two databases: openiam and activiti. Both must be backed up. If you are using MariaDB or MySQL, you can use the following approach:

Open a terminal window to the Linux host where your DB has been installed:

mysqldump -u [username] -p openiam > [backupfilename]-$(date +%F).sql
mysqldump -u [username] -p activiti > [backupfilename1]-$(date +%F).sql
  1. Backup all JAR files what located in /usr/local/openiam/services/bin/
  2. Backup all WAR files what located in /usr/local/openiam/ui/webapps/

Stop OpenIAM

openiam-cli stop

Apply new SQL scripts

Starting at 4.2.0, we are using flyway to manage database migrations.

Download, extract and install Flyway by adding to it PATH (requires sudo permissions):

wget -qO- https://repo1.maven.org/maven2/org/flywaydb/flyway-commandline/7.5.0/flyway-commandline-7.5.0-linux-x64.tar.gz | tar xvz && sudo ln -s `pwd`/flyway-7.5.0/flyway /usr/local/bin

Here is an example of how to apply new SQL scripts for MariaDB.

Go to the new SQL scripts folder (from steps above):

cd ./tmp/openiam-tmproot/openiam/conf/schema/

Run the database migration script as shown below. All of the of variables shown in the example below are required. The script will throw an error if any of them are not set, with a detailed error message.

NOTE:

  1. OPENIAM_CONF_PATH // replace <your_path> with a real path to this directory from steps above.
  2. Change DB credentials and host/port in case of non-default install.
export OPENIAM_CONF_PATH=<your_path>/tmp/openiam-tmproot/openiam && \
export OPENIAM_LOG_LEVEL=trace && \
export FLYWAY_DATABASE_TYPE=mysql && \
export FLYWAY_BASELINE_VERSION=2.3.0.0 && \
export FLYWAY_ACTIVITI_DATABASE_NAME=activiti && \
export FLYWAY_OPENIAM_DATABASE_NAME=openiam && \
export FLYWAY_ACTIVITI_PORT=3306 && \
export FLYWAY_ACTIVITI_HOST=localhost && \
export FLYWAY_OPENIAM_PORT=3306 && \
export FLYWAY_OPENIAM_HOST=localhost && \
export FLYWAY_ACTIVITI_USERNAME=idmuser && \
export FLYWAY_ACTIVITI_PASSWORD=idmuser && \
export FLYWAY_OPENIAM_USERNAME=idmuser && \
export FLYWAY_OPENIAM_PASSWORD=idmuser && \
./flyway.migrate.sh

The above script will generate output similar to the example below:

+ FLYWAY_COMMAND=migrate
+ OPENIAM_CONF_PATH=/root/update/tmp/openiam-tmproot/openiam
+ : 2.3.0.0
+ : activiti
+ : openiam
+ : 3306
+ : localhost
+ : 3306
+ : localhost
+ : mysql
+ : idmuser
+ : idmuser
+ : idmuser
+ : idmuser
+ '[' '' == true ']'
++ echo mysql
++ awk '{print tolower($0)}'
+ database_type=mysql
+ case $database_type in
+ '[' '!' -z trace ']'
+ '[' trace == debug ']'
+ '[' trace == trace ']'
+ echo 'Valid database type passed in. Not doing replacement: mysql'
Valid database type passed in. Not doing replacement: mysql
+ cd /root/update/tmp/openiam-tmproot/openiam/conf/schema/mysql
+ openiam_jdbc_url=
+ activiti_jdbc_url=
+ rds_jdbc_url=
+ case $database_type in
+ openiam_jdbc_url='jdbc:mysql://localhost:3306/openiam?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC'
+ activiti_jdbc_url='jdbc:mysql://localhost:3306/activiti?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC'
+ rds_jdbc_url='jdbc:mysql://localhost:3306/?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC'
+ '[' '!' -z '' ']'
+ '[' '' == true ']'
+ '[' -z '' ']'
+ flyway '-url=jdbc:mysql://localhost:3306/openiam?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC' -user=idmuser -password=idmuser -baselineVersion=2.3.0.0 baseline
Flyway Community Edition 7.5.0 by Redgate
ERROR: Skipping filesystem location:sql (not found).
Database: jdbc:mysql://localhost:3306/openiam (MySQL 5.5)
Schema history table `openiam`.`flyway_schema_history` already initialized with (2.3.0.0,<< Flyway Baseline >>). Skipping.
+ flyway '-url=jdbc:mysql://localhost:3306/openiam?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC' -user=idmuser -password=idmuser -locations=filesystem:/root/update/tmp/openiam-tmproot/openiam/conf/schema/mysql/openiam -outOfOrder=true -placeholderReplacement=false migrate
Flyway Community Edition 7.5.0 by Redgate
Database: jdbc:mysql://localhost:3306/openiam (MySQL 5.5)
Successfully validated 961 migrations (execution time 00:01.103s)
Current version of schema `openiam`: 4.2.0.3.001
WARNING: outOfOrder mode is active. Migration of schema `openiam` may not be reproducible.
Migrating schema `openiam` to version "4.2.0.4.001 - IAM-5216"
Migrating schema `openiam` to version "4.2.0.4.002 - IAM-5212"
Migrating schema `openiam` to version "4.2.0.4.003 - IAM-5218"
Migrating schema `openiam` to version "4.2.0.4.004 - IAM-5203"
Migrating schema `openiam` to version "4.2.0.4.005 - IAM-5197"
Migrating schema `openiam` to version "4.2.0.4.006 - IAM-5188"
Migrating schema `openiam` to version "4.2.0.4.007 - IAM-5227"
Migrating schema `openiam` to version "4.2.0.4.008 - fix policy name"
Migrating schema `openiam` to version "4.2.0.4.009 - fix cert report"
Migrating schema `openiam` to version "4.2.0.4.010 - IAM-5274"
Migrating schema `openiam` to version "4.2.0.4.011 - fix workday sync"
Migrating schema `openiam` to version "4.2.0.4.012 - IAM-5257"
Migrating schema `openiam` to version "4.2.0.4.013 - workday updates"
Migrating schema `openiam` to version "4.2.0.4.014 - IAM-5278"
Migrating schema `openiam` to version "4.2.0.4.015 - IAM-5305"
Migrating schema `openiam` to version "4.2.0.4.016 - IAM-5301"
Migrating schema `openiam` to version "4.2.0.4.017 - AC REMINDER"
Migrating schema `openiam` to version "4.2.0.4.018 - IAM-5317"
Migrating schema `openiam` to version "4.2.0.4.019 - IAM-5333"
Migrating schema `openiam` to version "4.2.0.4.020 - IAM-5317"
Migrating schema `openiam` to version "4.2.0.4.021 - IAM-5317"
Migrating schema `openiam` to version "4.2.0.4.022 - newAccessRight"
Migrating schema `openiam` to version "4.2.0.4.023 - fr localization"
Successfully applied 23 migrations to schema `openiam` (execution time 00:01.923s)
+ '[' -z '' ']'
+ flyway '-url=jdbc:mysql://localhost:3306/activiti?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC' -user=idmuser -password=idmuser -baselineVersion=2.3.0.0 baseline
Flyway Community Edition 7.5.0 by Redgate
ERROR: Skipping filesystem location:sql (not found).
Database: jdbc:mysql://localhost:3306/activiti (MySQL 5.5)
Schema history table `activiti`.`flyway_schema_history` already initialized with (2.3.0.0,<< Flyway Baseline >>). Skipping.
+ flyway '-url=jdbc:mysql://localhost:3306/activiti?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC' -user=idmuser -password=idmuser -locations=filesystem:/root/update/tmp/openiam-tmproot/openiam/conf/schema/mysql/activiti -outOfOrder=true -placeholderReplacement=false migrate
Flyway Community Edition 7.5.0 by Redgate
Database: jdbc:mysql://localhost:3306/activiti (MySQL 5.5)
Successfully validated 5 migrations (execution time 00:00.061s)
Current version of schema `activiti`: 4.0.0.0.212
WARNING: outOfOrder mode is active. Migration of schema `activiti` may not be reproducible.
Schema `activiti` is up to date. No migration necessary.

Replace JAR files

Copy new the JAR files into OpenIAM deployment directory

cd <your_path>/tmp/openiam-tmproot/openiam/services/bin/
cp * /usr/local/openiam/services/bin/

Set permissions on the JAR files:

chmod 644 /usr/local/openiam/services/bin/*

Set owner for the JAR files:

chown openiam:openiam /usr/local/openiam/services/bin/*

Replace WAR files

Clean up the following directories:

/usr/local/openiam/ui/temp/
/usr/local/openiam/ui/work/Catalina/
/usr/local/openiam/ui/webapps/

Copy new WAR files into OpenIAM Tomcat directory

cd <your_path>/tmp/openiam-tmproot/openiam/ui/webapps/
cp * /usr/local/openiam/ui/webapps/

Set permissions on the WAR files:

chmod 644 /usr/local/openiam/ui/webapps/*

Set owner for the WAR files:

chown openiam:openiam /usr/local/openiam/ui/webapps/*

Update existing groovy scripts

Some of the out of the box groovy scripts have been updated since the previous version (4.2.0.3). If you have customized them you will need to merge them with the new scripts, otherwise, you can just replace the old scripts with the new ones. The replacement scripts are listed below by topic.

cd <your_path>/tmp/openiam-tmproot/openiam/conf/iamscripts/

Managed System:

sync/mansys/csv/CSVManSysSampleTransformationScript.groovy -> /usr/local/openiam/conf/iamscripts/sync/mansys/csv/CSVManSysSampleTransformationScript.groovy

SalesForce.com:

sync/user/salesforce/SalesforceUserSyncAttributes.groovy -> /usr/local/openiam/conf/iamscripts/sync/user/salesforce/SalesforceUserSyncAttributes.groovy
sync/user/salesforce/TransformSalesforceRecord.groovy -> /usr/local/openiam/conf/iamscripts/sync/user/salesforce/TransformSalesforceRecord.groovy

Active Directory:

sync/group/ad/ADGroupSyncAttributes.groovy -> /usr/local/openiam/conf/iamscripts/sync/group/ad/ADGroupSyncAttributes.groovy
sync/user/ad/ADUserSyncAttributes.groovy -> /usr/local/openiam/conf/iamscripts/sync/user/ad/ADUserSyncAttributes.groovy
sync/user/ad/TransformActiveDirRecord.groovy -> /usr/local/openiam/conf/iamscripts/sync/user/ad/TransformActiveDirRecord.groovy
provision/ad/powershell/memberOf.groovy -> /usr/local/openiam/conf/iamscripts/provision/ad/powershell/memberOf.groovy

Access Manager:

AM/TestAbstractRedirectURLGroovyProcessor.groovy -> /usr/local/openiam/conf/iamscripts/AM/

Add new groovy scripts

As a result of new functionality added to this release, new groovy scripts have been introduced. You should copy these file to the iamscript directory as shown and then apply the correct permissions.

NOTE: All new folders and files should be owned by openiam user.

cd <your_path>/tmp/openiam-tmproot/openiam/conf/iamscripts/

Workday:

cp -R sync/user/workday /usr/local/openiam/conf/iamscripts/sync/user/
chown openiam:openiam /usr/local/openiam/conf/iamscripts/sync/user/workday/

SalesForce.com:

cp provision/salesforce/group/description.groovy /usr/local/openiam/conf/iamscripts/provision/salesforce/group/
cp provision/salesforce/group/groupPrincipal.groovy /usr/local/openiam/conf/iamscripts/provision/salesforce/group/
cp provision/salesforce/group/name.groovy /usr/local/openiam/conf/iamscripts/provision/salesforce/group/
cp sync/group/salesforce/SalesforceGroupSampleTransformationScript.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforceGroupSampleValidationScript.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforceGroupSyncAttributes.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforcePermissionSetSampleTransformationScript.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforcePermissionSetSampleValidationScript.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforcePermissionSetSyncAttributes.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforcePublicGroupSampleTransformationScript.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforcePublicGroupSampleValidationScript.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/group/salesforce/SalesforcePublicGroupSyncAttributes.groovy /usr/local/openiam/conf/sync/group/salesforce/
cp sync/role/salesforce/SalesforceRoleSampleTransformationScript.groovy /usr/local/openiam/conf/sync/role/salesforce/
cp sync/role/salesforce/SalesforceRoleSampleValidationScript.groovy /usr/local/openiam/conf/sync/role/salesforce/
cp sync/role/salesforce/SalesforceRoleSyncAttributes.groovy /usr/local/openiam/conf/sync/role/salesforce/

Active Directory:

cp sync/group/ad/powershell/ADGroupSampleTransformationScript.groovy /usr/local/openiam/conf/iamscripts/sync/group/ad/powershell/
cp sync/group/ad/powershell/ADGroupSampleValidationScript.groovy /usr/local/openiam/conf/iamscripts/sync/group/ad/powershell/
cp sync/group/ad/powershell/ADGroupSyncAttributes.groovy /usr/local/openiam/conf/iamscripts/sync/group/ad/powershell/

Boomi:

cp -R sync/group/boomi /usr/local/openiam/conf/iamscripts/sync/group/
cp -R sync/role/boomi /usr/local/openiam/conf/iamscripts/sync/role/
cp -R sync/user/boomi /usr/local/openiam/conf/iamscripts/sync/user/

LastPass:

cp -R sync/group/lastpass /usr/local/openiam/conf/iamscripts/sync/group/
cp -R sync/user/lastpass /usr/local/openiam/conf/iamscripts/sync/user/

Batch Task:

cp batch/sendReportAboutCampaignResults.groovy /usr/local/openiam/conf/iamscripts/batch/

Start OpenIAM

At this point the upgrade steps have been performed and you can re-start your OpenIAM installation using the command below.

openiam-cli start