Download the Keeper SSO Connect application from the Admin Console and stage the executable on the server.
Install Java 1.8 or Java 11 if not currently installed.
Download the SSL certificate file (
.jks) and your IDP's SAML XML metadata file.
Reboot the server [IMPORTANT]
Extract the Keeper SSO Connect app.
Run KeeperSSOConnect as administrator.
Upon successful completion of the new installation the app will launch a web browser. (We recommend using Google Chrome to perform the initial setup). If the configuration web page doesn’t launch you can launch it with the new SSO Connect Icon on the desktop.
If you receive an error connecting to the Keeper SSO Connect service, you need to reboot the server. Also, you need to ensure that your web browser is able to connect to keepersecurity.com over port 443. Keeper SSO Connect does not support the use of proxy servers or firewalls that perform SSL packet inspection.
Java 1.8 or Java 11 runtime environment.
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.
Outbound SSL port 443 opened to keepersecurity.com.
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.
FQDN assigned to the instance or to the load balancer.
SAML 2.0 compatible IdP.
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.
$ java -version
Create a dedicated folder to host the SSO Connect application:
$ mkdir sso_connect
Download the latest Keeper SSO Connect for Linux version from this link:
$ cd sso_connect$ wget https://keepersecurity.com/sso_connect/KeeperSso_java.zip$ unzip KeeperSso_java.zip
Then start the Keeper SSO Connect service:
$ java -jar SSOConnect.jar
Now that the application is installed, you can configure SSO using the web browser GUI or through the command line. Configuration options are discussed next.
By default, the configuration port of Keeper SSO Connect is port 8080. If you have local access to the target system, just open your web browser to:
To remotely configure SSO Connect through the web interface, simply open an SSH tunnel to the target system, for example: If you do not have direct browser access to the SSO Connect machine, you may be able to configure a tunnel to the machine:
$ ssh -L 9000:127.0.0.1:8080 email@example.com
Then open your web browser on your local system to:
Keeper SSO Connect can be started in configuration mode, which prompts you for the necessary parameters.
Stop the running SSOConnect process, if any, by hitting CTRL-C or killing the process.
Copy the SSL Certificate to the SSO Connect server. It must be in PKCS#12 or Java Keystore format, meaning a file ending with
Copy the IdP's SAML XML Metadata file to the server.
This is obtained from your IDP admin site (Active Directory, Azure, F5, Google, Okta, etc.).
This is usually an .xml file.
In the SSO Connect directory start SSO Connect in configuration mode:
$ java -jar SSOConnect.jar -config
You will be prompted to supply the following parameters:
Keeper Administrator email address (to login to the Keeper Admin Console for your company)
Keeper Administrator Master Password
Two-Factor code (if enabled on account)
SSO Domain Name (this attribute is defined on the SSO Connect provisioning screen on the Keeper Admin Console)
Note that each Domain configured in Keeper will require a separate SSO Connect installation.
Next you will be able to configure each individual parameter. Leave the setting blank (hit <Enter>) to accept the default setting.
SSO Connect External Hostname or IP Address
External SSL Port (default = 8443)
Local (private) IP
Local (private) Port
Use Certificates to decrypt and sign the saml response and requests (True/False)
SAML Attribute mapping for "First Name"
SAML Attribute mapping for "Last Name"
SAML Attribute mapping for "Email"
IdP Type (Google, Okta, Azure, etc...)
Key Store Password (if using Java Keystore)
PKCS#12 Passphrase (if using SSL Key)
Full path and name of Key File
Full path and name of IdP SAML Metadata file
The following questions relate to using an HSM (Hardware Security Module) for secure key storage. If you do not have an HSM or do not want SSO Connect to use one you can skip this section.
Configure Secure Key Storage (y/N):
Type of Secure Key Storage (Gemalto SafeNet Luna HSM):
Enter (AWS Cavium CloudHsmV2 is also supported)
Secure storage device access parameters (slot,password):
<your slot> (required for Gemalto, often 0 or 1)
******** (required for Gemalto, this is the Crypto Officer password on the HSM)
Certificate chain file (/home/ubuntu/keeperSSO/data/sso_keystore.jks):
Certificate chain file password (none):
Enable Secure Key Storage (Y/n):
Once the settings have been successfully implemented, they will sync to all other SSO Connect services upon restart of the service on each instance. Once the settings are sufficient for SSO Connect to start up and contact the Keeper server, the settings will sync to all other SSO Connect instances on the same domain when they are restarted.
SSO Connect will not automatically start after a configuration session so you need to start it:
$ java -jar SSOConnect.jar
SSO Connect supports many command-line options that can be scripted to automate operations such as rotation of SSL keys.
For a full list of command line parameter options, use the "-h" flag:
$ java -jar SSOConnect.jar -hUsage: java -jar path\_to\_jars/SSOConnect.jar \[option \[option\_argument\]\]\[option \[option\_argument\]\]\[...\]
-h or -help
Display this help text.
-c or -config
Configure SSOConnect via prompts.
-v or -version
Output the version.
-l or -list
Output the configuration to the console.
-d or -debug
Output the class path and other information to the console for trouble shooting.
-s or -sync
Performs a full sync. System must already be initialized.
SSOConnect can also be configured via the following command line switches.
Username of admin who can configure this instance of SSO Connect
Keeper Master Password
Two factor token
SSO name to initialize the instance to.
turn on Secure Key Storage (e.g. a Hardware Security Module)
turn off Secure Key Storage (e.g. a Hardware Security Module)
Export the SSOConnect Service Provider XML to the file name supplied as the argument. Instance must already be initialized.
Public / advertised FQDN (fully qualified domain name)
Public / advertised SSO Connect port
IP Address to bind ssl service to (if not supplied will default to the resolved ip of sso_connect_host)
Port to bind ssl service to (if not supplied use sso_ssl_port)
Either jks or p12
Password for the keystore
Password for each key in the keystore
The value can be “rsa” or “ec” (case-insensitive)
Location of the ssl file to convert
Location of the saml file
True if all incoming and outgoing traffic are signed
The number corresponding to the desired IDP: 0 Default, 1 F5 Networks BIG-IP, 2 Google, 3 Okta, 4 Microsoft ADFS, 5 Microsoft Azure, 6 OneLogin
Field the IDP sends the user's first name as
Field the IDP sends the user's last name as
Field the IDP sends the user's email as
Http port for 127.0.0.1 the administrative configuration web server runs on. Note: this value is per instance. To disable the configuration web server for a given machine, simply set this to 0.
For example, to rotate the SSL key of a running environment, the command will look something like this:
$ java -jar SSOConnect.jar -key_store_type p12 -key_store_password XXX -key_password XXX -ssl_file /path/to/sslfile -saml_file /path/to/samlfile -username firstname.lastname@example.org -password masterpass -twofactor 123456
You will be prompted to supply passwords through the interactive shell if left unset.
After you configure an instance, the changes will be immediately pushed to all other SSO Connect instances in your HA environment.
SSOConnect will uses the standard log4j2 libraries as its logger. It will look for the configuration file in the following order:
Value of the system environment variable 'logging.config'
log4j2.xml in the current working directory
log4j2.xml in the directory the SSOConnect.jar file is in
a log4j2 configuration file according to the standard log4j2 search criteria
the default log4j2.xml included inside the SSOConnect.jar file
Modifying the log4j2.xml file will only take affect after the service is restarted and only if it is the first log4j2 configuration file found.
Once your server is setup and operational you should setup SSO Connect as a service. This operation will vary depending on your OS.
If the application is still running because you configured it with the web interface, stop the running instance by entering ctrl-c.
As the root ueser, create a system startup file
/etc/systemd/system/ssoconnect.service with the following content:
[Unit]Description=SSO Connect Java Daemon[Service]WorkingDirectory=/home/<user>/sso_connectUser=<user>ExecStart=/usr/bin/java -jar /home/<user>/sso_connect/SSOConnect.jar /home/<user>/sso_connect[Install]WantedBy=multi-user.target
"Chmod" the file:
sudo chmod 644 /etc/systemd/system/ssoconnect.service
Run systemctl to start the service
$ systemctl status ssoconnect$ systemctl start ssoconnect$ systemctl status ssoconnect
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:
For most installations, this will be:
$ curl https://<public\_ip>:<port>/ping
You can review log files which are located by default in
working_directory/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.
In the SSO Connect installation folder is a
data/ directory. Inside the data directory 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.
You can add an extra layer of security by utilizing an HSM (Hardware Security Module) as described later 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 critical property files in the
into the SSO Connect Web UI with a Keeper Administrator account.
The Administrator account should not be configured for Single Sign-On.
Enter a Two Factor Authentication code if prompted.
Select the SSO Connection (Enterprise Domain).
Once you successfully authenticate Keeper SSO Connect to your Admin Console you will see the status tab:
Select on the Configuration link to begin the setup.
Enter the Advertised Hostname or IP Address. This address is what the Keeper client applications navigate to in order to initiate the SSO authentication process. If installing Keeper SSO Connect in an HA (High Availability) configuration, this is the address the that points to the load balancer. This address can be either an IP or a hostname.
Bound IP Address. This is the physical IP address of the NIC on the server. If a hostname is not used and if there is only one address associated with the server this entry will be the same as the Hostname or IP Address field.
In the sso-1.test-keeper.com is the Advertised Hostname that gets routed to the local address 10.1.0.4. The Keeper SSO Connect service binds to the Private IP address.
The IP/Hostname must be accessible by users who will be accessing Keeper. You may need to update your firewall to allow access over the IP and port.
The Keeper SSO Connect service requires an SSL Certificate. A self-signed certificate can be used but before deploying to production we recommend that a proper SSL Certificate from your certificate authority be generated and uploaded to this section. Self-signed certificates will generate security errors for your users on many browsers.
The certificate file type must be
.p12 for a PKCS 12 certificate or
.jks for a Java Key Store certificate. Most Certificate Authorities have instructions on their sites on how to convert to these file type if they did not initially issue these specific formats.
Select your specific IDP. If your IDP is not in the pull-down menu, select Default.
Select your IdP Provider. If your provider is not listed select Default.
The next step is to upload the IdP SAML metadata file. This file can be downloaded from your IdP.
Attribute Mappings do not require any changes. Select Save.
Reasons the Status might be listed as Stopped:
Your SSL Certificate is missing or incorrect.
The hostname in the SSL certificate doesn’t match the hostname in SSO Connect. A wildcard SSL certificate can be used or you can use a certificate created for the specific hostname. (i.e. if your hostname is Keeper.DOMAIN.com your cert should be set up for *.DOMAIN.com).
By default the Use Certificate to Decrypt and Sign SAML Response/Request should be selected.
See the Appendix on creating a self-signed SSL cert if you need to create one for testing or troubleshooting your SSL certificate.
The Keeper SSO Connect runs as a service on Windows. Closing out the web interface does not stop the service. The service can be stopped and started from the Service MMC in windows.
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 synch 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.
On non-Windows machines the
data folder is under the SSO Connect install folder, typically
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\.
If the SSO Connect server dies you will need to reinstall SSO Connect on the replacement machine using the normal installation instructions.
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.
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 steps in the Installation section.