SSO Connect On-Prem

Update Instructions

Step by Step update instructions for SSO Connect On-Prem

Only perform these steps if you are experienced with the installation of SSO Connect On-Prem.

Step 1. Back up your Server

It is recommended that you take a snapshot / back up your server in case you need to revert. Please take the necessary precautions when upgrading the service to limit any risk of downtime.

Step 2. Screenshot the Current Config

Login to the Keeper SSO Connect service on your instance to check the current configuration. Windows: Double-click SSO Connect shortcut on desktop or open http://localhost:8080/config and Login as the Keeper Administrator. Linux: Open http://localhost:8080/config and Login as the Keeper Administrator.

Take a screenshot of the current configuration, and make note of the local bound IP and port. This will be used in Step 7.

Step 3. Download the SSO Connect Installer

The SSO Connect Installer can be found by logging into the Admin Console and clicking on the Download link under the "Provisioning" tab.

Step 4. Stop SSO Connect Service

Windows: Open Windows Services, search for Keeper and Stop the service.

Linux: Run systemctl stop ssoconnect to stop the service, or if you ran the SSO Connect service by hand or another way, you need to CTRL-C or kill the process.

Ensure that all processes are stopped.

Step 5. Check your Java

Check the version of Java running. If you running anything below Java 11, you need to uninstall all versions of Java on your system and then install Java 11.

You can obtain Java 11.0.12 for Windows using the link below:

https://github.com/ojdkbuild/ojdkbuild/releases/download/java-11-openjdk-11.0.12.7-1/java-11-openjdk-11.0.12.7-1.windows.ojdkbuild.x86_64.msi Linux Java 11 install instructions depend on the platform.

Reboot is required after Java installation

Step 6. Install SSO Connect

Make sure you have the local bound IP and port written down from Step 2 because this information may be needed after re-install. Windows:

  • Unzip the KeeperSso.zip file

  • Run the unzipped .MSI installer.

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

Linux:

  • Navigate to your directory where SSO Connect is installed

  • Back up the folder

  • Delete all files and the services directories

  • Unzip the file KeeperSso_java.zip file in the installation folder (don't overwrite files)

  • Start the service as you normally would

Example:

cd /path/to/keeper

# backup the install folder
tar czf keeperbackup.tar.gz keeper/
cd keeper/

# remove the application files but leave data and logs
rm -f *
rm -fR services/
rm -fR static/

# copy the new SSO zip and extract it without overwriting
mv /path/to/KeeperSso_java.zip .
unzip -n KeeperSso_java.zip

# this depends on how you start the service
nohup java -jar SSOConnect.jar &

If the service doesn't start, or the installation hangs, please follow these steps:

  • Uninstall all versions of Java that you have currently installed.

  • Install Java 11 per the instructions in Step 5 above.

  • Reboot after the install.

It is recommended to reboot the server after the installation.

Step 7. Start SSO Connect Service

Windows: The service should automatically start. It sometimes takes a few minutes. You can also start the Keeper SSO Connect service using the Services manager. Linux: Start the service as you normally do. If you followed our original guide, run systemctl start ssoconnect to start the service. Or, if you ran the process by hand, this could also be started as java -jar SSOConnect.jar. Make sure there is only one process running.

Step 8. Verify the SSO Connect Config

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

You may need to fill in the "Bound IP / Port" fields in the "configuration" screen then click "Save". If the private IP was required for your configuration, leaving this blank might prevent the service from starting up.

Step 9. Verify the Upgrade Version

You can now 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": "o16.0.2",
    "sso": "Running",
    "status": "Ready"
}

Check that the "version" response contains the version which has been installed.

Step 10. Verify SSO Logins

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

Upgrade Complete!

Troubleshooting

Service Won't Start

Check the Java Version. SSO Connect requires Java 11.

  • Uninstall all versions of Java that you have currently installed.

  • Install Java 11 per the instructions in Step 5 above.

  • Reboot after the install.

400 Error

After upgrade, a few customers have experienced a 400 error when attempting to access the SSO Connect service status or to login with SSO. SSO Connect version 16.x and newer contains more strict security policies that enforce proper configuration.

Possible reasons for a 400 error:

  • SSL certificate loaded into SSO Connect has expired

  • SSL certificate subject name is mismatched with the front-end load balancer or reverse proxy configuration.

  • Ensure that the internal network communication between the load balancer or reverse proxy is using the fully qualified domain name (FQDN) as appears in the SSL certificate installed into SSO Connect.

Check the Log Files

Windows: 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

Linux: The logs are located with the sso_connect folder and varies depending on the base installation path: 

/<base_path>/sso_connect/logs

Check the log files for any errors during startup. If there are not enough detailed logs, you can modify the file called log4j2.xml in the folder path and update the log level to Debug as seen below:

After changing to debug, starting the service again will generate additional logs. Be sure to change it back to "info" after the problem has been solved.

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.

PreviousUpgrading SSO Connect On-PremNextUpdating On-Prem Config

Last updated