User Guide

Welcome to Keeper SSO Connect

We're excited you have chosen Keeper to protect your business. This guide will provide valuable information on how to set up Keeper SSO Connect and use the powerful features of the Keeper Enterprise platform.


Overview

Keeper SSO Connect is a SAML 2.0 application which 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 G Suite, Microsoft AD FS / Azure, F5 BIG-IP APM, Okta, 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 or cloud servers. Users encryption keys are generated dynamically by Keeper SSO Connect, encrypted and stored locally on the installed server, providing the customer with full control over the encryption keys that are used to encrypt and decrypt their digital vaults.

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

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. It can also 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 sit behind a load balancer.


System Requirements

The Keeper SSO Connect is a lightweight service that can be installed on a private on-premise or cloud-based server. It is not resources intensive.

Supported platforms: Windows Server 2008 R2, Windows Server 2012, Windows Server 2012R2, Windows Server 2016, Red Hat Linux RHEL 6.8 or above, Centos 7 or above, Mac OS X Server. JRE 1.8 is required.


Installation and Setup

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

  1. 1. Enable SSO Connect from the Keeper Admin Console
  2. 2. Install Keeper SSO Connect on your server (supports Windows, Mac, Unix/Linux)
  3. 3. Configure Keeper as a SAML 2.0 service provider on your existing Identity Provider

Activating SSO Connect from the Admin Console

Show Node Structure

Visit the Admin Console and login as the Keeper administrator.

SSO integration is applied to specific nodes (e.g. organizational units) within your Admin Console outside of the root node. To display the node structure, select on "Configuration" then "Show Node Structure".

Create SSO Node

Select on the "+" button to create a new node which will host the Keeper SSO Connect integration for AD FS. The node can be anywhere in your organizational structure. In the below example, the node is called "SSO - AD FS" and added beneath the root node.

Select "Create" then select the node.



Each SSO Connection can be associated with a node. Therefore, your organization is able to create multiple SSO connections assigned to different nodes.

Add SSO Connection

Select on the "Provisioning" tab of the node.

Next, select "+ Add Method" link to create a new connection.

Enterprise Domain

Every SSO Connection must be uniquely identified through the use of a supplied "Enterprise Domain" alias. This alias should be named something that is easy for your users to remember because they may need to type the name into their mobile and apps (iOS, Android, Mac, Windows) upon first logging into a new device.

New User Provisioning

Users can be dynamically provisioned to your Keeper Business account upon first successful authentication on SSO. 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.


Install Keeper SSO Connect

Pre-Installation

  1. 1. Download the Keeper SSO Connect application from the Admin Console and stage the executable on the server.
  2. 2.
  3. 3. Install Java 8 if not currently installed.
    • NOTE: Java 9 is not compatible.
  4. 4. Reboot the server

Installation - Windows

  1. 1. Extract the Keeper SSO Connect app.

  2. 2. Run KeeperSSOConnect as administrator.

  3. 3. Upon successful completion of the new installation the app will launch a web browser. (We recommend using Google Chrome to perform the initial setup). If the configuration web page doesn’t launch you can launch it with the new SSO Connect Icon on the desktop.

If you receive an error connecting to the Keeper SSO Connect service, you need to reboot the server. Also, you need to ensure that your web browser is able to connect to keepersecurity.com over port 443. Keeper SSO Connect does not support the use of proxy servers or firewalls that perform SSL packet inspection.

Installation - Linux

Instance Requirements

  1. 1. Java 8 runtime environment
  2. 2. Inbound port required for SAML communication from end-user device/browser (defaults to port 8443). If users can login from IdP on the public Internet, then this port must be public.
  3. 3. Outbound SSL port 443 opened to keepersecurity.com.
  4. 4. SSL private key (PKCS#12 or Java Keystore). During initial testing, a self-signed certificate is sufficient but users will receive a browser security warning.
  5. 5. FQDN assigned to the instance or to the load balancer
  6. 6. SAML 2.0 compatible IdP

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

  • $ java -version

Create a dedicated folder to host the SSO Connect application:

  • $ mkdir sso_connect

Download the latest Keeper SSO Connect / Linux version from this link:

  • $ cd sso_connect
  • $ wget https://keepersecurity.com/sso_connect/KeeperSso_java.zip
  • $ unzip KeeperSso_java.zip

Then start the Keeper SSO Connect service:

  • $ java -jar SSOConnect.jar

Now that the application is installed, you can begin the configuration using the web browser GUI or through the command line. Configuration options are discussed next.

Option 1: Configure through web GUI with local port access

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:

Option 2: Configure through web GUI via SSH Tunnel

To remotely configure SSO Connect through the web interface, simply open an SSH tunnel to the target system, for example:

  • $ ssh -L 9000:127.0.0.1:8080 ec2-user@12.34.56.78

Then open your web browser on your local system to:

Option 3: Configure through SSH / command line options

Keeper SSO Connect can be start up in a configuration mode which prompts you for the necessary parameters.

  1. 1. From the remote instance that is currently running Keeper SSO Connect, stop the existing running SSO instance by hitting CTRL-C or kill the process.
  2. 2. Copy the SSL Certificate (PKCS#12 or Java Keystore, IdP XML Metadata file) to the server
  3. 3. In the SSO Connect directory start the service in "config mode"
    • $ java -jar SSOConnect.jar -c
  4. 4. You will be prompted to supply the following parameters:
    • Keeper email address (of Admin)
    • Keeper Master Password (of Admin)
    • Two-Factor code (if enabled on account)
    • SSO Domain Name (this comes from the Admin Console provisioning screen)
  5. Next you will be able to configure each individual parameter. Leave the setting blank (hit <enter>) to accept the default setting.
    • SSO Connect Hostname or IP Address
    • Advertised SSL Port
    • Bound (private) IP
    • Bound (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

One the settings have been successfully implemented, they will sync to all other SSO Connect services upon restart of the service on each instance.

* Note: JKS Keystore type may require both Key Store and Passphrase to be the same

Option 4: Configure through SSH full command-line parameters

SSO Connect supports many command-line options that can be scripted to automate operations such as rotation of SSL keys.

For a full list of command line parameter options, use the "-h" flag:

$ java -jar SSOConnect.jar -h

Usage: java -jar path_to_jars/SSOConnect.jar [option [option_argument]][option [option_argument]][...]

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.
Note: if the instance is already initialized, you cannot re-initialize without deleting the contents in the data directory.
-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
* -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.
* options require username, password, and twofactor 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:

$ java -jar SSOConnect.jar -key_store_type p12 -key_store_password XXX -key_password XXX -ssl_file /path/to/sslfile -saml_file /path/to/samlfile -username you@company.com -password masterpass -twofactor 123456


You will be prompted to supply passwords through the interactive shell if left unset.


After you configure an instance, the changes will be immediately pushed to all other SSO Connect instances in your HA environment.




SSOConnect will uses the standard log4j2 libraries as its logger. It will look for the configuration file in the following order:

  • Value of the system environment variable 'logging.config'
  • log4j2.xml in the current working directory
  • log4j2.xml in the directory the SSOConnect.jar file is in
  • a log4j2 configuration file according to the standard log4j2 search criteria
  • the default log4j2.xml included inside the SSOConnect.jar file

Modifying the log4j2.xml file will only take affect after the service is restarted and only if it is the first log4j2 configuration file found.



Running Keeper SSO Connect as 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.

  1. 1. If the application is still running because you configured it with the web interface, stop the running instance by entering CTRL-C.
  2. 2. Create a system startup file /etc/systemd/system/ssoconnect.service with the following content:
    • [Unit]
      Description= SSO Connect Java Daemon
      [Service]
      WorkingDirectory=/home/{user}/sso_connect
      User={user}
      ExecStart=/usr/bin/nohup /usr/bin/java -jar /home/{user}/sso_connect/SSOConnect.jar /home/{user}/sso_connect
    • ### On Centos/RedHat you may need "nohup" in ExecStart.
      [Install]
      WantedBy=multi-user.target
  3. 3. Run systemctl to start the service
    • $ systemctl status ssoconnect
      $ systemctl start ssoconnect
      $ systemctl status ssoconnect

Troubleshooting Linux

  1. 1. 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:
    • http://127.0.0.1/ping
  2. For most installations, this will be
    • $ curl https://<public_ip>:<port>/ping
  3. 2. You can review log files which are located by default in working_directory/logs/ssoconnect.log. The logging is done through a standard log4j2.xml file located in the install directory. You may change the log4j2.xml to put your log files anywhere you wish.

Protection of Data Files

In the SSO Connect installation folder is a data/ directory. Inside the data directory there are 3 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.



Windows GUI Configuration

Log into the SSO Connect Web UI with a Keeper Administrator account.

  • This account should not be configured for Single Sign-On.

Enter Two Factor Authentication code if prompted.

Select the SSO Connection (Enterprise Domain).

Once you successfully authenticate Keeper SSO Connect to your Admin Console you will see the status tab:

Select on the Configuration link to begin the setup.

Enter the Advertised Hostname or IP Address. This address is what the Keeper client applications navigate to in order to initiate the SSO authentication process. If installing Keeper SSO Connect in an HA (High Availability) configuration, this is the address the that points to the load balancer. This address can be either an IP or a hostname.

Bound IP Address. This is the physical IP address of the NIC on the server. If a hostname is not used and if there is only one address associated with the server this entry will be the same as the Hostname or IP Address field.

In the sso-1.test-keeper.com is the Advertised Hostname that gets routed to the local address 10.1.0.4. The Keeper SSO Connect service binds to the Private IP address.

  • The IP/Hostname must be accessible by users who will be accessing Keeper. You may need to update your firewall to allow access over the IP and port.

SSO Connect SSL Key and Certificate

In order for the Keeper SSO Connect service to start an SSL Certificate is required. A self signed certificate can be generated. However, before deploying to production, it is recommended that a proper SSL Certificate from your certificate authority be generated and uploaded to this section. Self-signed certificates will generate security errors for your users.

  • Note: SSL Certificates must be renewed yearly
  • Select your specific IDP. If your IDP is not in the pull down select “Default”.

    SSO Connect Status

    Reasons your status is listed as Stopped:

    1. 1. Your SSL Certificate is missing or incorrect.
    • The hostname in the SSL certificate doesn’t match the hostname in SSO Connect. **A wildcard SSL cert can be used or one 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 Appendix on creating a self-signed SSL cert if you need to create a self signed SSL certificate for testing or troubleshooting your SSL certificate.

    IdP Metadata

    Select your IdP Provider. If your provider is not listed select “Default”.

    The next step is to upload the IdP metadata file. This file can be downloaded from your IdP.

    Identity Provider Attribute Mappings

    Attribute Mappings do not require any changes. Slect "Save".

    Restarting the Keeper SSO Connect Service

    The Keeper SSO Connect runs as a service. Closing out the web interface does not stop the service. The service can be stopped and started from the Service MMC in windows.


Identity Provider Setup

Keeper SSO Connect can be integrated with any SAML 2.0 compliant IdP. Listed below are several of the more popular IdP’s along with specific setup instructions.

Microsoft AD FS

Obtain Federation Metadata XML

Inside the AD FS Management application, locate the Federation Metadata xml file via URL Path "/FederationMetadata/2007-06/FederationMetadata.xml" as seen below:

Import Federation Metadata

Import the FederationMetadata.xml file into Keeper SSO Connect’s configuration screen by dragging and dropping the file:

Select "Save" to save the configuration.

Export Keeper SSO Connect Metadata

Select the “Export Metadata” link on Keeper SSO Connect and copy the sso_connect.xml file to your IdP.

Finish AD FS Configuration

Create Relying Trust Party

Create Keeper SSO Connect as a Relying Trust Party:

Import Keeper Metadata

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:

  1. 1.
  2. 2.
  3. 3.
  4. 4.
  5. 5.
  6. 6.
  7. 7.

Create Claim Issuance Policy Rules

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.

  1. 1.
  2. 2.
  3. 3.
  4. 4.
  • Important: Ensure that 3 attributes ("First", "Last" and "Email") are configured with the exact spelling as seen above.
  1. 5.
  2. 6. For Logout support we need to add two more Claim Issuance Policy rules:
  3. 7. Send Claims using a Custom Rule
  4. 8. Create Opaque Persistent ID

To copy the syntax to add in the claims rule select the link to the plain text file and paste the contents into the custom rule:

https://keepersecurity.com/sso_connect/Create_Opaque_Persistent_ID

  1. 9. Transform an Incoming Claim
  2. 10. Create Persistent Name Identifier
  3. Incoming claim type: http://mycompany/internal/sessionid
    Outgoing claim type: Name ID
    Outgoing name ID format: Transient Identifier
  4. 11.

ADFS Troubleshooting

If after setting up Keeper SSO Connect customer 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:
    PS C:\Windows\system32> Get-ADFSRelyingPartyTrust

    You should see something like this:

    AllowedAuthenticationClassReferences : {}
    EncryptionCertificateRevocationCheck : None
    PublishedThroughProxy : False
    SigningCertificateRevocationCheck : None
    WSFedEndpoint :
  • Run the following two commands:
    PS C:\Windows\system32> Set-ADFSRelyingPartyTrust -TargetIdentifier
    https://DOMAIN:8443/sso-connect -EncryptionCertificateRevocationCheck None
    PS C:\Windows\system32> Set-ADFSRelyingPartyTrust -TargetIdentifier
    https://DOMAIN:8443/sso-connect -SigningCertificateRevocationCheck None

Your Keeper SSO Connect setup is now complete!

Azure

Create Enterprise Application

From the Azure Cloud portal (https://portal.azure.com), select “Enterprise Applications” on the left menu section. (If Enterprise Applications is not shown, admin can be added to Favorites list).

Next, select "+ New application" icon.

Type “keeper” in the search, select the application.

The app will open in the right window pane. Scroll down and select "Add".

Configure the Application

Next, select the "Configure single sign-on" screen.

Select "SAML-based Sign-on":

Under the "Domain and URLs" section, type in the "Sign on URL", "Identifier", and “Reply URL”. These are the specific URL’s to the SSO Connect server.

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

Under the "User Attributes" section, select the “View and edit all other user attributes” to add needed attributes.

First, delete the 4 predefined SAML Tokens Attributes: givenname, surname, emailaddress, and name.

Next, select the add button to add the following required attributes: First, Last and Email.

  • It is important that the spelling and capitalization of the attribute is exactly as it appears (First, Last, Email) because these fields are case sensitive.
  • Ensure the Namespace is left blank

  • Ensure the Namespace is left blank

  • Ensure the Namespace is left blank

  • If the UPN is not the same as the users actual email address select user.mail as the value for the Email attribute.

Generate SAML Signing Certificate

Select "Create new certificate".

Enter the expiration date and save

After creating the certificate select Make new certificate active.

Obtain Metadata XML

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

Select on the "Metadata XML" link:

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

Import the Azure Metadata

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

  • Don’t forget to select Azure as the IDP Type.

User Provisioning

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

Next, 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.

Lastly, 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!

Okta

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 the .pem file created in Appendix

After selecting upload the name of the pem file along with the CN is displayed.

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 Okta “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!

G Suite

To access G Suite Admin Console, login to https://gsuite.google.com.

Then select Sign in.

Select on the "Apps" section.

Select on "SAML apps".

Select the "+" button.

Then select custom app:

On the Google IdP Information screen, download the IDP metadata and save it to your computer for later.

Select "NEXT".

On the "Basic information" screen, type in the Application Name, Description and upload the Keeper logo file keeper256x256.png. Then select "NEXT".

On the Service Provider Details screen, you need to enter the "ACS URL" and "Entity ID". These values come from the Keeper SSO Connect configuration screen. Copy and Paste the information from SSO Connect to the Service Provider screen on G Suite:

Input the ACS URL and Entity ID from Keeper SSO Connect to G Suite screen:

  • Example:
    Entity ID = https://keeper.domain.com:8443/sso-connect
    ACS URL = https://keeper.domain.com:8443/sso-connect/saml/sso

Select "NEXT" then proceed to the Attribute Mapping screen. You need to select on "ADD NEW MAPPING" and create 3 fields: First, Last and Email. Map those fields exactly as it appears below. 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:



Import G Suite Metadata

  • On the Keeper SSO Connect application configuration screen, drag-and-drop the metadata file saved in the previous step D above 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.

Your Keeper SSO Connect setup is now complete!

OneLogin

Login to the OneLogin portal.

From the onelogin menu select “Apps” then “Add Apps”.

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

On the “Add Keeper Password Manager” select 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.

Next, select the Configuration tab.

On the OneLogin Configuration tab, fill in Domain Address and port of the Keeper SSO Connect server in the Application Details “Domain” field.

Select "Save" in the upper right hand corner 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!

Ping Identity

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.

Your Keeper SSO Connect setup is now complete!

Centrify

Login to the Centrify Admin portal via the cloud login.

Switch to the Admin Portal from the pull down menu.

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

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

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

Close the Add Web Apps Window.

The next step is to upload Keeper’s SSO Metadata to Centrify.

In Keeper SSO connect, export the Keeper SSO Connect metadata using the "Export Metadata" link and save this file for the next step.

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

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

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

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

Download the Keeper logo.

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

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

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

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

  • setAttribute("Email", LoginUser.Get("mail"));
    setAttribute("First", LoginUser.FirstName);
    setAttribute("Last", LoginUser.LastName);
  • 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!

F5

On the F5 BIG-IP APM, configure a new SAML IdP service for your Keeper platform:

Go to Access Policy -> SAML -> BIG-IP as IdP -> Local IdP services

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

Upload this file to the server where Keeper SSO Connect is installed. We'll need it in the next step.

Import the Metadata file extracted from F5 BIG-IP APM into SSO Connect.

Select "Save" to save the configuration and verify all settings look correct.

Export the Keeper SSO Connect Metadata file for configuration of F5 BIG-IP APM from the Export Metadata link.

Your Keeper SSO Connect setup is now complete!

JumpCloud

JumpCloud also provides instructions for setting up Single Sign On (SSO) with Keeper Security.

As listed in the JumpCloud SSO Prerequisites a public certificate and a private key pair are required. Instructions can be found here.

Log into the JumpCloud Administrator console.

Select the "Applications" tab on the side menu.

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

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

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

The IDP ENTITY ID is a unique, case-sensitive identifier used by JumpCloud for this Service Provider (SP). This value should match the value specified in the “Entity ID” field of the Keeper SSO Connect. Your domain name, SSO Connect server name or IP address are possible examples.

Next, Upload the IdP Private Key (private.pem file) and IDP Certificate (cert.pem file).

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

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

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

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

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!

AWS SSO

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
Email ${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.

Your Keeper SSO Connect setup is now complete!


Firewall Configuration

On the server running Keeper SSO Connect, ensure you allow connections from Keeper SSO Connect via Inbound rules on the Windows Firewall, eg. port 8443 used by default, otherwise the request will be blocked.



Logging and Monitoring

Depending on the windows server operating system, SSO Connect Logs are located in either:

C:\Windows\System32\logs\ssoconnect.log

Or

C:\Windows\SysWOW64\logs\ssoconnect.log


Logging into your Keeper Vault (End-User Flow)

Keeper Vault Login Flow (SP-Initiated Connection)

Users can access Keeper directly from the Web Vault, Mobile App or Desktop App.

For example, from the Web App, visit https://keepersecurity.com/vault

Select "Enterprise SSO Login"

Then enter the Enterprise Domain as provided by the Keeper Administrator (entered into the Keeper Admin Console in section 4 of this document) and select "Connect".

To complete the user's profile, they must select a security question and answer.

Mobile app users can use the same flow by selecting "Enterprise SSO Login" during signup.

After account signup, the user is immediately logged into their Keeper Vault. Users will be presented with a quick start guide and helpful setup instructions.


Under the "Account" screen, you will see that the account is activated on the Keeper Business license.

Email Confirmation

When users are dynamically provisioned via Keeper SSO Connect, they will receive an email confirmation that contains helpful information including download links, Web Vault link and the "Enterprise Domain" info which is necessary to access Keeper from a new device.


High Availability Configuration

Keeper SSO Connect is designed to operate in a multi-instance HA environment. Once the first instance is configured (per instructions above) and the service is enabled to start upon boot, the instance can be cloned and additional instances can be launched underneath a load balancer.

To set up additional instances or to replace an instance, please follow these steps:

  1. 1. Install Keeper SSO Connect on the new instance per instructions above and start the service
  2. 2. Initialize the instance by one of the following methods:
    • Using the web browser, login to the SSO Connect instance configuration screen and select the SSO Connection from the drop-down menu after login.
    • Use the command-line interface to initialize the instance using the following procedure:

      Run the command line config option:

      $ java -jar SSOConnect.jar -c



      Type in the following when prompted:

      • Keeper Administrator email address
      • Corresponding 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)

When the following steps are finished, the current settings will be synched 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 it up. When asked “Do you wish to configure…”, enter Y. Hit enter to not change any values until it prompts for the Private IP and Private Port. Enter the appropriate values.

Continue to hitting to accept the current setting until all prompts are answered.



Restart the service
On a Unix system: $ systemctl restart ssoconnect


Now, the SSO Connect service is sync'd to this instance and it can process user transactions.









OLD
  1. 1. Once the first instance has been installed and configured further SSO Connect instances can be installed. They will automatically pick up the primary configuration.
  2. 2. Any load balancing or failover must occur via a frontend load balancer (hardware or software, such as nginx or haproxy).
  3. 3. Make sure the individual instances of SSO Connect servers have a local hosts record that points to their own network IP address for the HA server FQDN.

Advanced Monitoring

The Keeper SSO Connect application provides a network-level HTTP request that you can integrate into existing monitoring systems. For example, based on the above example the URL for testing the application status can be found by following this URL:

https://34.195.7.51:8443/ping

If the service is active, you will get a JSON response below:


FAQ’s

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

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

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

  • Reason being 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 internal and the FQDN resolves to the internal IP. So that field can be left blank. It depends on your setup.

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

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

    If a user is not is not transition 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.

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

  • When logging in for the first time the onboarding process needs to occur on either the Web or the Desktop application. The Browser Extension’s do not facilitate the onboarding process of a new user, but will allow existing users to authenticate.

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

  • There are two possible reasons for this error. The invited user is not in an SSO Enabled node within the Admin Console or the email address in the IdP doesn’t match the email address of the invited user. Try moving the user into the SSO Enabled node. If after verifying the user is in the correct node, try changing the SSO provisioning method from invited users to dynamic users. If the account gets created, it is most likely an email address mis-match.

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

  • On a linux system /tmp must have exec privileges. If /tmp does not have exec privileges, execution of "java -jar SSOConnect.jar" may show an exception similar to:
    java.lang.UnsatisfiedLinkError: /tmp/sqlite...

    To resolve this, ensure you have exec permission on /tmp.

Can users login via SSO and natively?

  • Enterprises can have some users configured to natively login and other users on SSO, but once a user has been transitioned to SSO, they will only be able to access their vault via SSO.

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

  • IE has difficulty handling cross-domain redirects due to their multiple security zones. Add *.keepersecurity.com to Trusted Sites Zone in IE.

Support

If you have any questions or require assistance in configuring Keeper SSO Connect, please contact the Keeper Business Support team at: business.support@keepersecurity.com


Appendix

Creating a Self-Signed Certificate - Windows

  1. 1. Download a copy of an OpenSSL Binary from this site:
    https://slproweb.com/products/Win32OpenSSL.html
  2. 2. Run as admin and take the default settings
  3. 3. Open command prompt
  4. 4. mkdir c:\<hostname>
  5. 5. cd \<hostname>
  6. 6. set RANDFILE=c:\<hostname>\.rnd
  7. 7. set OPENSSL_CONF=c:\OpenSSL-Win32\bin\openssl.cfg
  8. 8. c:\OpenSSL-Win32\bin\openssl.exe
  9. 9. genrsa -out <hostname>.key 2048
  10. 10. req -new -x509 -days 3652 -key <hostname>.key -out <hostname>.pem
  11. 11. Enter in the following data. Be sure the common name matches the Hostname or IP. Just hit “enter” for Email.
    • Country Name (2 letter code) []: US
    • State or Province Name (full name) []: California
    • Locality Name (e.g., city) []: Stanford
    • Organization Name (e.g., company) []: Stanford University
    • Organizational Unit Name (e.g., section) []: University IT
    • Common Name (e.g., web.stanford.edu) []: example.stanford.edu [This needs to match the HOSTNAME/IP of the SSO Connect configuration]
    • Email Address []:
  12. 12. pkcs12 -inkey <hostname>.key -in <hostname>.pem -export -out <hostname>.pfx

Creating a PKCS#12 Signed Certificate from Existing Certificate - Windows

Download a copy of an OpenSSL Binary from this site:

Run as admin and take the default settings.

Open command prompt:

  • mkdir c:\<hostname>
  • cd \<hostname>
  • set OPENSSL_CONF=c:\OpenSSL-Win32\bin\openssl.cfg
  • c:\OpenSSL-Win32\bin\openssl.exe

Place your private key (e.g. privateKey.key) and public key (e.g. certificate.crt) and the CA certificate chain (e.g. CACert.crt) in this folder. Then run this command:

  • openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

You may get prompted for the passphrase on the private key. The output file (certificate.pfx) can be uploaded into SSO Connect interface. If a keystore passphrase was set, enter the passphrase on the SSO Connect interface.