/
Upgrade on Linux - SSO

Upgrade on Linux - SSO

2022-06-15

These are the upgrade instructions to the latest release: SSO 9.0. If you are upgrading to a SSO 8.x.x version, please check the upgrade instructions for that particular release.

In the SSO version 9.0 there are of major changes that need to be taken into account in the upgrade process:

  • Java 8 is replaced with Java 11

    • step 1 for the previous version (Java 8)

    • steps 6 and 27 for the new version (Java 11)

  • Services are managed with systemd and no more with init.d

    • step 2 for the previous version (init.d)

    • step 22 and onward for the new version (systemd)

  • OpenLDAP version upgraded to 2.5.6

    • Backend has changed to use MDB instead of previous BDB which sets higher requirements on memory and disk storage

    • See System Recommendations and Supported Platforms for suggested memory and disk storage in regards to identities and sessions in the system

    • Two new parameters have been introduces in unix.config file that needs to be added manually after copying the old unix.config

      • openldap.maxsize = 10737418240

      • openldap.idlexp = 20

 

  1. For the version to be removed, make sure you still have Java 8 installed and JRE_HOME and JAVA_HOME set

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

  3. Remove SSO and Accounting Service daemon configurations

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

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

  5. Backup the existing Ubisecure SSO installation and OpenLDAP:

    cd /usr/local/ubisecure mv ubilogin-sso ubilogin-sso-old

  6. Replace Java installation with Java 11

    1. If you have a CustomerID installation running on the same SSO server node, stop the WildFly service at this point:

      systemctl stop wildfly

    2. Remove Java 8 installation

    3. Install Java 11 and set JAVA_HOME according to Installation requirements - SSO

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

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

  9. Add the following lines if they do not exist in the file /usr/local/ubisecure/ubilogin-sso/ubilogin/unix.config, see further instructions for openldap specific values from here The Macro language - SSO

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

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

  11. When upgrading from version 8.4 or newer, 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):

    cd /usr/local/ubisecure/ubilogin-sso-old cp --parents accounting/config/accounting-service.secret ../ubilogin-sso

  12. Copy the following files and directories (recursively) from the previous installation to the matching ubilogin-sso directory. Note that Tomcat, Ubisecure SSO, and Accounting Service logs are retained. Let overwrite existing files or add flags -fn for the cp commands.

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

  13. Check Password application

    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)

  14. Check Common Domain Cookie Discovery

  15. Run the setup script:

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

  16. After the setup script, you may still need to check some files from the backup folder if you have customised them. Compare the files under /usr/local/ubisecure/ubilogin-sso-old with the ones under /usr/local/ubisecure/ubilogin-sso and copy the necessary changes from:

    /usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/uas/WEB-INF/uas.properties /usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/totp/WEB-INF/application.yaml

  17. When upgrading from version 8.3.x or older, install and prepare PostgreSQL server. 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.

  18. When upgrading from version 8.6 or older, upgrade PostgreSQL server (for supported versions, see System Recommendations) following PostgreSQL official upgrade documentation at https://www.postgresql.org/docs/12/upgrading.html.
    We have created Knowledge Base "How-to" article with information how we have tested the upgrade and also include estimated migration times. See Upgrade and migrate to new version of PostgreSQL

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

  20. 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"

  21. 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"

  22. Start the ubilogin-directory daemon:

    systemctl start ubilogin-directory

  23. Important: Add new entries and update LDAP secrets into OpenLDAP, ignore warnings about e.g. existing entries

    ./ldap/openldap/import-changes.sh

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

  25. 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 systemctl start ubisecure-accounting systemctl start ubilogin-server

  26. When upgrading from version 8.8.x or older, import initial key.

    Server signing and decryption key management was updated for SSO 8.9 and the initial signing and decryption key generated during SSO setup must be imported manually in the new location in Ubilogin Directory.

    cd /usr/local/ubisecure/ubilogin-sso/ubilogin ./ldap/openldap/import.sh ./ldap/initial-key.ldif

  27. The system upgrade is complete. For the new Java installation you need to import SSO certificate to Java trust store. See also other steps in Single node installation finalization.

  28. Remove the backed up ubilogin-sso-old directory, or rename and retain it as desired.

  29. Clear your web browser’s cache before accessing the user interface.