Keeper SSO Connect On-Prem / Customer Hosted Version
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.
For customers looking for a 100% cloud-based integration, see Keeper SSO Connect Cloud
We recommend all new customers implement Keeper SSO Connect Cloud
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.
SSO Connect On-Prem Overview
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.
Note: Keeper SSO Connect On-Prem can be installed on any instance or environment under the control of the Keeper Enterprise customer, to preserve zero-knowledge encryption.
On Microsoft Windows environments, the Keeper SSO Connect application runs as a standard Windows service. This ensures the service won't exit when anyone logs off the PC and will automatically start up upon reboot. On all platforms SSO Connect can be configured for High Availability (HA). In order to ensure the service is always active, Keeper SSO connect can be installed on multiple servers that are located behind a load balancer.
System Requirements for Keeper SSO Connect service
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.
The following server platforms are currently supported:
Supported Windows Server Versions Windows Server 2016 Datacenter Windows Server 2016 Standard Windows Server 2019 Standard Windows Server 2019 Datacenter Windows Server 2022 Standard Windows Server 2022 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+
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.
Keeper SSO Connect requires at least Java 11. You can obtain Java 11 from OpenJDK or Amazon Corretto. OpenJDK project: https://github.com/ojdkbuild/ojdkbuild Amazon Corretto: https://aws.amazon.com/corretto Note: Reboot is required after Java 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
.
In the Edit System Variable (or New System Variable) window, specify the value of the PATH
environment variable. Click OK. Close all remaining windows by clicking OK.
The following table outlines the minimum hardware requirements per each server.
Max # of users per server
Processor speed (GHz)
Number of processors / Cores
Memory (GB)
Disk (GB)
1-1,000
3
1 / 4
2
40
1,000 - 50,000
3
2 / 4
8
40
50,000 - 100,000
4
2 / 8
16
40
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.
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:
Vendor
Model
Version
Notes
Amazon
CloudHsm
v2
Linux or Windows servers are supported.
Gemalto
Luna 7
6.2+
Currently only Linux-based SSO Connect instances supported.
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).
The external advertised TCP port that is configured in SSO Connect (default TCP/8443) needs to be allowed inbound into the network subnet where the SSO Connect servers are located. For example if the service is running on Windows, use Windows Firewall to open the port to SSO Connect. 8443 is just the default, you can use any port.
Steps to install and set up Keeper SSO Connect
The basic steps for setting up Keeper SSO Connect are listed in the steps below. Detailed instructions are annotated further in this guide.
In order to successfully complete the SSO Connect setup in the fastest possible time, please have the below items prepared:
Access to a Windows or Linux instance to run the service
Access to either a wildcard SSL certificate or ability to generate a new SSL cert for the endpoint (e.g. sso.mycompany.com)
Ability to configure https browser traffic from the end-user's browser to the service
Access to the Keeper Admin Console web interface
At least one non-sso admin user with Bridge/SSO Admin Permissions is require to log into the the SSO Connect server.
Once you have met the pre-requisites above, the setup steps are as follows:
Enable SSO Connect from the Keeper Admin Console
Install Keeper SSO Connect on your server (any cloud or on-prem Windows/Linux instance)
Configure Keeper SSO Connect with the Identity Provider
Setting up your Keeper Admin Console for SSO integration
Visit the Keeper Admin Console and login as the Keeper Administrator
US Data Center: https://keepersecurity.com/console
US Public Sector / GovCloud: https://govcloud.keepersecurity.us/console
EU Data Center: https://keepersecurity.eu/console AU Data Center: https://keepersecurity.com.au/console CA Data Center: https://keepersecurity.ca/console
JP Data Center: https://keepersecurity.jp/console
SSO integration is applied to specific nodes (e.g. organizational units) within your Admin Console outside of the root node. Since the SSO provisioning can not be added to the root node a new node will need to be added in order to support SSO authentication.
Click on the 'Admin' menu tab. By default the node structure is displayed to the right of the menu.
On the root node (the top level node with the organization name displayed) click on the three dots and select the '+ Add Node' button to create a new node which will host the Keeper SSO Connect integration to the IdP. The node can be anywhere in your tree structure.
Organizations with multiple IdP's can have each one associated with a different node. For example if one subset of users authenticates to Azure and another group of users authenticate with Okta each IdP can be enabled on different nodes. Users will only be able to be associated with one IdP.
Select the Provisioning tab of the node.
Next, select + Add Method link to create a new connection.
There are 2 parameters to configure. The Enterprise Domain and the New User Provisioning option.
Every SSO Connection must be uniquely identified through the use of an arbitrary Enterprise Domain name. This name should be something that is easy for your users to remember (e.g. my_company) because they may need to type the name into their mobile device and apps (iOS, Android, Mac, Windows) upon first logging into a new device.
Users can be dynamically provisioned to your Keeper Business account upon first successful authentication on SSO (Just-In-Time provisioning). For the best user experience, we recommend selecting this option. You can also manually invite users through the Admin Console Users tab, or invite users via the Keeper Bridge.
After configuring the Enterprise Domain and New User Provisioning select Save.
At this point, you can now configure the Keeper SSO Connect application.
If you are planning to use the Keeper Bridge for provisioning users instead of Just-In-Time SSO provisioning, please leave this option disabled.
Users who authenticate to Keeper via SSO Connect will need the ability to communicate with SSO Connect instance(s) over the configured FQDN and port. We recommend the following security controls:
Utilize Keeper's IP Allowlisting features of the role enforcement settings to restrict vault access to approved networks. This can be found in Role > Enforcement Policies > Allow IP List.
Apply firewall and access policies to SSO Connect instance(s) to trusted networks.
Install and configuration of Keeper SSO Connect on Windows Server environments.
As described in the System Requirements 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.
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.
You can obtain an SSL certificate from your web hosting company, or you can utilize one of the no-cost options available such as ZeroSSL. You can also have more control over the steps by using OpenSSL.
OpenSSL for Windows - https://slproweb.com/products/Win32OpenSSL.html
You can use the latest "Win32 OpenSSL Light" version.
To get the download link, in the Keeper admin console under provisioning (in your SSO node), add method "SSO Connect On-Prem".
After adding the provisioning, you will see a button to download Keeper SSO Connect.
Copy the downloaded file to the SSO Connect server.
Installation of SSO Connect requires the creation of an SSL certificate file that is utilized for the endpoint. Generate the SSL certificate and download the SSL certificate file (.pfx
, .p12
, or .jks
) and your IDP's SAML XML metadata file to the server.
Extract the Keeper SSO Connect installer file.
Run KeeperSSOConnect as Administrator.
The new desktop icon "Keeper SSO Connect" will launch a browser for configuration (we recommend using Google Chrome to perform the initial setup).
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.
Login to the SSO Connect Web UI, with a Keeper Administrator Master Password account, by navigating to http://127.0.0.1:8080/config or by utilizing the Keeper SSO Connect Desktop Icon.
In order to successfully login to the SSO Connect Web UI, you must utilize a Keeper Administrator account in which meet several requirements:
The account MUST be a Master Password Authentication account.
The account can not live within the SSO provisioning node.
The account must be in an Administrative Role in which has Manage Bridge/SSO permissions over the node.
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 example above, "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. It is recommend to use a proper SSL Certificate signed by a Certificate Authority (CA). The SSL cert can be one generated specifically for the SSO Connect server (hostname or IP address) or a wild card certificate that matches your domain (*.yourcompany.com).
Self-signed certificates will generate security errors for your users on most browsers and mobile devices.
The certificate file type must be .pfx
or .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.
For assistance in generating a SSL certificate, please refer to the section on Creating a Certificate.
Note: SSL Certificates may expire annually or quarterly. Please set a reminder to renew your certificate prior to the expiration date to prevent unexpected outages.
For SSO Connect version prior to 14.1.0 please enter the password in both fields
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.
Initial installation of Keeper SSO Connect on a Linux instance
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.
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.
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.
Setup of Keeper SSO Connect on a Linux instance via the graphical 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.
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:
Then open your web browser on your local system to:
Login with your Keeper Administrator Email address and Master Password and your multi-factor authentication if enabled.
You will be prompted to select the identity provider set up in the Admin Console (from the previous "Admin Console Configuration" step)
Then you will be ready to configure the SSO Connection instance.
Click on "Configuration" to configure the specific Identity Provider.
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 example above, "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.
In the example above, "sso2.lurey.com" is the Advertised Hostname that gets routed to the local address 10.0.229.63. 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.
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 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.
The Keeper SSO Connect service requires an SSL Certificate. It is recommend to use a proper SSL Certificate signed by a Certificate Authority (CA). The SSL cert can be one generated specifically for the SSO Connect server (hostname or IP address) or a wild card certificate that matches your domain (*.yourcompany.com).
Self-signed certificates will generate security errors for your users on most browsers and mobile devices.
The certificate file type must be .pfx
or .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.
For assistance in generating a SSL certificate, please refer to the section on Creating a Certificate.
Note: SSL Certificates may expire annually. Please set a reminder to renew your certificate prior to the expiration date to prevent unexpected outages.
Select your specific IDP. If your IDP is not in the pull-down menu, select Default.
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 identity provider. The specific steps in setting up the identity provider are in the next section ("Identity Provider Setup").
Attribute Mappings do not require any changes. Select Save.
After you click Save, the service will start up after a few seconds and the "Status" screen will display the server status information.
The Status might be listed as Stopped. If this happens, please check the following:
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.
To set up SSO Connect as a service, please visit this section.
Configuration on Linux without a GUI
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 Identity Provider Setup section.
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 .pfx
, .p12
, or .jks
.
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): Enter
slot: <your slot>
(required for Gemalto, often 0 or 1)
password: ********
(required for Gemalto, this is the Crypto Officer password on the HSM)
Certificate chain file (/home/ubuntu/keeperSSO/data/sso_keystore.jks): Enter
(required)
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.
Note: JKS Keystore type may require both Key Store and Passphrase to be the same
SSO Connect will not automatically start after a configuration session so you need to start it:
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:
Option
Description
-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.
Setting
Argument
Description
-username
string
Username of admin who can configure this instance of SSO Connect
-password
string
Keeper Master Password
-twofactor
string
Two factor token
-initialize
string
SSO name to initialize the instance to.
-enableSKS
none
turn on Secure Key Storage (e.g. a Hardware Security Module)
-disableSKS
none
turn off Secure Key Storage (e.g. a Hardware Security Module)
Note: if the instance is already initialized, you cannot re-initialize without deleting the contents in the data directory
numberSetting
Argument
Description
-export
string
Export the SSOConnect Service Provider XML to the file name supplied as the argument. Instance must already be initialized.
-sso_connect_host
string
Public / advertised FQDN (fully qualified domain name)
-sso_ssl_port
number
Public / advertised SSO Connect port
-private_ip
string
IP Address to bind ssl service to (if not supplied will default to the resolved ip of sso_connect_host)
-private_port
number
Port to bind ssl service to (if not supplied use sso_ssl_port)
-key_store_type
string
Either jks or p12
-key_store_password
string
Password for the keystore
-key_password
string
Password for each key in the keystore
-key_type
string
The value can be “rsa” or “ec” (case-insensitive)
-ssl_file
path
Location of the ssl file to convert
-saml_file
path
Location of the saml file
-sign_idp_traffic
boolean
True if all incoming and outgoing traffic are signed
-idp_type
number
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
-map_first_name
string
Field the IDP sends the user's first name as
-map_last_name
string
Field the IDP sends the user's last name as
-map_email
string
Field the IDP sends the user's email as
-admin_port
number
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.
Command-line options require username, password, and two-factor values (if 2FA is enabled). Either set them as an option or you will be prompted for them.
For example, to rotate the SSL key of a running environment, the command will look something like this:
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.
Setting up a service on Linux
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 on the command line by entering CTRL-C.
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.
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.
Configuration of SSO Connect On-Prem with popular IdP platforms
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!)
How to configure Keeper SSO Connect On-Prem with Microsoft AD FS for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with AD FS, see Keeper SSO Connect Cloud
Inside the AD FS Management application, locate the Federation Metadata xml file. This can be found by clicking on AD FS > Service > Endpoints then locate the URL path in the "Metadata" section. The path is typically /FederationMetadata/2007-06/FederationMetadata.xml as seen below:
To download the metadata file, this can typically be found by loading the URL in the browser on the server. For example: https://<your hostname>/FederationMetadata/2007-06/FederationMetadata.xml Download this file and save to the computer.
Import the FederationMetadata.xml file into Keeper SSO Connect’s configuration screen by dragging and dropping the file:
Select Save to save the configuration.
Please Note: 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.
Select the Export Metadata link on Keeper SSO Connect and copy the sso_connect.xml file to your IdP.
Create Keeper SSO Connect as a Relying Trust Party:
Import the Keeper Metadata that was exported previously from Keeper SSO Connect by completing the Relying Party Trust Wizard as seen in the steps below:
To prevent a logout error, change the SAML Logout Endpoints on the Relying Party Trust to: https://<YourADFSserverDomain>/adfs/ls/?wa=wsignout1.0
To map attributes between AD FS and Keeper, you need to create a Claim Issuance Policy with Send LDAP Attributes as Claims and map the LDAP attributes to Keeper Connect attributes.
Important: Ensure that 3 attributes ("First", "Last" and "Email") are configured with the exact spelling as seen above.
For Logout support we need to add two more Claim Issuance Policy rules:
To copy the syntax to add in the claims rule, copy the following text and paste it into the custom rule:
Incoming claim type: http://mycompany/internal/sessionid
Should I put my company's name in there? No, actually literally put "http://mycompany/internal/sessionid"
Outgoing claim type: Name ID Outgoing name ID format: Transient Identifier
a. Open Powershell as Administrator on the AD FS server. b. Identify your SSO Connect Relying Party Trust "Identifier" string which you can obtain by running:
Running this command will generate a long list of output, you are looking for the SSO Connect section and the "Identifier" string. This string will look something like: https://xyx.company.com:8443/sso-connect
c. Run the below command, replacing <Identifier> with the string found in step (b).
If you run Get-ADFSRelyingPartyTrust again, you'll see that the SamlResponseSignature section is set to "MessageAndAssertion".
From the services manager, restart AD FS service.
SAML assertion signing must be configured properly on your AD FS environment. If signing has not been configured, you will need to set this up, then exchange metadata again between AD FS and Keeper SSO Connect after the re-configuration.
If after setting up Keeper SSO Connect user gets SSO is not configured (undefined) a possible root cause is missing or incorrect CRL configuration. A simple fix/workaround is to disable all Certificate Revocation Check.
Possible Root Causes Time skew Ensure that Keeper Connect and the IdP have the same identical system time (within 1 second). Set ntp sync PS C:\Windows\system32>w32tm /config /syncfromflags:manual /manualpeerlist:0.pool.ntp.org,1.pool.ntp.org,2.pool.ntp.org,3.pool.ntp.org,0x8 /reliable:yes /update Certificate Validation Failure
Verify the settings. Run a PowerShell as Administrator and look at ADFSRelyingPartyTrust
Follow the "SAML Signing Configuration" instructions above
If you need to disable certificate validation on the IdP for testing purposes or for internal PKI certificates, you can use the below Powershell commands. Replace <Identifier> with the string found in the "SAML Signing Configuration" instructions above.
Note: Any changes made to signing configuration may require exchange of XML metadata between IdP and SSO Connect.
How to configure Keeper SSO Connect On-Prem with Microsoft Entra ID / Azure AD for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with Azure, see Keeper SSO Connect Cloud
Go to your Azure Admin account at https://portal.azure.com 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:
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.
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.
In your environment, if your user.userprincipalname (UPN) is not the same as the users actual email address, you can edit the Email claim and change it to user.mail as the value for the Email attribute.
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.
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 file saved in the previous step into Keeper SSO Connect’s configuration screen by dragging and dropping the file into the SAML Metadata section.
Don’t forget to select Azure as the Identity Provider Type.
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!
How to configure Keeper SSO Connect On-Prem with Amazon AWS SSO for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with AWS, see Keeper SSO Connect Cloud
Log into AWS and select on AWS Single Sign-On.
On the SSO Dashboard, select Configure SSO access to your cloud applications.
On the Applications menu, select Add a new application.
Next select Keeper Security and select Add.**
Keeper is working with AWS to develop an Application Connector.
Fill in the Display name and Description (optional) in the application details section.
In the AWS SSO metadata section, select the download button to export the AWS SSO SAML metadata file. This file gets imported in the SSO Connect IdP Metadata section on the configuration screen.
Copy this file to the Keeper SSO Connect server and upload it into the Keeper SSO Connect interface by dragging and dropping the file into the Configuration screen: Select Save.
The remaining step on the Keeper SSO Connect Server is to download the Keeper sso_connect.xml metadata file and upload it to the AWS application. Select Export Metadata on the Keeper SSO Connect.
Import the sso_connect.xml file to the Application metadata section on the application configuration screen.
After saving changes the Configuration for Keeper Password Manager has been saved success message will be displayed.
Note: The Keeper SSL certificate cannot be larger than 2048K or the below error will be received.
Either, generate a smaller SSL certificate, re-export and import the metadata file or manually set the ACS URL and Audience URL in the AWS SSO application configuration.
Next, Ensure the Keeper application attributes that are to be mapped to AWS SSO are correct (These should be set by default. Select the Attribute mappings tab. The AWS string value to ${user:subject} and format is blank or unspecified. The Keeper Attributes are set as follows:
Keeper Attribute
AWS SSO String Value **
Format
${user:email}
unspecified
First
${user:givenName}
unspecified
Last
${user:familyName}
unspecified
Note: If your AWS email is mapped to the AD UPN (which may not be the actual email address of your users) it can be re-mapped to the email address associated in the users AD profile.
To make this change navigate to the Connect Directory on the AWS SSO page.
Select on the Edit attribute mappings button.
Change the AWS SSO email attribute from ${dir:windowsUpn} to ${dir:email} .
Select on the the Assigned users tab and then the Assign users button to select users or groups to assign the application.
On the Assign Users window:
Select either Groups or Users
Type the name of a group or user
Select on the Search connect directory to initiate the search.
The results of the directory search will display under the search window.
Select the users/groups that are desired to have access to the application and then select the Assign users button.
Note: Keeper SSO Connect expects that the SAML response is signed. Ensure that your identity provider is configured to sign SAML responses.
Your Keeper SSO Connect setup is now complete!
How to configure Keeper SSO Connect On-Prem with Centrify for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with Centrify, see Keeper SSO Connect Cloud
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!
How to configure Keeper SSO Connect On-Prem with F5 BIG-IP APM for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with F5, see Keeper SSO Connect Cloud
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!
How to configure Keeper SSO Connect On-Prem with Google for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with Google Workspace, see Keeper SSO Connect Cloud
G Suite supports the following integration with Keeper:
SSO authentication with SAML 2.0
Automatic Provisioning with SCIM
You can configure SSO, SSO+SCIM or SCIM without SSO.
To access G Suite Admin Console, login to https://gsuite.google.com.
Visit the Apps screen.
Click on SAML apps
On the lower right click on the ( + ) button to create a SAML app.
Search for Keeper and select the application.
On the Google IdP Information screen, download the IDP metadata and save it to your computer (Note: this is the file you need to drag & drop into the Keeper SSO Connect screen).
On the Service Provider Details screen, there are a few fields to fill out. You will replace the {host name] and {port} with the values that you'll be using from your SSO Connect instance.
Type in the ACS URL, Entity ID and select "Signed Response". For example, in the setup below, sso2.lurey.com is the host name and 8443 is the port.
You must also check the box for "Signed Response".
In the Attribute Mapping screen, ensure that there are 3 mappings exactly as they appear below. Set the First, Last and Email fields to "First Name", "Last Name" and "Primary Email" as displayed below.
If you have selected a Custom App, you'll need to click on "Add New Mapping" to create the 3 fields: First, Last and Email. The spelling needs to be exact.
Select on FINISH and your G Suite setup is complete. You will be informed that you still need to import the IDP data on Keeper SSO Connect.
To enable Keeper SSO Connect, for your users, select the more button and enable:
Alternatively, you can click on the Keeper SAML app and Edit the service to configure specific groups that have access:
Back on the Keeper SSO Connect application configuration screen, drag-and-drop the metadata file into the SAML Metadata section of Keeper SSO Connect:
Select on Save and verify that all of the parameters match your G Suite SAML connection screens.
Once you save, assuming that you have already configured the SSL certificate and other parameters, your Keeper SSO Connect instance should show as fully operational in the Status screen:
As of right now, G Suite does not support "Single Logout" at the application level. This means that users who explicitly Log Out of Keeper will also be logged out from their other Google services. Single Logout (SLO) is a feature of many identity providers which will logout the user from the specific application. Unfortunately Google doesn't support this yet.
If you want to prevent full SAML Logout from all SAML apps you should change the IDP type in the previous step to Default. Don't set it to Google, which will log you out of Gmail and all other Google apps on SAML Logout.
If you prefer that clicking "Logout" from Keeper does not log you out of Google, then simply change the SSO Connect configuration to select the "Default" provider instead of Google in the drop-down. However you should be aware of the consequences from a security perspective:
Keeper's session will be logged out, however logging back into the vault will not prompt the user to re-enter their Google login credentials while the browser's Google session is still active.
From a user perspective this is a more friendly, less disruptive flow
From a security perspective, be aware the Google account therefore controls the session handling of the Keeper vault on that user's browser.
Your Keeper SSO Connect setup with G Suite is now complete! Users can now login into Keeper using their Google account by following the below steps:
Open the Keeper vault and click on "Enterprise SSO Login".
Type in the Enterprise Domain that was provided to the Keeper Admin Console when setting up SSO. On the SSO Connect status screen it is called "SSO Connect Domain".
Click "Connect" and login with your G Suite credentials.
For the end-user experience (Keeper-initiated Login Flow) see the guide below: https://docs.keeper.io/user-guides/enterprise-end-user-setup-sso#keeper-initiated-login-flow
End-user Video Tour for SSO Users is here: https://vimeo.com/329680541
Next, we'll show how to configure User Provisioning using SCIM.
User Provisioning provides several features for lifecycle management:
New users added to G Suite will be sent an email invitation to set up their Keeper vault
Users can be assigned to Keeper on a user or team basis
When a user is de-provisioned, their Keeper account will be automatically locked
Note: Google does not support Group provisioning to Keeper teams. When they implement this feature, this will allow the Keeper user to be placed into Teams that are synchronized between G Suite and Keeper.
From the Keeper Admin Console, go to the Provisioning tab for the G Suite node and click Add Method.
Select SCIM and click Next.
Click on "Create Provisioning Token"
The URL and Token displayed on the next screen will be provided to Google in the G Suite Admin Console. Save the URL and Token in a file somewhere temporarily and then click Save.
Make sure to save these two parameters (URL and Token) and then click Save or else provisioning will fail.
Back on the G Suite admin console, go to Home > Apps > SAML Apps and click on the "Provisioning Available" text of the Keeper app you set up.
Click on Set Up User Provisioning
Paste the provisioning token that was saved above into this next screen and click Next.
Paste the URL saved from above and paste into the endpoint URL field and click Next.
Leave the Map attributes to default settings and click Next.
If you would like to assign Keeper to a specific group, you can set the Provisioning Scope in the next screen. If you are using SSO, ensure that the groups with provisioning access are also assigned Keeper SSO access. Click Finish when complete.
Ignore this error message below, it's a Google bug.
Next, you can activate provisioning.
You may need to click "Activate Provisioning" to turn it on.
User Provisioning will display as ON.
User provisioning setup is complete. Moving forward, new users who have been configured to use Keeper in G Suite and are within the provisioning scope definitions will receive invites to Keeper and be under the control of G Suite.
If you would like to provision users to Keeper via G Suite SCIM provisioning, but you do NOT want to authenticate users via SSO, please follow the below instructions:
Using this guide, follow the steps of SSO configuration but use SSO url and Entity ID that point to a domain name which you control, but is not actually a live SSO Connect instance (e.g. null.mycompany.com)
Once Keeper application is set up in G Suite, turn on the automated provisioning method as described in this document.
Google's IdP x.509 certificates for signing SAML assertions are set to expire after 5 years. In the Google Workspace "Manage Certificates" section, you should make note of the expiration and ensure to set a calendar alert in the future to prevent an outage.
When the certificate is expiring soon, or if the certificate has expired, you can follow the instructions below.
Login to Google Workspace Admin Console: https://admin.Google.com
Click on Apps then select Web and Mobile Apps.
Select Keeper app
Expand service provider
Click “Manage Certificates”
Click “ADD CERTIFICATE”
Click “DOWNLOAD METADATA”
Save the metadata file. This is the IdP metadata.
Login to the Keeper Admin Console
Navigate to Admin > SSO Node > Provisioning > Edit SSO Cloud provisioning method
Upload the Google IdP metadata into Keeper
For more information on this topic, see Google's support page:
How to configure Keeper SSO Connect On-Prem with JumpCloud for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with JumpCloud, see Keeper SSO Connect Cloud
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:
https://jumpcloud.com/configure/keeper-and-sso-configuration/
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!
JumpCloud® supports Automated Provisioning with SCIM (System for Cross Domain Identity Management) which will update and deactivate Keeper user accounts as changes are made in JumpCloud®. Step-by-Step instructions can be found here, https://docs.keeper.io/enterprise-guide/user-and-team-provisioning/jumpcloud-provisioning-with-scim
How to configure Keeper SSO Connect On-Prem with Okta for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with Okta, see Keeper SSO Connect Cloud
Login to the Admin section of the Okta portal.
Select Admin
Select the Applications tab and select Applications.
Next, select the Add Application button.
In the application search field, type Keeper Password, and then select the Add button for the Keeper Password Manager and Digital Vault Application.
On the General Settings page, Enter the Entity ID from your Keeper SSO Connect server: (i.e. https://DOMAIN:8443/sso-connect where DOMAIN is the server name or IP address of your Keeper SSO Connect application ). Then select the Done button.
Add users or groups on the Assignments page. (This step can be skipped and returned to after setup is complete.)-
Next, select the Sign On tab.
Select the Edit button.
Next, check the Enable Single Logout setting and choose a certificate to upload.
This can be generated by following the Okta instructions.
After selecting upload the certificate file (.crt) for the Keeper SSO Connect SSL instance endpoint.
After the file is successfully uploaded, select save at the bottom of the Sign On page.
The setting will be saved.
Scroll down to the SAML 2.0 configuration section, download the Identity Provider metadata file. Rename the file to metadata.xml. This will be used in Step 8.
The View Setup Instructions link provides additional setup instructions many of which are also found within this document.
Upload metadata.xml 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!
To enable Okta SCIM user and group provisioning please follow the below guide:
How to configure Keeper SSO Connect On-Prem with OneLogin for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with OneLogin, see Keeper SSO Connect Cloud
Be sure to first perform the steps in the Admin Console Configuration section.
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.
How to configure Keeper SSO Connect On-Prem with Ping Identity for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with Ping, see Keeper SSO Connect Cloud
Login to the Ping Identity portal.
From the Ping Identity menu select Applications.
Then select Add Application and select New SAML Application.
On the Application Details page, add the following data:
Application Name: Keeper Password Manager Application Detail: Password Manager and Digital Vault Category: Compliance (or other) Graphic: Upload the Keeper Graphic http://s3.amazonaws.com/keeper-email-images/common/keeper256x256.png
Then select Continue to Next Step.
The next step is to download the SAML Metadata from Ping Identity. Select the Download link next to SAML Metadata.
The saml2-metadata-idp.xml file will download to the browser. Copy this file to the Keeper SSO Connect server and upload it into the Keeper SSO Connect interface by dragging and dropping the file into the Setup screen: Select Save.
The remaining step on the Keeper SSO Connect Server is to download the KeeperSsoMetadata.xml file and upload it to the Ping Application configuration Select Export Metadata on the Keeper SSO Connect.
Back on the Ping Identity application configuration, select the Select File button and choose the file KeeperSsoMetadata.xml.
Select Continue to Next Step.
The next step is the map the attributes. Select the Add new attribute button.
In attribute 1, type “First” in the Application Attribute column, select First Name in the Identity Bridge Attribute or Literal Value column, and check the Required button. Select the Add new attribute button.
In attribute 2, type "Last" in the Application Attribute column, select Last Name in the Identity Bridge Attribute or Literal Value column, and check the Required button. Select the Add new attribute button.
In attribute 3, type "Email" in the Application Attribute column, select Email in the Identity Bridge Attribute or Literal Value column, and check the Required button. Application Attributes: First, Last, Email must begin with a capital letter.
Select the Save & Publish button. Review the setup and and then select the Finish button.
The Keeper Application should be added and enabled.
Important Note: In the Application Configuration section of your Ping Identity setup, ensure that the "Signing" section has "Sign Response" selected with "RSA_SHA256" as the Signing Algorithm.
Your Keeper SSO Connect setup is now complete!
How to configure Keeper SSO Connect On-Prem with PingOne for seamless and secure SAML 2.0 authentication.
Login to the PingOne Admin portal https://admin.pingone.com/
From the PingOne console menu, select Applications > Application Catalog
Search "Keeper" and click on the "Keeper Password Manager - On-Prem SSO" link to add the Keeper Password Manager application
Click Setup to proceed to the next step
Click "Continue to Next Step"
On the Keeper SSO Connect Windows server, download the KeeperSsoMetadata.xml file and save it in a safe location.
Select Export Metadata on the Keeper SSO Connect.
Back on the PingOne application configuration, select the Select File button and choose the file KeeperSsoMetadata.xml.
Then click on Choose File next to "Primary Verification Certificate" and upload a valid SSL certificate file.
Click Continue to Next Step
Enter the appropriate values associated with each attribute (see below image) and click Continue to Next Step
Modify the Name to appropriately match the Configuration Name of the SSO node from the Keeper Admin Console. Click Continue to Next Step.
You may choose to add PingOne user groups to your application. Click Add next to the group or groups you would like to add and click Continue to Next Step.
PingOne users will have access to Keeper Password Manager by default. Assigning groups to Keeper Password Manager restricts access to only those groups.
Click Download next to "SAML Metadata" and save the .xml
file to a safe location.
Click Finish to complete the application setup wizard.
The saml2-metadata-idp.xml file will download to the browser. Copy this file to the Keeper SSO Connect server and upload it into the Keeper SSO Connect interface by dragging and dropping the file into the Setup screen: Select Save.
The Keeper Application should be added and enabled.
Important Note: In the Application Configuration section of your Ping Identity setup, ensure that the "Signing" section has "Sign Response" selected with "RSA_SHA256" as the Signing Algorithm.
Your Keeper SSO Connect setup is now complete!
How to configure Keeper SSO Connect On-Prem with RSA SecurID Access for seamless and secure SAML 2.0 authentication.
For a 100% cloud-based integration with RSA, see Keeper SSO Connect Cloud
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.
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.
Creating SSL Certificates on Windows for Keeper SSO Connect On-Prem
You can obtain a quick, easy, and free SSL certificate at ZeroSSL. Or if you prefer to have more control over each step of the process, you can proceed with the following instructions.
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.
(1) Download and install OpenSSL version 1.1.1.
Version 3.0 of OpenSSL appears to have compatibility issues with Java 11, so we are recommending to use version 1.1.1 for now. For convenience, a 3rd party (slproweb.com) has created a binary installer. A popular binary installer is linked below:
https://slproweb.com/download/Win32OpenSSL_Light-3_1_4.exe
During install, the default options can be selected. In the install process, you may be asked to also install a Microsoft Visual Studio extension. Go ahead and follow the instructions to install this extension before completing the OpenSSL setup.
(2) Run the OpenSSL Command Prompt
In your Start Menu there will be an OpenSSL folder. Click on the OpenSSL Command Prompt.
(3) Create a Private Key
On the OpenSSL Command Prompt, run the below command to create a private key.
(4) Generate a CSR
Create a CSR, making sure to use the hostname which you plan to use for SSO Connect. In this case, we will be using keeper.mycompany.com. The important item here is that the Common Name matches exactly to the domain.
Example:
(5) Purchase an SSL certificate
Submit the CSR to your SSL certificate provider. If you don't have one, we recommend using a basic HTTPS cert from https://ssls.com.
Follow your vendor’s instructions for completing the certificate request. You will then need to wait for your certificate to be issued by your SSL Certificate provider. This can take anywhere between 5 minutes and 24 hours -- check with your vendor regarding their turnaround time.
The SSL certificate provider will deliver you a zip file that contains a signed certificate (.crt file) and intermediate CA cert (.ca-bundle). Unzip this file into the same location as the private key.
(6) Create .pfx File
After the certificate has been issued, it needs to be converted to .pfx
format. From the OpenSSL Command Prompt in the same folder as the .key
, .crt
and .ca-bundle
file, run the below command.
In this example...
keeper.mycompany.com.key
is the private key generated in step 1.
keeper.mycompany.com.crt
is the signed certificate delivered in step 3.
keeper.mycompany.com.ca-bundle
is the CA bundle containing intermediate and root public certificate chains
keeper.mycompany.com.pfx
is the pkcs12 output file used by SSO Connect that has been encrypted with a password.
Make sure to save all 4 files and the generated strong password in your Keeper Vault. Note: The generated key password should not contain special characters.
You will need this password when importing the PFX file into Keeper SSO Connect Interface. (7) Install the Certificate
Back in SSO Connect On-Prem, click “⚙️Configuration”:
(8) Drag or upload the .pfx file you just generated into SSO Connect:
(9) Click “Save” in the upper right hand corner of SSO Connect and your certificate configuration should be complete.
Once this is complete, please check the end-user login flow to ensure that the SSO login works.
Operating Keeper SSO Connect On-Prem in HA mode
Keeper SSO Connect On-Prem can be optionally configured to operate in a multi-instance HA environment. Once the first instance is configured (per Windows and Linux 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.
Each HA instance must run the same version of SSO Connect
Install Keeper SSO Connect On-Prem on the new instance
Login to the SSO Connect instance configuration screen and select the SSO Connection from the drop-down menu after login.
Use the Windows Services screen to restart Keeper SSO Connect.
Upon startup the SSO Connect service is synchronized to this instance and will begin to process user transactions.
Use the command-line interface to initialize the instance using the following procedure: $ java -jar SSOConnect.jar -config
Enter the following when prompted:
Keeper Administrator email address
Keeper Administrator Master Password
Two-Factor code (if enabled on the account)
SSO Domain Name (this attribute is defined on the SSO Connect provisioning screen on the Keeper Admin Console)
When the configuration steps are finished, the current settings will be sync'd from the server including the SSL Cert and IDP XML file, so you don’t have to supply information for those settings. But if you are using a private IP you will have to set that up in the Configuration dialog. When asked “Do you wish to configure…”, enter Y. Hit enter to retain existing values until it prompts for the Private IP and Private Port. Enter the appropriate values.
Continue pressing Enter to accept the current settings until all prompts are answered.
Restart the service.
$ systemctl restart ssoconnect
Upon startup the SSO Connect service is synchronized to this instance and will begin to process user transactions.
Keeper SSO Connect On-Prem optionally integrates with cloud-based Amazon HSM (CloudHsmV2) devices for key protection and storage.
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.
Amazon currently allows only CloudHsmV2 for new HSM deployments; Keeper supports this version. a. Legacy Cloud HSM v1 hardware is not supported by Keeper.
Amazon HSM software currently supports Linux or Windows installations.
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
Port TCP/8080 open, inbound from a Keeper Admin workstation to Keeper SSO Connect for admin GUI access (optional)
Provision your Amazon HSM cluster and install the HSM software on the SSO Connect machine as described in:
https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html
or
https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-win.html
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:
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.
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.
Verify that the HSM device is accessible.
SSOconnect has a built-in test program copied from the Amazon test libraries:
It should print the keys stored in the HSM.
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.
The error will be a variation of "Unable to use Secure Key Storage". This indicates one of the following problems:
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\
.
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.
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.
Keeper SSO Connect optionally integrates with on-premise and cloud-based Gemalto HSM devices for key protection and storage.
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.
The Gemalto HSM must be running Luna firmware 6.2 or higher.
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
Port TCP/1792 open, bidirectional to/from the HSM system
Port TCP/8080 open, inbound from a Keeper Admin workstation to Keeper SSO Connect for admin GUI access (optional)
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
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.
the IP address or hostname of the HSM machine.
The admin password (also known as the Security Officer password).
A unique string, such as the IP address of your current machine, or your name, etc.
The password for the Crypto Officer for the partition.
The partition name where you will store keys (this should be already configured).
NOTE: If you haven't set up a partition yet, use the 'lunash' program and login as admin to create a partition. See the Gemalto Luna documentation.
Start the Luna Client:
In addition to the normal SSO Connect configuration questions there are some HSM-specific questions as shown below.
Verify that the server is appropriate. CentOS 6 or 7 is preferred. We do not support Windows at this time.
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.
Verify that Java 1.8 or Java 11 is available.
Verify that the Luna libraries are available.
Verify that the correct ports are open The firewall must allow both inbound and outbound connections to/from ports 22 and 1792.
Verify that the user is a member of the hsmusers group:
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.
Verify that you don't have a partial configuration in the data
folder.
If you previously tried and failed to configure KeeperSSO, it is
safe to delete the KeeperSSO/data
folder and start over.
Verify that the app has read/write permissions to the data/
folder
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.
The error will be a variation of "Unable to use Secure Key Storage". This indicates one of the following problems:
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\
.
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.
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.
Instructions for upgrading your Keeper SSO Connect On-Prem Service
Keeper Security performs security updates to Keeper SSO Connect On-Prem.
Follow the instructions in the Update Instructions page to proceed with the upgrade.
Proceed with Step by Step Instructions
If you are not familiar with your environment or if you are not comfortable performing the update, please contact Keeper support.
Before you contact support, please provide the following information:
SSO Connect Version
SSO Connect server OS version
Identity Provider name and version
Java version
Any other network configuration (e.g. HA, Firewall, NGINX, etc)
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.
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.
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.
The SSO Connect Installer can be found by logging into the Admin Console and clicking on the Download link under the "Provisioning" tab.
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.
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
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:
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.
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.
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.
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.
Ensure that end-user SSO Login is successful through the Keeper Web Vault, Desktop or mobile applications.
Upgrade Complete!
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.
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.
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.
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.
Changing the SSL certificate, hostname, or the metadata configuration in SSO Connect On-Prem
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:
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.).
Save the changes. (This replicates the changes to the Keeper Cloud).
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.
From the Keeper Cloud perspective, there is no primary or secondary SSO Connect server in an HA configuration. There is a single SSO Connect data back up (per SSO Connect provisioning instance) that synchronizes to all the servers architected for HA.
Do not delete the SSO Connect provisioning instance on the Admin Console. Doing so will remove the configuration and orphan your SSO Connect servers.
How to change SSO Connect On-Prem servers with minimal down time.
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.
Do not delete the SSO Connect provisioning instance on the Admin Console. Doing so will remove the configuration and orphan your SSO Connect servers.
1. Install the new SSO Connect server as previously done for Windows or Linux.
Each server will need to be at the same Keeper SSO Connect version. Recommend ensuring the initial (or active) SSO Connect is upgrade to the latest version prior to installing subsequent servers.
2. Depending on the configuration, the Private IP address field may need to be populated with the local IP address of the new server. If the initial SSO Connect server had the Private IP address configured, that data does not synchronize with the SSO Connect configuration since in most cases the private IP is unique to the individual server.
If after authenticating to the new server on the configuration page the service is Stopped. It is most likely due to the Private IP address not set correctly to let the service bind to the local IP of the NIC.
3. If the host-name is a DNS name that is not changing, then no reconfiguration is needed as the DNS record can point to the new server. If the host-name is changing with the new server, the host-name will need to be updated in the SSO Connect configuration.
4. If the host-name changes, it may affect the SSL certificate. If a wild card cert was used and the new server is satisfied by that wild card, no action is needed. If the SSL cert was specific to the server name, and a new server name (or IP address) is now the host-name, a new SSL certificate may be required.
5. When the new configuration is updated click save. The new server is ready to support the SSO authentication process.
When the configuration is saved on one server it replicated to the cloud and synchronizes to the other servers.
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.
On Linux servers the data
folder is under the SSO Connect install folder, typically $HOME/sso_connect/data
.
On Windows servers 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.
The Keeper SSO Connect application provides an HTTP request that you can integrate into existing monitoring systems. The application status can be found by sending an HTTP GET request to this URL:
Ensure that the IP/Name and Port are accessible. If the service is active, you will get a JSON response as shown below:
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:
Resource for answering common questions and resolving errors.
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.
Follow the steps outlined on the Updating the SSO Connect Configuration page of this guide.
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 (https://docs.keeper.io/sso-connect-guide/identity-provider-setup/ad-fs-configuration#obtain-federation-metadata-xml). We strongly recommend setting a reminder before the expiration of the certificate so this step can be performed to maintain operation.
To prevent a logout error, change the SAML Logout Endpoint URL
In your ADFS manager server, go to the Relying Party Trusts properties for Keeper SSO Connect.
Under the Endpoints tab, edit the SAML Logout Endpoints and set the URL to: https://<YourADFSserverDomain>/adfs/ls/?wa=wsignout1.0
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.
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.
If you are hosted in the EU region, use keepersecurity.eu
If you are hosted in the AU region, use keepersecurity.com.au
If you are hosted in the US GOV region use govcloud.keepersecurity.us
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.
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.
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.
The SSO Connect service will be in a "Stopped" status if the Private IP address is needed and not configured.
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.
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.
If a user is transitioned to SSO login, but desires to change their master password, they will need to be relocated to a node that doesn’t have the SSO enforcement.
If use of a master password in conjunction with SSO authentication is desired, follow the steps outlined in the Enterprise guide for vault offline access: https://docs.keeper.io/enterprise-guide/vault-offline-access
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.
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.
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
.
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.
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.
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
.
The user will be prompted via email to confirm the change.
Once the user has changed their email, ensure the SSO IdP email has been changed.
After the address change is made, the administrator will need to perform a sync on the SSO Connect Server.
If more than a few emails need to change at the same time, please contact support to coordinate this change.
If using Duo for 2FA, have user disable their 2FA prior to the email change. (Admin may have to change the role to temporarily allow no 2FA on the account). This because if the email changes outside of Keeper and the vault is still associated with the old email, it may not correspond to what is in Duo.
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 Trusted Sites Policy for settings.
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:
See the "Upgrading SSO Connect" section of this document.
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.
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.
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.
Keeper provides automated migration from your SSO Connect On-Prem instance to Cloud SSO.
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 SSO Connect Cloud 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 here. Users and admins can also manually process device approvals until an automated method is set up.
IMPORTANT We recommend scheduling and planning migration with a Keeper support engineer before you start the process.
IMPORTANT DO NOT DELETE your existing On-Prem SSO instance until after 100% of users have migrated. DO NOT DELETE the On-Prem Keeper application from your identity provider until after 100% of users have migrated. Both instances must remain active until all users have logged in at least one time, and until all migration is completed.
Ensure that all of the on-premise IdP users are also provisioned in the Cloud IdP instance. For example, inside Azure ensure that users are assigned to the SSO Cloud enterprise application.
For devices to be automatically approved as part of this SSO migration process, we recommend installing Keeper Automator. Instructions for provisioning Keeper Automator can be found here: https://docs.keeper.io/sso-connect-cloud/device-approvals/automator
Start in the Keeper Admin Console by accessing "Admin" from left-side menu. Select a node with the on-premise SSO Connect instance where users are migrating from.
Now add a new SSO Connect Cloud provisioning method inside that same node. A popup message will appear that explains if the user continues, Keeper will assume that user authentication is moving to the cloud. Select "Continue" to complete the migration setup.
Configuration of the new SSO Connect Cloud environment can be done before or after SSO migration has started. In the event that the SSO Connect Cloud environment is setup after migration begins, the SSO Connect Cloud instance will show as "Pending" during migration.
Your SSO Connect Cloud environment can be setup using the process described here:
Note that during setup of your new SSO Cloud instance, you are asked to specify an "Enterprise Domain". This is simply a unique identifier that is used to reference the identity provider configuration. It isn't actually a domain name, it's just an arbitrary identifier that you can set to anything. If you used your domain name for the on-prem instance (e.g. company.com), the new SSO Cloud Enterprise Domain could be set to something like new.company.com or whatever you like. Ideally it would be something users can remember.
Once setup of your SSO Connect Cloud instance is completed, make sure that you test the process with a new user. Ensure that new users are able to authenticate with the SSO Cloud instance and ensure that you're able to approve devices.
After assigning Keeper SSO Connect Cloud to a node with Keeper SSO Connect running, Keeper will begin the migration and the provisioning screen will show the status "Migration in Progress" along with the number of users migrated to SSO Connect Cloud.
During the migration process, both on-prem and cloud instances must remain intact. This is a slow roll migration which is performed as end-users login.
When existing and new users log in, they will automatically be moved and authenticated using the SSO Connect Cloud. If the SSO Connect cloud environment has not been set up yet, the cloud instance will show a status of "Pending" instead of "Active".
When the cloud instance is in a "Pending" state, The users can still be migrated in Keeper indicating they have logged in and a key exchange has occurred which will allow them to be provisioned via SSO Connect Cloud when it is activated. The migrated users will still be authenticated using the on-premise SSO Connect until the SSO Connect Cloud environment is activated.
Keep in mind the On-Prem SSO and the Cloud SSO each have unique "Enterprise Domains" configured. To prevent the user from inadvertently logging back into the On-Prem instance when trying to migrate to the Cloud instance, click on the "Back" button to navigate away from the Enterprise Domain screen and start the authentication with the user's email address.
When all users have finally logged into Keeper and have been migrated to SSO Connect Cloud, the migration status will change to "Migration Complete". If the SSO Connect Cloud is also "Active", then the message under "Migration Complete" will include the instruction: "You can delete the SSO Connect On-Prem Method for this node."
Do not delete SSO Connect on-premise provisioning method for this node until 100% of the users have fully migrated and Keeper informs you that deletion is safe.
At any point during the SSO migration, the administrator can export a migration status report in CSV format. For each SSO user, the report shows: user UID, user name, user email address and the user's migration status.
If any users do not successfully migrate to SSO Connect Cloud using this automation process, these users can be moved using a manual process described in the following document:
If you have any questions or require assistance in configuring Keeper SSO Connect, please contact the Keeper Enterprise Support team at: business.support@keepersecurity.com.
Make sure to provide the following information in your request:
1. SSO Connect Version 2. SSO Connect OS type and version 3. Identity Provider name and version 4. Java version running on your server 5. Your time zone and preferred meeting time
To learn more about the Keeper Encryption Model, see the below link: https://docs.keeper.io/enterprise-guide/keeper-encryption-model