Upgrade on Windows - SSO

Last reviewed: 2018-03-22

IMPORTANT: Sign in using an Administrator account - the same account used during initial product installation.

Updates from 6.0.x, 6.1 and 6.2 to 6.3 can be done according to these instructions as well.

Obtain and Install Oracle Server JRE 1.8.x and Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files
- You can find the download site in the address: http://www.oracle.com/technetwork/java/javase/downloads/index.html
- Refer to Oracle online documentation for installing the Server JRE https://docs.oracle.com/javase/8/docs/technotes/guides/install/windows_server_jre.html
- Instructions to install JCE Policy Files are included in the download package
- The Java Server JRE is distributed as a .tar.gz bundle for each platform. On Windows, extracting a tar.gz archive requires a separate application, such as 7-Zip (http://www.7-zip.org/)
Set up a system wide environment variables for Java
- Modify the paths according to your Java installation.
  Set JAVA_HOME to C:\Program Files\Java\jdk1.8.0_144
  Set JRE_HOME to C:\Program Files\Java\jdk1.8.0_144\jre
  Environment variables can be set Control Panel → System and Security → System → Advanced system settings → Environment Variables → System Variables → New...
Stop the UbiloginServer and UbiloginDirectory services.
```
net stop ubiloginserver
net stop ubilogindirectory
```
Backup and restore - Ubisecure Directory

Move the existing installation to ubilogin-sso-old directory.

cd /d "C:\Program Files\Ubisecure\"
move ubilogin-sso ubilogin-sso-old

Extract the archive ubilogin-sso-8.x.x.xxxxx.zip to a temporary location.
Move the complete unzipped ubilogin-sso directory from the distribution package to C:\Program Files\Ubisecure.

Copy win32.config and config.index file from older version. Overwrite config.index.

copy "C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\win32.config" "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\win32.config"
copy "C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\config.index" "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\config.index"

If upgrading from version prior to 6.8, add the following lines to the file C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\win32.config, if not there yet.
```
tomcat.instancename = UbiloginServer
tomcat.username = NT AUTHORITY\\LocalService
adam.username = NT AUTHORITY\\NetworkService
```

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

C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\custom\*
C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\methods\*
C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\logs\*
C:\Program Files\Ubisecure\ubilogin-sso-old\tomcat\logs\*

If Updating to a version prior to 8.2, copy the following file from the previous installation to the matching ubilogin-sso directory.
```
C:\Program Files\Ubisecure\ubilogin-sso-old\java\windows-x64\jre\lib\security\cacerts
```
If Updating from a version prior to 8.2 to version 8.2 or later and using an external user directory (other than Ubilogin Directory) or SMTP server, import the AD and/or SMTP server certificates to the Java keystore file.

NOTE: Java has been removed from the SSO installation since version 8.2. SSO uses currently Java in the C:\Program Files\Java\ directory.
To view all certificates from the old java keystore file, execute the command:
```
C:\Program Files\Ubisecure\ubilogin-sso-old\java\windows-x64\jre\lib\security>..\..\bin\keytool -list -keystore cacerts
```
To export a certificate from the old java keystore file, execute the command:
```
C:\Program Files\Ubisecure\ubilogin-sso-old\java\windows-x64\jre\lib\security>..\..\bin\keytool -exportcert -keystore cacerts -alias <"user_defined_alias"> -file <path_to_the_certificate_file>
```
To import a certificate to the current java keystore, execute the command:
```
C:\Program Files\java\jrex.x.x_xxx\lib\security>..\..\bin\keytool -import -file <path_to_the_certificate_file> -alias <"user_defined_alias"> -keystore cacerts
```
To verify that the certificate was succesfully added to the Java keystore, execute the command:
```
C:\Program Files\java\jrex.x.x_xxx\lib\security>..\..\bin\keytool -list -keystore cacerts -alias <"user_defined_alias">
```
Check the Common Domain Cookie Discovery and SAML Compatibility Flags.
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
C:\Program Files\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 update, re-enable the settings after update 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 update remember to set those again manually. To check, examine
C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\webapps\uas\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.
Run the setup script

NOTE: Ubisecure System Administrator password will be reset after upgrading the directory. The password will be set to the default value specified in the configuration file (win32.config or unix.config) with the key system.password.
You should either
a) Set the default password in the configuration file to a new stronger password before updating, or
b) Block external HTTP/S access to the system during the update process. You will be prompted to enter a new system password during the first login attempt. After the password is changed, unblock access to the system.
```
cd /d "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin"
setup.cmd
```
Start the UbiloginDirectory service
```
net start ubilogindirectory
```
Upgrading Ubisecure Directory

To update your ADAM or AD LDS installation, the schema and directory settings of the instance must be updated. Before starting, make sure that you are logged in with the same user account that was used to install ADAM or AD LDS.
To update the schema and directory settings, execute the command adaminstall.cmd shown below.
This command updates the LDAP schema and does not delete existing user or configuration data.
```
cd /d "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\ldap"
adam\adaminstall.cmd
```
NOTE: Please note that the system password is reset to the value contained in ubilogin\ldap\system-password.ldif
If you are upgrading from Ubisecure SSO 6.0.0 or 6.0.1 to 6.3, follow the instructions listed in the document Ubisecure SSO Authentication Migration. With newer versions, you can skip this step.

Import the new LDAP secrets file

cd /d "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin"
ldap\adam\import.cmd ldap\secrets.ldif

Copy the following files and directories from the previous installation to the matching ubilogin-sso directory.

C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\webapps\uas\WEB-INF\uas.properties
C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\webapps\cdc\WEB-INF\config.properties

If robots.txt has been changed, copy the following file from the previous installation to the matching ubilogin-sso directory:
```
C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\ROOT\robots.txt
```
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. Also, edit the server.xml file and check the web.xml file configuration. Skip this step if the Password reset and password change application is not used.
Copy the following files to the matching ubilogin-sso directory:
```
C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\webapps\password\WEB-INF\password.properties
C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\webapps\password\WEB-INF\saml2
```
Edit server.xml file and uncomment:
<Context path="/password" docBase="${catalina.base}/webapps/password"/>
```
notepad C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\config\tomcat\conf\server.xml
```
Also check web.xml for mail.smtp.host and mail.smtp.from configuration and copy those to new web.xml (C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\password\WEB-INF\web.xml)
```
notepad C:\Program Files\Ubisecure\ubilogin-sso-old\ubilogin\webapps\password\WEB-INF\web.xml
```
If the environment has an external SQL database, copy the JDBC driver provided by the database vendor from the previous installation to the matching java directory depending on the old and new SSO versions. Skip the step if the environment does not have an external SQL database or if both old and new SSO versions are 8.2 or later.
Old and new SSO versions prior 8.2:
```
copy C:\Program Files\Ubisecure\ubilogin-sso-old\java\windows-x64\jre\lib\ext\{INSERT DRIVER FILENAME} C:\Program Files\Ubisecure\ubilogin-sso\java\windows-x64\jre\lib\ext
```
Old SSO version prior to 8.2 and new SSO version 8.2 or later:
```
copy C:\Program Files\Ubisecure\ubilogin-sso-old\java\windows-x64\jre\lib\ext\{INSERT DRIVER FILENAME} C:\Program Files\Java\jrex.x.x_xxx\lib\ext{INSERT DRIVER FILENAME}
```

Update Tomcat configuration by reinstalling (Notice the output after remove.cmd command):

C:\cd /d "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin"
C:\Program Files\Ubisecure\ubilogin-sso\ubilogin>config\tomcat\remove.cmd
  The UbiloginServer service is not started.
  More help is available by typing NET HELPMSG 3521.
C:\Program Files\Ubisecure\ubilogin-sso\ubilogin>config\tomcat\install.cmd

The UbiloginServer service is automatically restarted and the system update is complete.

NOTE: If you have Ubisecure CustomerID installed, you need to copy the Authorizer files at this point. For instructions, please see document Ubisecure CustomerID Installation, chapter Customer ID SSO Adapter Installation on Windows.
Either securely remove the backed up ubilogin-sso-old directory, or rename it and store it in a secure location. All configuration files in the old installation directory (win32.config and u nix.config) should either be removed from the system or otherwise protected from unauthorized users.
Clear your web browser’s cache before accessing the user interface.
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
```