Keeper SSO Connect On-Prem provides seamless integration with your SAML 2.0 identity provider in a Zero-Knowledge security architecture.

This technical guide provides detailed information on how to deploy Keeper SSO Connect On-Prem in your public cloud, private cloud or on-prem environment and use the powerful features of the Keeper Enterprise platform.

Setup time: Up to 1 hour

1. Configure the Keeper Admin Console for SSO Integration.

2. Download, install, and configure the Keeper SSO Connect Service on any private or public cloud instance(s) or on-prem if desired.

3. Configure the Keeper Application on the IdP.

Proceed to the next page for a more in-depth overview followed by the system requirements.

Keeper SSO Connect is a SAML 2.0 application that leverages Keeper’s zero-knowledge security architecture to securely and seamlessly authenticate users into their Keeper Vault and dynamically provision users to the platform. Keeper SSO Connect works with popular SSO IdP platforms such as Okta, Microsoft Azure, Google G Suite, Microsoft ADFS, F5 BIG-IP APM, Centrify, OneLogin, Ping Identity, and CAS to provide businesses the utmost in authentication flexibility.

Keeper SSO Connect is a software application that is installed on the enterprise’s on-premise, private cloud, or public cloud infrastructure. All user encryption keys are managed by Keeper SSO Connect, providing the customer with full control over the keys that are used to encrypt end-user vaults.

The Keeper SSO Connect service application can be installed on a private on-premise or cloud-based server. Windows and Linux-based operating systems are supported.

Once you have installed Keeper SSO Connect On-Prem on a server in your environment, the next step is to configure the SAML 2.0 authentication into your identity provider.

Keeper SSO Connect On-Prem can be integrated with any SAML 2.0 compliant identity provider. We have documented the steps for several popular platforms in the pages that follow.

• Azure

• Okta

• Google Workspace

• Microsoft AD FS

• Ping Identity

• OneLogin

• JumpCloud

• RSA SecurID Access

• F5

• Centrify

• AWS SSO

If your Identity Provider is not listed here, don't worry. Keeper is compatible with all SAML 2.0 SSO identity providers. You can just follow the step by step instructions of a similar provider in the list above, and it will be generally the same setup flow.

(If you create a setup guide for your identity provider, please share it with us and we'll post it here!)

Keeper is compatible with any SAML 2.0 identity provider. Please use the reference guides in this documentation for configuration. If you need assistance, contact us.

The basic steps for setting up Keeper SSO Connect are listed in the steps below. Detailed instructions are annotated further in this guide.

Keeper SSO Connect On-Prem can be optionally configured to operate in a multi-instance HA environment. Once the first instance is configured (per and instructions in this document) and the service is enabled to start on boot, the instance can be cloned and additional instances can be launched behind a load balancer.

Keeper Security is RSA SecurID Access Certified.

RSA SecurID Access integrates RSA Authentication Manager and their Cloud Authentication Service. In this setup Cloud Authentication Service can be used as an identity provider in conjunction with Keeper SSO Connect. Detailed documentation is provided on the RSA website via the links below.

If you have any questions or require assistance in configuring Keeper SSO Connect, please contact the Keeper Enterprise Support team at: .

SSO Connect On-Prem SSL certificates must be updated on an annual basis, or there may be times that the metadata.xml file needs to be updated on the SSO Connect server. Follow these instructions:

1. Login to the SSO Connect On-Prem server and click the "Configuration" tab. Make the desired change (update SSL certificate, hostname change, update IdP SAML metadata, etc.).

2. Save the changes. (This replicates the changes to the Keeper Cloud).

3. If multiple SSO Connect servers (HA configuration) are present in your architecture, no further steps are required as each subsequent SSO Connect server will synchronize to the cloud and update. However, to force the sync, click on “Full Sync” on the SSO connect menu on each server.

The Keeper SSO Connect is a lightweight service that can be installed on a private on-premise or cloud-based server. The application is hosted by the customer in order to preserve zero knowledge and provide compatibility with any SAML 2.0 compatible identity provider.

Supported Server Platforms

The following server platforms are currently supported:

Supported Windows Server Versions Windows Server 2019 Standard Windows Server 2019 Datacenter Windows Server 2022 Standard Windows Server 2022 Datacenter Windows Server 2025 Standard Windows Server 2025 Datacenter

Supported Linux versions: Ubuntu 18+ CentOS 7+ Debian 9.8+ openSUSE Tumbleweed openSUSE Leap 15.1+ Red Hat Enterprise Linux 6.8+

Supported Java versions Java 11+

Java Dependencies

Keeper SSO Connect requires at least Java 11. The installer for Windows provides the option to bundle the latest LTS Amazon Corretto 11 version. If you have a different version of Java installed we recommend uninstalling that version and install Java 11 first before you proceed. Otherwise you may experience service hanging during installation.

After the reboot, check the java installation version 1. Open an Administrator Command Prompt. 2. Type java -version. 3. Verify the java version installed is found.

If Java isn't recognized on the command line, follow the steps below.

• Open 'Advanced system settings'

• Click Environment Variables. In the section System variables, find thePATH environment variable and select it. Click Edit. If the PATH environment variable does not exist, click New.

Server Hardware Requirements

The following table outlines the minimum hardware requirements per each server.

Scalability and High Availability

The Keeper Connect service on a single instance can handle thousands of simultaneous users.

However, both scalability and high availability can be achieved by placing a load balancer in front of a cluster of Keeper SSO Connect servers. The Keeper Cloud backend will take care of configuration synchronization. Changes applied to one server are automatically distributed to all servers in the same SSO node cluster. This includes the user database.

Further scalability, for example to scale to 100,000 users or more, can be achieved by splitting groups of users up into multiple SSO Connect domains. This will require creating separate SSO-enabled node(s) in the Keeper Admin Console and a separate SSO server or server cluster for each node.

HSM Integration (Optional)

SSO Connect can optionally be integrated with Amazon CloudHSM or Gemalto HSM solutions to protect the private encryption keys. The following HSM modules are currently supported:

Network Deployment Requirements

The following network requirements apply to Keeper SSO Connect deployments.

• Keeper SSO Connect network connections to Keeper Cloud servers at keepersecurity.com (US) or keepersecurity.eu (EU customers) is TCP/443 (TLS 1.2) outbound stateful.

• End-user devices must connect to SSO Connect via the advertised public FQDN/IP and TCP port. For example, keepersso.mycompany.com.

• Local server bind port and the external advertised connection port are configurable separately. In that scenario the ports need to be translated via a load balancer, firewall or locally (eg. iptables).

Once your server is setup and operational you should setup SSO Connect as a service. This operation will vary depending on your OS.

1. If the application is still running because you configured it with the web interface, stop the running instance on the command line by entering CTRL-C.

2. As the root user, create a system startup file /etc/systemd/system/ssoconnect.service with the following content (replace /path/to/keeper with your exact path and replace <user> with your username that will be running the process

"chmod" the file:

Enable the service to auto-start.

Run systemctl to start the service.

Troubleshooting Linux

To test the service response or to monitor the health of the Keeper SSO Connect instances, you can query the "Ping URL" which in the above example is:

Note the local ping is being used here because we connected to the local instance via port forward. To check the service running from the outside (external users) you can use the public port:

Example request/response:

You can review log files which are located by default in /path/to/keeper/logs/ssoconnect.log. The logging is done through a standard log4j2.xml file located in the install directory. You may change the log4j2.xml file to place your log files anywhere you wish.

The next section provides Identity Provider setup instructions for each major vendor.

F5

On the F5 BIG-IP APM, configure a new SAML IdP service for your Keeper platform: Go to Access Policy -> SAML -> BIG-IP as IdP -> Local IdP services

Navigate to: Access Policy > SAML : BIG-IP as IdP - Local IdP Services. Select your applicable IdP connection point and "Export Metadata".

Upload this file to the server where Keeper SSO Connect is installed. We'll need it in the next step. Import the Metadata file extracted from F5 BIG-IP APM into SSO Connect.

Select Save to save the configuration and verify all settings look correct. Export the Keeper SSO Connect Metadata file for configuration of F5 BIG-IP APM from the Export Metadata link.

Your Keeper SSO Connect setup is now complete!

• Keeper Security Website

• Keeper Enterprise Guide

• SSO Connect Product Page

• ​

Additional Security Details

To learn more about the Keeper Encryption Model, see the below link:

PingOne

Login to the PingOne Admin portal

From the PingOne console menu, select Applications > Application Catalog

Each subsequent server added to an SSO Connect provisioning method will automatically download the configuration and user SSO data when the SSO Connect successfully authenticates as an administrator with the SSO permission. This reduces the amount of "reconfiguration" needed to migrating to a new server or to make the server part of an HA environment.

1. Install the new SSO Connect server as previously done for Windows or Linux.

Centrify

Login to the Centrify Admin portal via the cloud login.

Switch to the Admin Portal from the pull down menu.

Close the Quick Start Wizard if it pops up. Select Apps from the menu then Add Web Apps.

On the Add Web Apps window, select the Custom tab and then scroll down and choose Add for SAML.

Select Yes to “Do you want to add this application?”.

Close the Add Web Apps Window.

The next step is to upload Keeper’s SSO Metadata to Centrify. In Keeper SSO connect, export the Keeper SSO Connect metadata using the Export Metadata link and save this file for the next step.

In the SAML Application Settings section in Centrify, select Upload SP Metadata.

Select Upload SP Metadata from a file and browse for the KeeperSSOMetadata.xml file. Select Ok.

Download the Identity Provider SAML Metadata. This will be uploaded to Keeper SSO Connect.

On the Description section enter Keeper SSO Connect in the Application Name field and select Security in the Category field.

Download the Keeper logo. Select Select Logo and upload the Keeper logo (keeper60x60.png).

On the User Access section select the roles that can access the Keeper App:

Under the Account Mapping section, select "Use the following..." and input mail.

On the Advanced section, append the script to include the following lines of code:

• The above script reads the display name from the User Account section. The FirstName attribute is parsed from the first string of DisplayName and the LastName attribute is parsed from the second string of DisplayName.

Select Save to finish the setup.

Upload the Identity Provider SAML Metadata file into the Keeper SSO Connect interface by dragging and dropping the file into the Setup screen:

Select Save and Your Keeper SSO Connect setup is now complete!

Setup:

Login to the OneLogin portal.

Select Administration to enter the admin section.

From the onelogin menu select Applications then Add App.

In the Search field, do a search for Keeper Password Manager and select it from the search result.

On the Add Keeper Manager screen click Save.

The next step is to download the SAML Metadata from OneLogin. Select the down arrow on the MORE ACTIONS button and select SAML Metadata.

The onelogin_metadata_######.xml file will download to the browser. Copy this file to the Keeper SSO Connect server interface.

On the OneLogin Configuration tab, type in the Assertion Consumer Service Endpoint from your Keeper SSO Connect server: (i.e. https://DOMAIN:8443/sso-connect/saml/sso where DOMAIN is the server name or IP address of your Keeper SSO Connect application) then click Save.

Back on the Keeper Provisioning tab, click on "Add Method" and select SCIM.

Click Generate then copy the URL and Token.

Paste the "URL" into the SCIM Base URL, and paste the "Token" into the SCIM Bearer Token then click Save.

Click Save on the Keeper Admin Console and the integration is complete.

JumpCloud

JumpCloud instructions for setting up Single Sign On (SSO) with Keeper Security. As listed in the JumpCloud SSO Prerequisites a public certificate and a private key pair are required. Instructions can be found here:

Log into the JumpCloud Administrator console.

Select the Applications tab on the side menu.

Next, select the + icon in the upper left corner.

Search for Keeper in the Application list search bar. Select Configure on the Keeper Application.

Next, on Keeper Application connector page, enter the IDP ENTITY ID:

The IDP ENTITY ID is a unique, case-sensitive identifier used by JumpCloud for this Service Provider (SP). This value should match the value specified in the Entity ID field of the Keeper SSO Connect. Your domain name, SSO Connect server name or IP address are possible examples. Next, Upload the IdP Private Key (private.pem file) and IDP Certificate (cert.pem file).

In the SP Entity ID field, enter the value found in the Entity ID field of the Service Provider Section from Keeper SSO Connect.

In the ACS URL field, enter the value found in the ACS URL field of the Service Provider Section from Keeper SSO Connect.

In the field terminating the IdP URL, either leave the default value or enter a plaintext string unique to this connector. (i.e. keepersecurity)

In the Display Label field, enter a label that will appear under the Service Provider logo within the JumpCloud User console. (i.e. Keeper Security)

Note: Keeper SSO Connect expects that the SAML response is signed. Ensure that JumpCloud is configured to sign SAML responses.

To complete the configuration, select the activate button.

Last step is to export the metadata from this connector to import it into the Keeper SSO Connect in Step 8.

Upload this file into the Keeper SSO Connect interface by dragging and dropping the file into the Setup screen:

Select Save and Your Keeper SSO Connect setup is now complete!

Keeper Security performs security updates to Keeper SSO Connect On-Prem.

Step by Step Instructions

Follow the instructions in the Update Instructions page to proceed with the upgrade.

Proceed with Step by Step Instructions

Need Help?

If you are not familiar with your environment or if you are not comfortable performing the update, please .

Before you contact support, please provide the following information:

• SSO Connect Version

• SSO Connect server OS version

• Identity Provider name and version

Access the web interface

In order configure Keeper SSO Connect via the web interface, access to the configuration portal is necessary. If the server has a graphical user interface and a web browser the admin can launch it directly through local access. However if the server doesn't have a GUI or browser, use of an SSH Tunnel will be necessary. Please determine which method meets your needs and after the web interface is accessible proceed to the the configuration steps.

Okta SSO Configuration

Ping Identity

Azure

Go to your Azure Admin account at and click on Azure Active Directory > Enterprise Applications.

If you already have a Keeper application set up for SCIM Provisioning, you can edit the existing application and should not create a new one.

If you have not set up Keeper in Azure yet, click on "New Application" then search for Keeper and select "Keeper Password Manager & Digital Vault". On the right side click "Add" to add the application.

After adding the application, click on the "Single Sign On" section and select the "SAML" option:

Edit Basic SAML Configuration

Click the pencil icon to edit the "Basic SAML Configuration".

Type in the Identifier, Reply URL and Sign on URL that apply to the URLs in your Keeper SSO Connect installation. Ignore the "Patterns" text.

Example Settings: Identifier = https://xyz.domain.com:8443/sso-connect Reply URL = https://xyz.domain.com:8443/sso-connect/saml/sso Sign on URL = https://xyz.domain.com:8443/sso-connect/saml/login

(replace the domain and port according to your SSO Connect configuration)

Save the settings.

Edit User Attributes & Claims

Under the User Attributes section, Azure will automatically create claims for User ID, First, Last and Email.

We recommend deleting the 4 claims in the "Additional Claims" section since they are not needed.

Edit SAML Signing Certificate SAML

Under the SAML Signing Certificate section click Edit.

Select Create new certificate. Enter the expiration date and save.

After creating the certificate select Make new certificate active.

Select signing option "Sign SAML response and assertion" with SHA-256 signing method.

Obtain Metadata XML

To complete the integration between Microsoft Azure and Keeper SSO Connect, you must retrieve the Metadata XML file and import this file into the Keeper SSO Connect screen. Select on the Federation Metadata XML link:

This will download a file Keeper Password Manager & Digital Vault.xml to your computer. This file will need to be transferred to the server running Keeper SSO Connect for the next step.

Import the Azure Metadata

Import the file saved in the previous step into Keeper SSO Connect’s configuration screen by dragging and dropping the file into the SAML Metadata section.

User Provisioning

If only specific users or groups will be assigned to Keeper Password Manager the following setting will need to be changed. In your Azure console, navigate to Azure Active Directory > Enterprise Applications > Keeper Password Manager & Digital Vault and select Properties.

Change the User assignment required to Yes and then save. This will ensure only the user and groups assigned to the application will be able to use it.

On the Users and groups section select the users and/or groups that are to be provisioned to the Keeper application.

Your Keeper SSO Connect setup is now complete!

Java Runtime

As described in the page, the Java runtime is required to run Keeper SSO Connect. It can be installed by the admin or it can be optionally included in the Keeper installer. Make sure to install a compatible version of the Java runtime.

This document provides step by step instructions on generating an SSL certificate for use in Keeper SSO Connect On-Prem. For existing environments, this action must be performed before your SSL certificate expires.

If you are using Linux, there is no need to install a binary version of OpenSSL. The instructions below here focus on Windows environments.

Overview

Keeper now supports an automated process for migrating your users from SSO Connect On-Prem to Keeper SSO Connect Cloud.

When migrating to SSO Connect Cloud, there is a change in the user experience, specifically in regards to new device approvals. Please ensure that you read the documentation.

Note: This migration process does not include device approvals. Device approvals will need to be configured using one the standard Keeper methods as documented

AWS SSO

Node Structure

Visit the and login as the Keeper Administrator

US Data Center:

US Public Sector / GovCloud:

Integration with AWS Cavium CloudHsmV2

Keeper SSO Connect HSM Overview

Inside SSO Connect's data folder there are several files. Two of the files contain secret keys generated on the server that must be protected and are utilized to encrypt and decrypt the end-user's auto-generated master passwords. There is also a .sql file which contains a local cache of encrypted data. It is critical that access to this data folder is restricted.

On non-Windows machines the data folder is under the SSO Connect install folder, typically $HOME/sso_connect/data.

On Windows machines the data folder is in C:\ProgramData\Keeper SSO Connect\data\ since v14.1. Prior to v14.1 it was in C:\Program Files\Keeper Security\SSO Connect\data\.

You can add an extra layer of security by utilizing an HSM (Hardware Security Module) as described below. When an HSM is available, an encryption key is generated for each SSO Connect instance and stored securely in the HSM. The encryption key is used to encrypt the critical property files in the data/ folder.

AWS Cavium CloudHsmV2 Instructions

HSM Requirements

1. Amazon currently allows only CloudHsmV2 for new HSM deployments; Keeper supports this version. a. Legacy Cloud HSM v1 hardware is not supported by Keeper.

2. Amazon HSM software currently supports Linux or Windows installations.

Network Requirements

• Port TCP/443 open, stateful outbound from Keeper SSO Connect to www.keepersecurity.com

• Port TCP/2223 open, bidirectional from the SSO Connect machine to the HSM hardware

• Port TCP/2225 open, bidirectional from the SSO Connect machine to the HSM hardware

Testing network access

CloudHsmV2 software installation

Provision your Amazon HSM cluster and install the HSM software on the SSO Connect machine as described in:

or

You will need the Java libraries. On Linux the software is installed in /opt/cloudhsm.

Ensure that the cloudhsm_client service is running in the background:

Test the Software Installation

Install SSO Connect as usual.

NOTE: The Amazon HSM Java software is supposed to recognize a file named HsmCredentials.properties on the Java Classpath. However, this may not work for some reason. Instead you may need to set HSM_USER, HSM_PASSWORD, and HSM_PARTITION environment variables. For testing, you will probably have to set the shell variables.

Test the HSM connection:

It should print the keys in the HSM.

Configure SSO Connect as usual via the command line or in the admin interface at http://localhost:8080/config

a. Set the "Advertised Hostname", a. Add the SSL certificate, a. Add the SAML XML metadata file.

In the admin interface, the HSM configuration section is at the bottom of the Configuration page.

a. Select "Amazon CloudHsmV2" as the type, a. Some properties will appear in the box below. You probably don't need to change them. i. An exception would be if the certificate to be used to talk to the HSM is not the same certificate used for SSL in SSO Connect. i. You may need to enter a password for the certificate file (usually the same one used for the SSL certificate file). a. Click the Enabled/Disabled box, a. Click Save

SSO Connect should now restart and connect to the HSM. If the status page shows that HSM is enabled, it worked. In rare situations when startup is very slow you may need to click on the Status command again so that it updates the status.

If it didn't work, check the SSO Connect error log. The most common error is that it can't find the HSM credentials. Set the credentials as environment variables to ensure that they are available.

If it didn't work, check the error log. The most common error is that it can't find the HSM credentials. Set the credentials as environment variables to ensure that they are available.

Troubleshooting

Troubleshooting the Configuration

1. Verify that SSOconnect is installed on the machine.

   • Usually there is a folder called sso_connect, KeeperSSO, or some similar name. The folder will contain many jar files.

Troubleshooting the Operation

1. Check the log file for errors. The Secure Key Storage subsystem of SSOconnect will print an ERROR line to the log if it encounters a problem.

2. The error will be a variation of "Unable to use Secure Key Storage". This indicates one of the following problems:

Backup

The data folder contains the SSO Connect configuration files. At a minimum it should be backed up after initial configuration and each time the configuration is modified. In addition to the configuration files, there are data files in data but they will automatically be refreshed if they get out of synch with the Keeper server. Thus, regular periodic backups can be used but are not necessary. The data folder on each SSO Connect instance needs to be backed up independently because not all of the configuration settings are shared among instances.

On non-Windows machines the data folder is under the SSO Connect install folder, typically $HOME/sso_connect/data.

On Windows machines the data folder is in C:\ProgramData\Keeper SSO Connect\data\ since v14.1. Prior to v14.1 it was in C:\Program Files\Keeper Security\SSO Connect\data\.

Recovery

Server Failure

If the SSO Connect server dies you will need to reinstall Amazon HSM and SSO Connect on the replacement machine using the standard installation instructions above.

If you have backed up the data folder as described above, restore it before starting SSO Connect. If a data folder already exists (because you started SSO Connect), stop SSO Connect, remove all files in the data folder, copy the files from the backed-up data folder, and restart SSO Connect. SSO Connect should start successfully.

If you did not backup the data folder or if the backup is out-of-date you will need to configure the replacement instance as if it were a new installation. Please follow the SSO Connect installation guide.

HSM Failure

When using an HSM, the HSM stores the encryption key used to decrypt the configuration files in the data folder. The HSM is accessed once, when SSO Connect starts, and also any time the configuration is changed. If the configuration files are encrypted and the encryption key stored on the HSM is lost or inaccessible the SSO Connect instance will need to be configured again in order to create new, unencrypted configuration files. Delete the contents of the data folder and configure SSO Connect from scratch again.

You can disable HSM/SKS use by entering 'no' to the "Enable SKS?" configuration question, or by using the -disableSKS command-line option.

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.

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.

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.

Linux:

• Navigate to your directory where SSO Connect is installed

• Back up the folder

• Delete all files and the services directories

Example:

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.

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.

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:

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

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:

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

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.

Installation - Linux

Instance Requirements

1. Java 11 runtime environment

2. Inbound port required for SAML communication from end-user device/browser (defaults to port 8443). If users can login from IdP on the public Internet, then this port must be public.

3. Outbound SSL port 443 opened to keepersecurity.com.

4. SSL private key (PKCS#12 or Java Keystore). During initial testing, a self-signed certificate is sufficient but users will receive a browser security warning.

5. FQDN assigned to the instance or to the load balancer.

Initial installation of Keeper SSO Connect can be performed on a single instance prior to being deployed in an HA environment. After the service is configured, the settings will automatically synchronize between load balanced instances. Make sure that the correct version of Java is installed and in your path. Java 1.7, Java 9, and Java 10 are NOT supported.

If java is not found, please install it. For example:

Download and unzip the SSO Connect service:

Then start the Keeper SSO Connect service:

Now that the application is installed, you can configure SSO using the web browser GUI or through the command line. Configuration options are discussed in the next section.

OpenSSL v1.1.1

Keeper SSO Connect requires a valid signed SSL certificate that has been signed by a public certificate authority. Self-signed certificates may work for testing however most client applications will fail to connect.

Please use OpenSSL v1.1.1 to generate your SSL certificates. There is a known compatibility issue between certificates generated on OpenSSL 3.0 and Java 11.

Backup

The data folder contains the SSO Connect configuration files. At a minimum it should be backed up after initial configuration and each time the configuration is modified. In addition to the configuration files, there are data files in data that are modified at runtime but they will automatically be refreshed if they get out of sync with the Keeper server. Regular periodic backups can be used but are not necessary. The data folder on each SSO Connect instance needs to be backed up independently because not all of the configuration settings are shared among instances.

If you would like to configure SSO Connect on the command line then please see the sections below. If SSO Connect is already configured, skip to the section.

Linux configuration with interactive mode

Keeper SSO Connect can be started in configuration mode, which prompts you for the necessary parameters.

Integration with Gemalto HSM

Keeper SSO Connect HSM Overview

Inside SSO Connect's data folder there are several files. Two of the files contain secret keys generated on the server that must be protected and are utilized to encrypt and decrypt the end-user's auto-generated master passwords. There is also a .sql file which contains a local cache of encrypted data. It is critical that access to this data folder is restricted.

On non-Windows machines the data folder is under the SSO Connect install folder, typically $HOME/sso_connect/data.

On Windows machines the data folder is in C:\ProgramData\Keeper SSO Connect\data\ since v14.1. Prior to v14.1 it was in C:\Program Files\Keeper Security\SSO Connect\data\.

You can add an extra layer of security by utilizing an HSM (Hardware Security Module) as described below. When an HSM is available, an encryption key is generated for each SSO Connect instance and stored securely in the HSM. The encryption key is used to encrypt the critical property files in the data/ folder.

Gemalto Luna HSM Instructions

HSM Requirements

1. The Gemalto HSM must be running Luna firmware 6.2 or higher.

Network Requirements

• Port TCP/443 open, stateful outbound from Keeper SSO Connect to www.keepersecurity.com

• Port TCP/22 open, stateful outbound from the HSM management terminal to the HSM system

• Port TCP/22 open, inbound to the Keeper SSO Connect server for CLI configuration

Testing network access

Linux-specific requirements

CentOS 6 or 7 is preferred, but the software can run on Ubuntu with the following additions:

If /lib/ld-linux.so.2 exists, go to the next section

Install the Luna Client

The Luna client must be installed and properly configured before Keeper SSO Connect can use the Luna HSM.

• Copy the LunaClient software to the SSO Connect server. The file usually has a name like LunaClient_7.3.0-165_Linux.tar.gz.

• Login to the SSO Connect server.

• Run the Luna Client installer:

• Edit $JAVA_HOME/jre/lib/security/java.security

  a. find the list of security providers.

  b. add security.provider.10=com.safenetinc.luna.provider.LunaProvider.

  c. Save the file.

Configure Luna access

Requirements

1. the IP address or hostname of the HSM machine.

2. The admin password (also known as the Security Officer password).

3. A unique string, such as the IP address of your current machine, or your name, etc.

Verify that the HSM is configured

1. Start the Luna Client:

Configure Keeper SSO Connect for HSM access

In addition to the normal SSO Connect configuration questions there are some HSM-specific questions as shown below.

Troubleshooting

Troubleshooting the Configuration

1. Verify that the server is appropriate. CentOS 6 or 7 is preferred. We do not support Windows at this time.

2. Verify that the Luna client is correctly installed on the server. Run the Luna client and login as the Crypto Officer to verify that you can successfully login and display the contents of the partition.

3. Verify that Java 1.8 or Java 11 is available.

Troubleshooting the Operation

1. Check the log file for errors. The Secure Key Storage subsystem of SSOconnect will print an ERROR line to the log if it encounters a problem.

2. The error will be a variation of "Unable to use Secure Key Storage". This indicates one of the following problems:

Backup

The data folder contains the SSO Connect configuration files. At a minimum it should be backed up after initial configuration and each time the configuration is modified. In addition to the configuration files, there are data files in data but they will automatically be refreshed if they get out of synch with the Keeper server. Thus, regular periodic backups can be used but are not necessary. The data folder on each SSO Connect instance needs to be backed up independently because not all of the configuration settings are shared among instances.

On non-Windows machines the data folder is under the SSO Connect install folder, typically $HOME/sso_connect/data.

On Windows machines the data folder is in C:\ProgramData\Keeper SSO Connect\data\ since v14.1. Prior to v14.1 it was in C:\Program Files\Keeper Security\SSO Connect\data\.

Recovery

Server Failure

If the SSO Connect server dies you will need to reinstall Luna and SSO Connect on the replacement machine using the normal installation instructions above.

If you have backed up the data folder as described above, restore it before starting SSO Connect. If a data folder already exists (because you started SSO Connect), stop SSO Connect, remove all files in the data folder, copy the files from the backed-up data folder, and restart SSO Connect. SSO Connect should start successfully.

If you did not backup the data folder or if the backup is out-of-date you will need to configure the replacement instance as if it were a new installation. Please follow the SSO Connect installation guide.

HSM Failure

When using an HSM, the HSM stores the encryption key used to decrypt the configuration files in the data folder. The HSM is accessed once, when SSO Connect starts, and also any time the configuration is changed. If the configuration files are encrypted and the encryption key stored on the HSM is lost or inaccessible the SSO Connect instance will need to be configured again in order to create new, unencrypted configuration files. Delete the contents of the data folder and configure SSO Connect from scratch again.

You can disable HSM/SKS use by entering 'no' to the "Enable SKS?" configuration question, or by using the -disableSKS command-line option.

During installation, the SSO Connect service hangs and doesn't start.

Please ensure that you have a compatible Java version installed. See the System Requirements page for supported Java versions. Please note you may need to uninstall all existing Java installations before installing a compatible version.

How to make changes to my SSO Connect configuration to update the SSL certificate or IdP metadata?

Follow the steps outlined on the page of this guide.

We use ADFS, and our SSO Connect is down.

ADFS signing certificates typically are only valid for a year. ADFS may automatically rotate to the most current certificate. This breaks the trust between Keeper SSO Connect and ADFS. A new FederationMetadata.xml file will need to be generated and uploaded to the Keeper SSO Connect to ensure operation (). We strongly recommend setting a reminder before the expiration of the certificate so this step can be performed to maintain operation.

Our IdP is ADFS, when my users exit Keeper they receive a logout error:

To prevent a logout error, change the SAML Logout Endpoint URL

1. In your ADFS manager server, go to the Relying Party Trusts properties for Keeper SSO Connect.

2. Under the Endpoints tab, edit the SAML Logout Endpoints and set the URL to: https://<YourADFSserverDomain>/adfs/ls/?wa=wsignout1.0

What information needs to be secured on the SSO Connect server?

There is a "data" folder created when SSO Connect starts up. This data folder is located in C:\ProgramData\Keeper SSO Connect\ on windows, and in the installation folder on Linux.

Inside the data directory there are several files. It is critical that access to this data folder is restricted. You can add an extra layer of security by utilizing an HSM (Hardware Security Module) as described in this document. When an HSM is available, an encryption key is generated for each SSO Connect instance and stored securely in the HSM. The encryption key is used to encrypt the property files in the data/ folder.

How do we link users directly to the sign-in screen?

If you would like to send users a hyperlink directly to the SSO Login screen of the Web Vault, you can use the following format:

Replace xxxxx with the name of the Enterprise Domain that has been assigned in the Admin Console.

Why don't you just bind the SSO service to all interfaces rather than require me to provide an IP?

• The reason is that some customers have multi-homed servers and they do not want to bind to all interfaces for a number of reasons.

If an internal IP is required, why does SSO connect let me leave it blank?

• The internal IP is not required. You can leave it blank if the hostname resolves via DNS to the same external IP or even internal IP for Intranet. We have customers who use SSO strictly internally and the FQDN resolves to the internal IP. So that field can be left blank. It depends on your setup.

When I set up an HA SSO Connect server, or recover my SSO Connect server configuration from the cloud sync, the private IP address is not there.

This is by design. The Private IP is unique to the local instance of the SSO Connect. If the Private IP from "Server1" was sync'd and when "Server2" authenticated and sync'd the SSO Connect Config, it would have the incorrect IP from "Server1". For this reason the Private IP of the 1st (on any other) SSO Connect server is not retained.

When users authenticate via SSO they receive an error stating "invalid SAML response".

If nothing has changed in the IdP or within Keeper SSO Connect, the most likely culprit is the clock on the SSO Connect has changed and the system time is off by greater than 2 minutes. Older versions of SSO Connect will display this message when the time is off, but the latest version of SSO Connect will specifically give the error: "SAML Validation error: System time is off by > 2 min". It is recommended to have the SSO Connect Server clock to sync with NTP. Another potential cause of this error is if the metadata from the IdP is different than what is on the SSO Connect which causes the SAML certificates to be out of sync and there for untrusted.

Why can’t my non-SSO users change their master password?

• When SSO Connect is enabled on a node, all the users in the node and sub-nodes are under an enforcement to prevent the changing of their master password. This is done to prevent SSO users from bypassing authentication through the IdP.

I have invited a user; why can’t they create their vault via SSO Connect?

• When logging in for the first time the on-boarding process needs to occur on either the Web

  or the Desktop application. The Browser Extensions do not facilitate the on-boarding process

  of a new user, but will allow existing users to authenticate.

I am receiving the following error when a new user tries to connect for the first time: {“result_code”: ”does_not_exist”, ”message”: ”This user does not exist”}

• There are two possible reasons for this error. The invited user is not in an SSO enabled node within the Admin Console or the email address in the IdP doesn’t match the email address of the invited user. For the first issue, move the user into the SSO Enabled node and have them try again. For the second issue, verify the SSO account uses the same email address as the invited user. If they are different, a new account with the email address from the IdP will be created.

I'm getting an error on Linux about writing to /tmp. How do I resolve?

• On a Linux system /tmp must have exec privileges. If /tmp does not have exec privileges, execution of java -jar SSOConnect.jar

  may show an exception similar to: java.lang.UnsatisfiedLinkError: /tmp/sqlite...

  To resolve this, ensure that you have exec permission on /tmp with the command chmod a+x /tmp

Can users login in both ways: via SSO and natively?

• Enterprises can have some users configured to natively login and other users configured to use SSO, separated by Node. The Keeper Admin Console also has a role policy which can allow SSO users to also create a Master Password for logging in offline.

How do I convert a federated user to a local user or put another way, disable SSO access and have the user log in natively (username/master password)?

• In the admin console, move the user from the SSO enabled node to a node not under the enforcements of the SSO provisioning.

• After the move, the user must perform an account recovery (logging in natively with an incorrect password) clicking the ‘Forgot Password’ link. The user will receive an account recovery code to the email address listed on their Keeper account. After inputting the code, the user will be required to have the security question and answer configured at the inception of the vault creation process. This will allow them to create a new master password.

If my email address changes on the IdP, and I authenticate with SSO, what do I need to do within Keeper?

• Both the IdP and Keeper need to identify the same user based on their email address. So if email changes in one, but not the other, authentication will not work. It has to be a coordinated effort on both fronts.

• From the Keeper side, only the user can change their email address. (Ensure the user is not part of a role based enforcement preventing email changes.) To change the email address in Keeper, click on Settings > General > Email Address - Reset Now.

I can login via SSO into Keeper using Chrome, Firefox, and the Desktop application, but I can’t connect with IE. Why?

• IE has difficulty handling cross-domain redirects due to their multiple security zones. IE requires security zone settings to be configured in order to work properly with SSO. These security zone settings can be pushed out by the admin or manually configured if allowed. See the section on for settings.

After I install SSO Connect, the configuration page comes up with a "Can't reach this page" at http://127.0.0.1:8080/config/.

• If JRE has been installed and the server has been rebooted, this error is most like caused by a competing service like IIS listening to the port 8080. To alleviate the competition IIS can be uninstalled if not needed, or the port that SSO Connect uses for the configuration page can be changed.

• Stop the SSO Connect service if running

• Edit the instance.properties file located at:

• Change the port of the admin_port. (i.e. 8081)

• Restart the SSO Connect service and relaunch the admin page on the newly defined port. (i.e. http://127.0.0.1:8081/config/).

Where are the Keeper SSO Connect log files located?

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

• On Linux distributions, the logs are located with the sso_connect folder and varies depending on the base installation path:

What's the process for upgrading SSO Connect to the latest version?

• See the "" section of this document.

When my users log out of Keeper it logs them out of all SAML connected applications and the IdP.

To disable Single Logout (SLO), edit the IdP metadata file to remove the line found in the metadata that gets inputed into the Keeper SSO Connect Server: <md:SingleLogoutServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://your-sso_connect:8443/sso-connect/saml/slo"/>

And re-import the file to the SSO Connect server.

Getting blank white screen or error when logging into Desktop App

If you're receiving a blank white or error message on the dialog when logging into Keeper with SSO, this means that you probably used an invalid or self-signed SSL certificate in your Keeper SSO Connect configuration.

The Keeper Desktop application and several devices & web browsers do not like self-signed certificates and will produce an error to users. Please re-configure your Keeper SSO Connect instance to use a proper signed SSL certificate (either a wildcard cert or domain-specific certificate). The SSL certificate must be signed by a trusted public certificate authority that is recognized by Chrome, Safari and other browsers.

Getting confusing errors on the Web Vault when trying to login with SSO

If you're getting error messages like seen below.... it's likely that you are logged into Keeper in your Admin account or a different user account on another tab or window. If you are in the process of testing or setting up your SSO environment, it could get confusing if you're also logged into Keeper as the Admin.

To avoid these errors, we recommend logging into Keeper as the Admin using either another web browser (e.g. Firefox) or download the Keeper Desktop App and use that app while setting up your SSO environment.