Upgrade on Linux - SSO

Last reviewed: 2020-02-04

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

  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. 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
  7. 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
    
  8. 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@
  9. When upgrading to version 8.4 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
  10. If Accounting Service has already been installed and in use 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
  11. If Accounting Service has already been installed and in use 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
  12. 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
    
  13. If robots.txt has been changed, copy the following file from the previous installation to the matching ubilogin-sso directory:

    /usr/local/ubisecure/ubilogin-sso-old/ubilogin/webapps/ROOT/robots.txt
  14. If the Password reset and password change application is used, 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)

    NOTE:

    Common Domain Cookie Discovery

    Check from the current   installation if Common Domain Cookie Discovery is installed or SAML   Compatibility Flags have been used. 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 Installation document.

    SAML Compatibility Flags

    Older versions of SSO stored   server-level SAML Compatibility Flags in the application configuration files.   These flags are now stored in LDAP and managed through the user interfaces.

    If SAML Compatibility Flags have been activated prior to   the upgrade remember to set those again manually. To check, examine

    /usr/local/Ubisecure/ubilogin-sso-old/ubilogin/webapps/WEB-INF/uas.properties

    If the line

    com.ubisecure.ubilogin.uas.saml2.compatibility   =

    exists and is not blank, make a note of all values and   copy them later to the main screen of SSO Management to the field   Compatibility Flags when installation is completed. Multiple values are   separated with a whitespace character. The values are case sensitive. The   values should remain visible on the screen after pressing Update. If the   value disappears, check for typing errors.


    If the environment has an external SQL database, copy the jdbc driver provided by the database vendor from the previous installation to the matching ubilogin-sso/java directory:

    cp /usr/local/ubisecure/ubilogin-sso-old/java/windows-x64/jre/lib/ext/{INSERT DRIVER FILENAME} /usr/local/ubisecure/ubilogin-sso/java/windows-x64/jre/lib/ext
  15. Run the setup script:

    cd /usr/local/ubisecure/ubilogin-sso/ubilogin
    ./setup.sh
  16. When upgrading to version 8.4 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.

  17. If you are upgrading from Ubisecure SSO 6.0.0 or 6.0.1 to 6.x, follow the instructions listed in the document Ubisecure SSO Authentication Migration. With newer versions, you can skip this step.

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

    /etc/init.d/ubilogin-directory start
  22. Important: Add new entries and update LDAP secrets into OpenLDAP, ignore warnings about e.g. existing entries

    ./ldap/openldap/import-changes.sh
  23. If you are upgrading from Ubisecure SSO 6.0.0 or 6.0.1 to 6.x, follow the instructions listed in the document Ubisecure SSO Authentication Migration. With newer versions, you can skip this step.

  24. When upgrading to version 8.4 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.

    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

  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 
    /etc/init.d/ubisecure-accounting start
    /etc/init.d/ubilogin-server start
  26. 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.

  27. Remove the backed up ubilogin-sso-old directory, or rename and retain it as desired.
  28. Clear your web browser’s cache before accessing the user interface.
  29. The user interface has changed in version 7.1 to support responsive design. Existing user interfaces are supported, but must be updated to enable backward compatibility. directory. For each template.properties file in the custom/templates directory, add the following text as the first line of the file

    # enable backward compatibility for SSO 6.x templates
    @import = sso6

    If the template contains a CSS reference, add the following line to the top of the referenced CSS file.

    /* enable backward compatibility for SSO 6.x templates */
    @import "sso6.css";

    If the CSS file contains references to graphical or other resources hosted by the Ubisecure SSO as a resource, ensure the resource path is a relative path. An example is shown below:

    #intro {
           background-image: url("resource/intro-box-custom-background.png")
    }

    Test all custom user interfaces. To implement a responsive design, create a new template, removing the “import” lines and adjust the CSS tags to match new CSS design. The responsive CSS is available after default installation at the address (where UAS_URL is the hostname for the installation):

    https://UAS_URL/uas/template/default/default.css