The following instructions should not be utilised. There remains a potential of data loss during these upgrade instructions. Customers are requested to follow these upgrade instructions which require a service break.

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) have been considered.

Overview

This page specifies the steps for updating a clustered deployment of a Ubisecure SSO configuration where at least one of the SSO nodes is operational during the whole procedure. The scope of the document includes the update steps of the SSO nodes and the LDAPs. Update of the reverse proxy server is not included in this document.

NOTE: If service break is allowed both SSO nodes can be updated using more straightforward procedure. See Clustered upgrade during a service break - SSO.

NOTE: In this document, the SSO 1 node is the schema master.

NOTE: If the solution contains additional components UbiloginCertAP and/or UbiloginWSIDP it is recommended to stop these services prior stopping the Ubiloginserver service whenever stated in the step list. UbiloginCertAP and UbiloginWSIDP services can be started after starting the Ubiloginserver service.

SSO Cluster

The diagram below describes an SSO cluster configuration to be updated.

High availability is achieved by using two SSO instances so that there is one active SSO node, and another, passive, as high availability option if another SSO node is not available. A reverse proxy is used to switch the traffic in case of failures. In case of high-performance setup, the traffic load can be distributed between both SSO nodes by the reverse proxy.

Note that LDAP content is replicated between the SSO instances, but both SSO nodes use their own LDAP (LDAPs can be installed also on their own nodes).

A reverse proxy is configured to use primarily SSO 1 node, and SSO 2 node only when SSO 1 node is not available. During the update operation, the reverse proxy is used to switch traffic away from an SSO node that is being updated while the other SSO node is still operational.

Clustered SSO Update

Update Procedure Overview

An overview of updating an Ubisecure SSO cluster is described in the following steps:

Find out which SSO node is the schema master
1. Use the Active Directory Schema snap-in to connect an AD LDS instance
2. Identify the schema master
Configure the reverse proxy server to route the production traffic only to the SSO 2 node
1. Setup both SSO nodes for the activity test
2. Optional: Test through the reverse proxy server which SSO node is active
3. Disable traffic from the reverse proxy server to the SSO 1 node
4. Test through the reverse proxy server which SSO node is active
Disable the replication
1. Stop the Ubiloginserver process from the SSO 1 node
2. Disable outbound and inbound replication from the SSO 2 node
3. Disable outbound and inbound replication from the SSO 1 node
Configure the metadata clean up for the retired AD LDS instances in the SSO 1 node
1. Clean up the metadata from the SSO 1 node using the dsmgmt tool
2. Remove the SSO 2 node server object from the SSO 1 node using the ADSI Edit tool
Update the SSO 1 node
1. Use document: Upgrade on Windows - SSO
2. Test the functionality of the updated SSO 1 node
Configure Proxy to route production traffic only to SSO 1 Server
1. Route the traffic towards the SSO 1 node
2. Optional: Export session information from the SSO 2 node's directory and import to SSO 1 node's directory
3. Setup SSO 1 node for the activity test
4. Test through the reverse proxy server which SSO node is active
Remove the AD LDS (UbiloginDirectory) from the SSO 2 node
1. Stop SSO and Accounting Service Windows services
2. Stop an remove the AD LDS from the SSO 2 node
Enable the replication in the SSO 1 node
Update the SSO 2 node
1. Install Java to the SSO 2 node according to the System Recommendations and Supported Platforms
2. Execute the steps in the document AD LDS clustering setup (node 2) - SSO
3. Install the new SSO version to the SSO 2 node
4. Update Tomcat configuration by reinstalling it to the SSO 2 node
5. Check Single node installation finalization
6. Test the functionality of the updated SSO 2 node
Enable traffic from the Reverse Proxy to route production traffic to SSO 2 node in addition to the SSO 1 node

Update Steps

IMPORTANT: When command line level commands are required run the command prompt window as an administrator.

Step 1. Find out which SSO node is the schema master

It is important to figure out which one of the SSO nodes is the schema master and execute all the steps accordingly. Schema master SSO node will be updated first and the second SSO node will be set up after that. It is enough to run the schema master check to one of the SSO nodes. In this document, the SSO 1 node is the actual schema master but the check is executed to the SSO 2 node.

a. Use the Active Directory Schema snap-in to connect an AD LDS instance

regsvr32 schmmgmt.dll

Click the OK button

mmc


File - Add/Remove Snap-in...


Available snap-ins - Active Directory Schema - Add - OK


Active Directory Schema - Change Active Directory Domain Controller (Do not mind the possible connection error).


This Domain Controller or AD LDS instance - <SSO_Node _Name>:<LDAP Port> Highlight the SSO Server name - OK

This Domain Controller or AD LDS instance - <SSO_Node _Name>:<LDAP Port>

Highlight the SSO Server name - OK


If you get this dialog - click the OK button

b. Identify the schema master


Active Directory Schema - Operations Master


Verify the schema master and click the close button.

Step 2. Configure the Reverse Proxy to route the production traffic only to the SSO2 node

a. Setup both SSO nodes for the activity test

Open the file index.html and type a text Node1 to SSO 1 node and text Node2 to SSO 2 node. Save the file.

cd /d "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\ROOT\

C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\ROOT\notepad index.html


Type: Node<SSO_node_number>

Update the ubilogin server.

c:\Program Files\Ubisecure\ubilogin-sso\ubilogin>config\tomcat\update.cmd

b. Optional: Test which SSO node is active through the reverse proxy server (NOTE, in high-performance configuration where both SSO nodes are always active you can skip this step.)


Write the uas.url to the browser (found from the win32.config file). Check which node responses.

Write the uas.url to the browser (found from the win32.config file).

Check which node responses.

NOTE, the certification error in the browser window above is due to the self-assigned certificate used in the test environment.

c. Using the reverse proxy server route the traffic towards the SSO2 node.

Disable the traffic between the SSO 1 node and the reverse proxy (load balancer).

d. Test which SSO node is active through the reverse proxy server


Write the uas.url to the browser (found from the win32.config file). Verify that the correct node responses.

Write the uas.url to the browser (found from the win32.config file).

Verify that the correct node responses.

Step 3. Disable the Replication

a. Stop the Ubiloginserver process from the SSO1 node.

net stop ubiloginserver

b. Disable the outbound and inbound replication for the SSO2 node

repadmin /options localhost:389 +DISABLE_OUTBOUND_REPL +DISABLE_INBOUND_REPL

Current DSA Options: (none)
New DSA Options: DISABLE_INBOUND_REPL DISABLE_OUTBOUND_REPL

c. Disable the outbound and inbound replication for the SSO1 node

repadmin /options localhost:389 +DISABLE_OUTBOUND_REPL +DISABLE_INBOUND_REPL

Current DSA Options: (none)
New DSA Options: DISABLE_INBOUND_REPL DISABLE_OUTBOUND_REPL

Step 4. Configure the metadata cleanup for the retired AD LDS instances in the SSO 1 node

Before Active Directory Lightweight Directory Service (AD LDS) replica can be restored, the SSO2 node object that represents this replica has to be removed from SSO 1 node.

a. Clean up the metadata from the SSO 1 node using the dsmgmt tool

Comments inside the brackets.

c:\>dsmgmt

dsmgmt: metadata cleanup

metadata cleanup: select operation target

select operation target: connections

server connections: connect to server <SSO1_Node_Name>:<Port> 
(By default, the LDAP port number is 389)

server connections: q

select operation target: list sites
(Identify the number that corresponds to the site in which the server object that you want to delete resides)

select operation target: select site <n>
(<n> represents the number that was identified in the previous command)

select operation target: list naming contexts
(Identify the number that corresponds to a naming context that was previously held by the server whose server object you want to delete.)

select operation target: select naming context <n>
(<n> represents the number that was identified in the previous command)

select operation target: list servers in site
(Identify the number that is associated with the server whose server object you want to delete)

select operation target: select server <n>
(<n> represents the number that was identified in the previous command)

select operation target: q

metadata cleanup: remove selected server
(Click yes to confirm the deletion of the server object)

metadata cleanup: q

dsmgmt: q

b. Remove the SSO 2 node server object from the SSO 1 node using the ADSI Edit tool

If an NTDS Settings object appears below the server object to be deleted, remove it first. The operation can be done in the ADSI Edit tool.

Connect to the ADSI Edit tool.


Start - Windows Administrative Tools - ADSI Edit Rick click ADSI Edit - Connect to...

Define the connection settings


Select a well known Naming Context - Configuration Select or type a domain or server - localhost:389

Remove the NTDS settings object under the SSO 2 node if it exists.


ADSI Edit - <SSO_2_node> - NTDS Settings - Delete Click the Yes button.

Remove the SSO 2 node object.


ADSI Edit - <SSO_2_node> - Delete Click the Yes Button. File - Exit

ADSI Edit - <SSO_2_node> - Delete

Click the Yes Button.

File - Exit

Step 5. Update the SSO1 node

The following is ONLY for the SSO1 Node

a. Execute the steps in the document: Upgrade on Windows - SSO

b. Test the functionality of the updated SSO 1 node. This might require separate reverse proxy server configuration. This should be planned considering the customer's application and network setup.

Step 6. Configure the reverse proxy to route production traffic only to SSO1 node

a. Using the reverse proxy server route the traffic towards the SSO 1 node and disable it to the SSO 2 node.

b. Optional: Export session information from the SSO 2 node's directory and import to SSO 1 node's directory

c. Setup SSO 1 node for the activity test

Open the file index.html and type a text Node1 to SSO 1 node and text Node2 to SSO 2 node. Save the file.

cd /d "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\ROOT\

C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\ROOT\notepad index.html


Type: Node<SSO_node_number>

Update the ubilogin server.

c:\Program Files\Ubisecure\ubilogin-sso\ubilogin>config\tomcat\update.cmd

d. Test which SSO node is active through the reverse proxy server


Write the uas.url to the browser (found from the win32.config file). Check which node responses.

Write the uas.url to the browser (found from the win32.config file).

Check which node responses.

Step 7. Remove the services and AD LDS from the SSO 2 node

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

b. Stop SSO and Accounting Service Windows services

net stop ubiloginserver

net stop ubilogindirectory

c. Remove SSO and Accounting Service Windows service configurations

cd "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin"
config\tomcat\remove.cmd

d. Remove the AD LDS from the SSO 2 node


Start - Control Panel - Programs - Uninstall a program - AD LDS Instance UbiloginDirectory - Uninstall


Click the Yes button.


Click the Skip button if you get this message (the replication is not on at this point in the SSO 2 node).

Click the Skip button if you get this message (the replication is not on at this

point in the SSO 2 node).


Click the OK button.

Step 8. Enable replication in the SSO 1 node

repadmin /options localhost:389 -DISABLE_OUTBOUND_REPL -DISABLE_INBOUND_REPL

Current DSA Options: DISABLE_INBOUND_REPL DISABLE_OUTBOUND_REPL
New DSA Options: (none)

Step 9. Update the SSO 2 node

a. Remove Java 8, install Java 11, and set JAVA_HOME according to Installation requirements - SSO.

b. Execute the steps in the document AD LDS clustering setup (node 2) - SSO

c. Install the new SSO version to the SSO 2 node.

Copy the Ubisecure SSO configurations from the SSO 1 node to the SSO 2 node.

- In practice, this means that the SSO installation folder (C:\Program Files\ubisecure\ubilogin-sso) is copied as such
- Check the win32.config file's parameter ldap.url to see if the LDAP has been installed in the localhost. If the directory (LDAP) connection is something else than "localhost" (LDAPs are installed on their own separate nodes) then modify the C:\Program Files\ubisecure\ubilogin-sso\ubilogin\config\settings.cmd file's LDAP URL parameters on the SSO node 2.
1. 1. set LDAP_URL=ldap://<IP address of the LDAP server 2>:389
  2. set LDAP_URL_HOSTNAME=<IP address of the LDAP server 2>
  3. set LDAP_URL_PORT=389

d. Update Tomcat configuration by reinstalling it (DON’T RUN setup.cmd on SSO node 2):

C:\Program Files\Ubisecure\ubilogin-sso\ubilogin>config\tomcat\install.cmd
Keystore already exist in c:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\tomcat\keystore.pfx
5 File(s) copied
776 File(s) copied
[SC] ChangeServiceConfig SUCCESS
[SC] ChangeServiceConfig2 SUCCESS
[SC] ChangeServiceConfig SUCCESS
The UbiloginServer service is starting..
The UbiloginServer service was started successfully.


Ubilogin Server started at https://www.example.com/ubilogin/

e. Check Single node installation finalization. For the new Java installation you need to import SSO certificate to Java trust store.

f. Test the functionality of the updated SSO 2 node. This might require separate reverse proxy server configuration. This should be planned considering the customer's application and network setup.

Overview

SSO Cluster

Clustered SSO Update

Update Procedure Overview

Update Steps

Step 1. Find out which SSO node is the schema master

Step 2. Configure the Reverse Proxy to route the production traffic only to the SSO2 node

Step 3. Disable the Replication

Step 4. Configure the metadata cleanup for the retired AD LDS instances in the SSO 1 node

Step 5. Update the SSO1 node

Step 6. Configure the reverse proxy to route production traffic only to SSO1 node

Step 7. Remove the services and AD LDS from the SSO 2 node

Step 8. Enable replication in the SSO 1 node

Step 9. Update the SSO 2 node

Step 10. Enable traffic from the Reverse Proxy to route production traffic to SSO 2 node in addition to the SSO 1 node

Browser not supported