Upgrading SSO Connect

Instructions for upgrading your Keeper SSO Connect service to the latest version.

Keeper Security performs regular security, bug fix and feature releases to Keeper SSO Connect. Please update Keeper SSO Connect software regularly to ensure the latest compatibility and security updates are installed. IMPORTANT UPGRADE NOTES:

  1. Downtime required: Up to 30 minutes depending on IdP. Upgrading from a recent version (14.1.1 and newer) will only take a few minutes.

  2. Schedule a maintenance window to perform the upgrade, as users will be unable to login.

  3. Follow the upgrade steps below exactly as written

  4. Keeper SSO Connect requires supported Java version 11. Please refer to the software dependancies in the System Requirement section for links. Verify the environment variables are set. Refer to the Windows Installation section.

Reboot may be necessary after uninstalling / installing Java

For Windows installations, make sure your server is one of our supported Windows Server versions: - Windows Server 2008 R2 Datacenter SP1 64-bit - Windows Server 2008 R2 Enterprise - Windows Server 2012 R2 Standard - Windows Server 2012 R2 Datacenter - Windows Server 2016 Datacenter - Windows Server 2016 Standard - Windows Server 2019 Standard - Windows Server 2019 Datacenter

The instructions below are designed to be straightforward and easy. However, if you need additional support the Keeper Support Engineering team can be scheduled to assist. Our public calendar where you can sign up for a 1:1 session is here: https://calendly.com/keeper-engineering/sso Or send an email to: enterprise.support@keepersecurity.com Please specify the following information when scheduling: - SSO Connect Version - SSO Connect server OS version - Identity Provider name and version

Step 1. Check the SSO Connect config

Login to the Keeper SSO Connect service on your instance to check the current configuration. a. Windows: Double-click SSO Connect shortcut on desktop or open http://localhost:8080/config and Login as the Keeper Administrator. b. Linux: Open http://localhost:8080/config and Login as the Keeper Administrator. If you are unable to login, or if you receive an error "No SSO Service Providers Available", this means you are not a Keeper administrator with the proper admin permissions. Make sure to login as a Keeper administrator who has "Manage SSO" admin permissions as configured in the Keeper Admin Console. Visit the "Status" and "Configuration" screen and take a screenshot of the configuration - for example the hostname, Bound IP/port, etc. Make note of the local bound IP and port. This will be used in Step 6.

Step 2. Download the latest version of SSO Connect

The latest SSO Connect installers can be found here:

Windows: https://keepersecurity.com/sso_connect/KeeperSso.zip Linux: https://keepersecurity.com/sso_connect/KeeperSso_java.zip

Copy the downloaded file to each SSO Connect server.

Step 3. Stop SSO Connect Service

a. Windows: use the Services manager and stop the Keeper SSO Connect service. b. Linux: if you followed our original install instructions, run systemctl stop ssoconnect to stop the service. If you ran the SSO Connect service by hand or another way, you need to CTRL-C or kill the process.

Step 4. Install the latest SSO Connect

Make sure you have the local bound IP and port written down from step 2 because this information is needed after re-install. a. Windows: Unzip file and run the packaged .MSI installer.

If you are running SSO Connect version 14.1.0 or earlier , you will need to uninstall the previous versions of SSO Connect before running the new install.

b. Linux: First navigate to your directory where SSO Connect is installed. Delete all files and the services directories. Then Unzip the KeeperSso_java.zip file in the installation folder.

Step 5. Start SSO Connect Service

a. Windows: start the Keeper SSOConnect service using the Services manager. b. Linux: Start the service. If you followed our original install instructions, run systemctl start ssoconnect to start the service. If you ran the process by hand, this could also be started as java -jar SSOConnect.jar

Step 6. Verify the SSO Connect Config

a. Windows: Double-click SSO Connect shortcut on desktop or open http://localhost:8080/config and Login as the Keeper Administrator. b. Linux: Open http://localhost:8080/config and Login as the Keeper Administrator.

If you uninstalled the application in step 4, you may need to fill in the "Bound IP / Port" fields in the "configuration" screen then click Save. If required, leaving this blank will prevent the service from starting up.

Step 7. Verify the Upgrade Version

You can verify the version running by opening this URL in a browser (replace XXX and port with the advertised hostname and port), for example:

https://keeper.xyz.com:8443/ping

Ensure that the IP/Name and Port are accessible. If the service is active, you will get a JSON response as shown below:

{
"configuration": "Running",
"sync_revision": 1336,
"sync": "Thu Feb 28 14:57:06 PST 2019",
"version": "o14.2.0.17",
"sso": "Running",
"status": "Ready"
}

Check that the "version" response contains 14.1.3, 14.2.0 or newer.

Step 9. Verify SSO Logins

Ensure that end-user SSO Login is successful through the Keeper Web Vault, Desktop or mobile applications.

Upgrade Complete!

Troubleshooting

SAML Request/Response

On the left side of the SSO Connect interface is a button called "Show SAML debug". This screen will display the latest SAML transaction history, which should contain any errors from the IdP.

SSO Debug Screen

Log Files

On Microsoft Server installations, the log files reside within a hidden system directory. This directory can be access by typing the following path into the File Explorer:

C:\ProgramData\Keeper SSO Connect\logs
  • On Linux distributions, the logs are located with the sso_connect folder and varies depending on the base installation path:

/<base_path>/sso_connect/logs