Upgrade on Linux - SSO

Last reviewed: 2020-05-29

Make sure you have Java installed, JRE_HOME and JAVA_HOME set according to Installation requirements - SSO.

Stop the daemons that are running, ubisecure-accounting is a new service since 8.4:

/etc/init.d/ubilogin-server stop
/etc/init.d/ubilogin-directory stop
/etc/init.d/ubisecure-accounting stop

Remove SSO and Accounting Service daemon configurations

cd /usr/local/ubisecure/ubilogin-sso/ubilogin
./config/tomcat/remove.sh

Take a backup from Ubisecure Directory of the old SSO

/usr/local/ubisecure/ubilogin-sso/openldap/libexec/slapd -T cat -f "/usr/local/ubisecure/ubilogin-sso/openldap/etc/openldap/slapd.conf" -l /home/ubilogin/database.ldif

Backup the existing Ubisecure SSO installation and OpenLDAP:
```
cd /usr/local/ubisecure
mv ubilogin-sso ubilogin-sso-old
```
Extract the archive sso-x.x.x-unix.tar.gz to directory /usr/local/ubisecure use the full path to the archive you have downloaded
```
tar -xzvf sso-x.x.x-unix.tar.gz
```

Copy unix.config file from the older version

cp /usr/local/ubisecure/ubilogin-sso-old/ubilogin/unix.config /usr/local/ubisecure/ubilogin-sso/ubilogin/unix.config

Add the following lines if they do not exist in the file /usr/local/ubisecure/ubilogin-sso/ubilogin/unix.config

tomcat.instancename = ubilogin-server
openldap.instancename = ubilogin-directory
openldap.root= uid=System,ou=System,@suffix@

When upgrading from version 8.3.x or older, add the Accounting Service related settings if they do not exist in the file /usr/local/ubisecure/ubilogin-sso/ubilogin/unix.config. Modify the settings according to these guidelines.

# Accounting configuration
accounting.url = https://localhost:8442
accounting.proxy.local.url = @accounting.url@
accounting.instancename = ubisecure-accounting
accounting.datasource.url = jdbc:postgresql://localhost:5432/accountingdb
accounting.datasource.username = 
accounting.datasource.password = 
accounting.secret-key-location-uri = file:///${user.dir}/config/accounting-service.secret
accounting.actuator.username = accounting_admin
accounting.actuator.password = 
accounting.jms.broker.port = 36161
accounting.jms.broker.socket-timeout-ms = 10

When upgrading from version 8.4 or later, copy Accounting Service logs from the older version:

mkdir /usr/local/ubisecure/ubilogin-sso/accounting/logs
cp /usr/local/ubisecure/ubilogin-sso-old/accounting/logs/* /usr/local/ubisecure/ubilogin-sso/accounting/logs

When upgrading from version 8.4 or later, depending of the location of your Accounting Service secret key you may need to copy the file from the older version. NOTE: The secret key must be the same during the entire reporting period which is a month, see Accounting Service security. Example (use the path you have set in the configuration):
```
mkdir /usr/local/ubisecure/ubilogin-sso/accounting/config
cp /usr/local/ubisecure/ubilogin-sso-old/accounting/config/accounting-service.secret /usr/local/ubisecure/ubilogin-sso/accounting/config
```

Copy the following files and directories (recursively) from the previous installation to the matching ubilogin-sso directory. Note that both Tomcat and Ubisecure SSO logs are retained.

/usr/local/ubisecure/ubilogin-sso-old/ubilogin/custom/*
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/config.index
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/methods/*
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/logs/*
/usr/local/ubisecure/ubilogin-sso-old/tomcat/logs/*
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/uas/WEB-INF/uas.properties
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/cdc/WEB-INF/config.properties
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/ROOT/robots.txt

Check Password application
NOTE:
Password: Check from the current installation if Password application is enabled. To check, examine the file
/usr/local/ubisecure/ubilogin-sso-old/tomcat/conf/server.xml
If the path /password is not commented out, Password application has been enabled in the previous installation.
Skip this step if the Password application is not enabled.
Copy the following files and directories from the previous installation to the matching ubilogin-sso directory:
```
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/password/WEB-INF/password.properties
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/password/WEB-INF/saml2
```
Edit /usr/local/ubisecure/ubilogin-sso/ubilogin/config/tomcat/conf/server.xml and uncomment following line:
<Context path="/password" docBase="${catalina.base}/webapps/password"/>
Also check /usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/password/WEB-INF/web.xml for mail.smtp.host and mail.smtp.from configuration and copy those to new web.xml (/usr/local/ubisecure/ubilogin-sso/ubilogin/webapps/password/WEB-INF/web.xml)
Check Common Domain Cookie Discovery
NOTE:
Common Domain Cookie Discovery
Check from the previous installation if Common Domain Cookie Discovery has been enabled.
To check, examine the file
/usr/local/Ubisecure/ubilogin-sso-old/tomcat/conf/server.xml
If the path /cdc is not commented out, Common Domain Cookie Discovery has been enabled in the previous installation.
If Common Domain Cookie Discovery has been installed prior to the upgrade, re-enable the settings after upgrade according to the Common Domain Cookie Discovery document.

Run the setup script:

cd /usr/local/ubisecure/ubilogin-sso/ubilogin
./setup.sh

When upgrading from version 8.3.x or older, install and prepare PostgreSQL. Since SSO version 8.4 with Accounting Service feature access to PostgreSQL database is required for the service to run. If you have already installed Ubisecure CustomerID you can use the existing PostgreSQL installation but you need to create a specific database for this purpose. The necessary tables are automatically created during the initial startup of the Accounting Service.
See PostgreSQL preparation on Linux for more information and steps to accomplish.
If you have a clustered environment check that you have configured OpenLDAP replication in the following files as currently advised: /usr/local/ubisecure/ubilogin-sso-old/ubilogin/ldap/openldap/ldap_server_list.conf and /usr/local/ubisecure/ubilogin-sso-old/ubilogin/ldap/openldap/ldap_peer.conf, see OpenLDAP clustering: Install node 1. If not add the settings into these files before continuing with the OpenLDAP installation. If the settings are present copy the following files from the previous installation to the matching ubilogin-sso directory
```
/usr/local/ubisecure/ubilogin-sso-old/ubilogin/ldap/openldap/ldap*.conf
```
If you have a clustered environment repeat the step advised in OpenLDAP clustering: Install node 1 and modify /usr/local/ubisecure/ubilogin-sso/ubilogin/config/settings.sh. Replace <node1-hostname> with your hostname.
```
ADD the following new line below the line reading "esac"
LDAP_LISTEN_URLS="ldap://<node1-hostname>:389 $LDAP_LISTEN_URLS"
```

Remove old OpenLDAP installation and Restore the Ubisecure Directory from the backup

./ldap/openldap/remove.sh
./ldap/openldap/install.sh --no-initdata
su ubilogin -c "/usr/local/ubisecure/ubilogin-sso/openldap/libexec/slapd -T add -f "/usr/local/ubisecure/ubilogin-sso/openldap/etc/openldap/slapd.conf" -l /home/ubilogin/database.ldif"

Start the ubilogin-directory daemon:
```
/etc/init.d/ubilogin-directory start
```
Important: Add new entries and update LDAP secrets into OpenLDAP, ignore warnings about e.g. existing entries
```
./ldap/openldap/import-changes.sh
```
When upgrading from version 8.3.x or older, configure Accounting Service
Before continuing with the installation which will start the Accounting Service you need to enter and save the secret key contents in the location referred by accounting.secret-key-location in unix.config. See Accounting Service security about the usage of the key for pseudonymisation. The page contains a suggested script to create a secure enough secret in the default location.
You may also customise other Accounting Service configuration settings for your needs, which is recommended. See Accounting Service additional configuration about the properties to set.

When customising edit this file which is copied from the installation package by the setup script: /usr/local/ubisecure/ubilogin-sso/ubilogin/custom/accounting/config/application.yaml
Reinstall SSO Tomcat and Accounting Service configuration and start the services. Since version 8.4 remove should be done before installation directory is replaced (see step 3.). About Accounting Service (ubisecure-accounting) start see also Linux single node installation.
```
cd /usr/local/ubisecure/ubilogin-sso/ubilogin
./config/tomcat/install.sh 
/etc/init.d/ubisecure-accounting start
/etc/init.d/ubilogin-server start
```
The system upgrade is complete. See also Single node installation finalization.

NOTE: If you have Ubisecure CustomerID installed, you need to copy the Authorizer files at this point. For instructions, please see Related tasks when upgrading SSO in Linux - CustomerID.
Remove the backed up ubilogin-sso-old directory, or rename and retain it as desired.
Clear your web browser’s cache before accessing the user interface.