Single node upgrade on Windows from version 4.x.x - CustomerID
Last reviewed: 2018-06-12
NOTE: These instructions require CustomerID 5 to be installed over an existing CustomerID 4 installation. If you want to build a separate environment for CustomerID 5 the data from LDAP in CID 4 environment has to be separately migrated into the new environment. Consult Ubisecure if you need advice on how to achieve this.
Issue all of the following commands using the Windows Command Prompt as an Administrator.
NOTE: If you are upgrading from a version lower than 4.6.x then you need to do the upgrade in two steps. First upgrade to version 4.6.x and then upgrade to the newest version. Direct upgrade to the newest version is only possible from version 4.6.x and later.
Stopping Ubisecure CustomerID services
Turn off Ubisecure CustomerID service and make sure no changes are made to the database during following steps.
net stop customerid
Set up the Derby-to-PostgreSQL migration tool
Extract the migration tool package cid-database-migration-package-x.x.x-windows.zip
to %PROGRAMFILES%\Ubisecure\migration-tool
.
Checking Java
See CustomerID Java Check On Windows.
Use the Migration-Tool to Export Data from Derby DB
Environment variables used by the migration-tool:
DERBY_HOME | The path where Derby DB is installed. |
DERBY_CONNECTION_URL | JDBC connection URL of the Derby DB. |
DERBY_PASSWORD | The password of Derby user. |
MIGRATION_JAR_FILE | The jar file containing migration implementation. |
Use the following lines as an example how to setup your own environment variables from the command line. Edit values to match your own environment.
SET DERBY_HOME="%PROGRAMFILES%\Ubisecure\customerid\db-derby" SET DERBY_CONNECTION_URL=jdbc:derby://localhost:1527/eidm2db;territory=fi_FI;collation=TERRITORY_BASED:PRIMARY SET "DERBY_PASSWORD=secretDerbyPassword" SET MIGRATION_JAR_FILE=cid-database-migration-x.x.x.jar
Run DerbyExport functionality of the migration-tool to export data from the existing Derby DB:
cd /D %PROGRAMFILES%\Ubisecure\migration-tool "%JRE_HOME%\bin\java" -Dderby.system.home=%DERBY_HOME% -cp .;./lib/derbyclient-10.11.1.1.jar;cid-database-migration-x.x.x.jar com.ubisecure.customerid.database.migration.DerbyExport
The DerbyExport functionality of the migration-tool will create .sql scripts into export-results subfolder that can be used to import existing data to PostgreSQL. It may take a while to perform this, depending on how much data is stored in Derby database. If the tool discovers pre-existing sql files in this folder with the same name as what it is going to write, it will interrupt its work and exit. So, if you have to fix something and re-run the command, you will have to ensure that the export-results folder is empty before you do so.
Backing up Ubisecure CustomerID
See instructions from Backup and restore - CustomerID.
Backing up Ubisecure Directory (ADAM or AD LDS)
See instructions from Backup and restore Ubisecure Directory - SSO.
Stopping and Removing Ubisecure CustomerID Services
Ubisecure CustomerID services can be stopped and removed by using the following commands:
net stop CustomerID cd /D "%PROGRAMFILES%\Ubisecure\customerid\application" config\tomcat\remove.cmd
Unpacking the New Distribution Package
See Distribution package unpacking on Windows - CustomerID.
Installing WildFly
If you have an existing WildFly installation, you need to uninstall it and install the one included in the distribution package.
For instructions installing (and uninstalling) WildFly see CustomerID WildFly Installation On Windows.
Extract the Deployment Template
Extract the cid-deployment-template-x.x.x.zip
to %PROGRAMFILES%\Ubisecure
.
Importing Configuration Settings from the Old Installation
In order to resume the service after the upgrade, it is necessary to copy some configuration settings from the previous installation. These settings are contained in the file customerid\application\win32.config
. In the new installation the win32.config
file is located further down the similar path in the subfolder config and must first be copied to the application folder.
The values must be copied carefully as the configuration options may have changed. You should copy only those values that have the same keys on both old and new win32.config
files.
NOTE: A large change was done between the 4.6.x and 5.0.x versions.
Refer to Edit the Setup template on Windows - CustomerID for more information about the new configuration options.
Running the Setup Script
NOTE: If you have made configuration changes to any of the win32.config
parameters after previously running the setup.cmd
, ensure that these changes are included in the new win32.config
file. For example, if you have changed the REST credentials in eidm2.properties
file, make sure the same values are now present in the win32.config
file.
cd /D "%PROGRAMFILES%\Ubisecure\customerid\application" setup.cmd
Configuring WildFly
See WildFly configuration on Windows - CustomerID.
Setting Up customerid.home System Property for WildFly
See Setting up customerid.home System Property for WildFly in CustomerID WildFly Configuration On Windows.
Setting Up Audit and Diagnostic Logging
See Setting up Audit and Diagnostic logging in CustomerID WildFly Configuration On Windows.
Setting Up a Mail Session
See Setting up a Mail Session in CustomerID WildFly Configuration On Windows.
Ubisecure CustomerID service can be restarted at this point by using the following commands:
net stop wildfly net start wildfly
Ubisecure SSO service can be started again at this point by using the following command:
net start UbiloginServer
Preparing a Database for Ubisecure CustomerID
See PostgreSQL preparation on Windows - CustomerID, but skip the Applying the CustomerID DDL to PostgreSQL chapter.
Create JDBC Data Source To WildFly
See JDBC data source creation on Windows - CustomerID.
Modify Directory Service for Ubisecure CustomerID Internal Database
You should already have a directory service for Ubisecure CustomerID internal database. However that service points to the old Derby database. It needs to be modified so that it points to the PostgreSQL database. See further instructions from SQL directory service creation on Windows - CustomerID concerning the correct values.
Use the Migration-Tool to Import the Data to PostgreSQL
You have to create an empty PostgreSQL database and the CustomerID database user before import.
Environment variables used by the import-tool:
PGHOME | The path where PostgreSQL is installed. |
PGUSER | The username which is used to access PostgreSQL database. |
PGPASSWORD | The password of PGUSER. |
PGCLIENTENCODING | The character encoding to use when accessing PostgreSQL DB. Typically UTF-8. |
PGPORT | This is the TCP port where PostgreSQL can be accessed. |
PGHOST | The DNS host name or IP address of PostgreSQL server. |
PG_CONNECTION_URL | JDBC connection URL of the PostgreSQL DB. |
MIGRATION_JAR_FILE | The jar file containing migration implementation. |
Use the following lines as an example how to setup your own environment variables from the command line. Edit values to match your environment.
SET PGHOME="%PROGRAMFILES%\PostgreSQL\9.4\bin\psql.exe" SET PGUSER=customerid_user SET PGPASSWORD=secretPostgresqlPassword SET PGCLIENTENCODING=UTF8 SET PGHOST=localhost SET PGPORT=5432 SET PG_CONNECTION_URL=jdbc:postgresql://%PGHOST%:%PGPORT%/customeriddb SET MIGRATION_JAR_FILE=cid-database-migration-x.x.x.jar
Create tables to the PostgreSQL DB:
cd %PROGRAMFILES%\Ubisecure\migration-tool %PGHOME% -d customeriddb -U %PGUSER% -f ./scripts/cid_create_postgresql.sql
Initialize the DB with internal data used by the CustomerID:
%PGHOME% -d customeriddb -U %PGUSER% -f ./scripts/cid_init.sql
Import previously exported Derby DB data to the PostgreSQL DB:
for %f in (.\export-results\*.sql) DO ( %PGHOME% -d customeriddb -U %PGUSER% -f %f )
Use the following command if you need to drop database tables before a new attempt (for example after correction of the data):
%PGHOME% -d customeriddb -U %PGUSER% -f ./scripts/cid_drop.sql
Validating the Data
When the data has been imported, run DataCleanup functionality of the migration-tool to make sure that the data has been imported properly.
"%JRE_HOME%\bin\java" -cp .;./lib/postgresql-9.4.1210.jar;cid-database-migration-x.x.x.jar com.ubisecure.customerid.database.migration.DataCleanup
This functionality will write errors in a log file called CLEANUPRESULTS.txt
. If there were errors in the data import it is possible to repair them manually using an SQL client to connect to PostgreSQL. How to repair depends on the nature of the error and in this case you may have to consult Ubisecure support.
When all errors have been fixed, you should run DataCleanup functionality of the migration-tool again and check the log file if the data is consistent.
It is known issue, that Organization EntityNames will get URL encoded, which causes some special letters and non-ASCII letters to malform. This is known to cause those organizations to be unaccessible. To fix this issue, change broken organizations Entity Name and Technical Name contain characters allowed in URL. (See RFC 3986: Unreserved characters)
Creating Constraints and Indexes
When the data has been validated, execute the following commands to create indexes and constraints to the tables.
%PGHOME% -d customeriddb -U %PGUSER% -f ./scripts/cid_create_postgresql_sso_views_and_functions.sql %PGHOME% -d customeriddb -U %PGUSER% -f ./scripts/cid_create_postgresql_constraints.sql
Restoring the Local Customizations
NOTE: Before replacing the custom folder, make sure there are no new additions in the configuration files. If there are, update your old customizations to support new configurations before replacing the files. The page Ubisecure CustomerID Configuration Changes In Versions lists all changes you need to do between different versions. Using that document as a guide delete all removed keys, add new ones if needed and replace all changed keys.
Copy the old configurations from the backup:
- customerid\application\custom folder
Restore the old custom folder with the following command:
xcopy /E %PROGRAMFILES%\Ubisecure\customerid-insert_old_version_number_here\customerid\application\custom "%PROGRAMFILES%\Ubisecure\customerid\application\custom" <Press a>
NOTE: Starting from Ubisecure CustomerID 5.0.x version back channel logout is no longer supported. If you have had that enabled you need to disable it before proceeding. Add the compatibility flag ( LiteNoBackChannel ) to your identity.properties
files and generate new metadata. Finally upload the new metadata to Ubisecure SSO Management. See instructions from SAML SP activation - SSO.
Deploying Ubisecure CustomerID
Ubisecure CustomerID uses WildFly as a J2EE Container. This chapter describes how to deploy the cid-ear-x.x.x.ear
and
cid-worker-
ear-x.x.x.ear
enterprise archives (EARs).
Deploy the Ubisecure CustomerID application to WildFly using the deploy-ear.cmd
script as shown below:
cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\" deploy-ear.cmd %USERPROFILE%\Desktop\customerid\cid-ear-x.x.x.ear deploy-ear.cmd %USERPROFILE%\Desktop\customerid\cid-worker-ear-x.x.x.ear
Successful deployment will show Deploying CustomerID EAR to Wildfly... Press any key to continue . . .
Ubisecure CustomerID SSO Adapter Upgrade
See SSO adapter upgrade on Windows - CustomerID.
UPGRADE IS NOW COMPLETE! Log in with your credentials.