Upgrade on Linux - SSO

These are the upgrade instructions to the latest release: SSO 9.1. If you are upgrading from a SSO 8.x.x version, ensure the upgrade steps to SSO 9.0 (Java11, systemd service management, and OpenLDAP MDB) have been considered.

Note: we have removed all upgrade steps for SSO 8.x.x to SSO 9.0.0 - please ensure you follow the required upgrade instructions to move from SSO 8.x.x to SSO 9.0.0 then follow these upgrade steps to SSO 9.1.0


  1. Stop the daemons that are running

    systemctl stop ubilogin-server
    systemctl stop ubilogin-directory
    systemctl stop ubisecure-accounting
  2. Remove SSO and Accounting Service daemon configurations

    cd /usr/local/ubisecure/ubilogin-sso/ubilogin
    ./config/tomcat/remove.sh
  3. 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
  4. Backup the existing Ubisecure SSO installation and OpenLDAP:

    cd /usr/local/ubisecure
    mv ubilogin-sso ubilogin-sso-old
  5. 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
  6. 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
    
  7. Verify the following settings in /usr/local/ubisecure/ubilogin-sso/ubilogin/unix.config are according to your requirements, see further instructions for openldap specific values from here The Macro language - SSO

    openldap.root= uid=System,ou=System,@suffix@
    openldap.maxsize = 10737418240
    openldap.idlexp = 20 
  8. Verify the following Accounting Service related settings in /usr/local/ubisecure/ubilogin-sso/ubilogin/unix.config are according to your requirements, check these guidelines. NOTE that accounting.jms.broker.host has been added in SSO v. 9.3.

    # 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.host = @accounting.proxy.local.url.host@
    accounting.jms.broker.port = 36161
    accounting.jms.broker.socket-timeout-ms = 10
  9. 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
  10. 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.

    Verify that the Accounting Service custom configuration file:

    /usr/local/ubisecure/ubilogin-sso-old/ubilogin/custom/accounting/config/application.yaml 

    is compatible with the version in the installation package located at

    /usr/local/ubisecure/ubilogin-sso/ubilogin/config/accounting/config/application.yaml


    See also Accounting Service additional configuration.

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

  12. 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 enabled prior to the upgrade, re-enable the settings after upgrade according to the Common Domain Cookie Discovery document.


  13. Run the setup script:

    Tip

    Before running the setup script check if you want to preserve some of the settings that may otherwise be regenerated, see: Preserve essential configuration settings in upgrade.

    cd /usr/local/ubisecure/ubilogin-sso/ubilogin
    ./setup.sh
  14. 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
  15. Ensure that a supported version of PostgreSQL is installed and running - for supported versions, see System Recommendations, additional links in our documentation:  PostgreSQL preparation on Linux, Upgrade and migrate to new version of PostgreSQL

  16. 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
  17. 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"
  18. 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"
  19. Start the ubilogin-directory daemon:

    systemctl start ubilogin-directory
  20. Important: Add new entries and update LDAP secrets into OpenLDAP, ignore warnings about e.g. existing entries

    ./ldap/openldap/import-changes.sh
  21. Verify your Accounting Service customisation in /usr/local/ubisecure/ubilogin-sso/ubilogin/custom/accounting/config/application.yaml appears as you require, check Accounting Service additional configuration about the properties to set. Remember secret key in the location referred by accounting.secret-key-location in unix.config must exist. See Accounting Service security about the usage of the key for pseudonymisation.

  22. Reinstall SSO Tomcat and Accounting Service configuration and start the services.

    cd /usr/local/ubisecure/ubilogin-sso/ubilogin
    ./config/tomcat/install.sh 
    systemctl start ubisecure-accounting
    systemctl start ubilogin-server
  23. Ensure that you have imported initial signing and decryption key via initial-key.ldif. This should have been completed during earlier upgrades.

    Import key operation needs to be done only once when upgrading from version 8.8.x or older to version 8.9.x or newer, and should not be done for any follow-up updates from 8.9.x or newer to newer versions.

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

  25. Remove the backed up ubilogin-sso-old directory, or rename and retain it as desired.
  26. Clear your web browser’s cache before accessing the user interface.