Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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
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.
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.
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:
SSOConnect can also be configured via the following command line switches.
Note: if the instance is already initialized, you cannot re-initialize without deleting the contents in the data directory
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.
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.
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)
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.
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.
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.
