Installation - Linux

Instance Requirements

1. Java 11 runtime environment

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

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

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

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

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

$ java -version

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

ubuntu:~$ sudo apt install openjdk-11-jre-headless

Download and unzip the SSO Connect service:

ubuntu:~$ mkdir keeper
ubuntu:~$ cd keeper/
ubuntu:~/keeper$ wget https://keepersecurity.com/sso_connect/KeeperSso_java.zip
ubuntu:~/keeper$ unzip KeeperSso_java.zip

Then start the Keeper SSO Connect service:

$ java -jar SSOConnect.jar

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

OpenSSL v1.1.1

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

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

Access the web interface

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

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:

http://127.0.0.1:8080/config/

Configure through the web GUI via an SSH Tunnel

To remotely configure SSO Connect through the web interface, simply open an SSH tunnel to the target system, for example: If you do not have direct browser access to the SSO Connect machine, you may be able to configure a tunnel to the machine:

$ ssh -L 9000:127.0.0.1:8080 ubuntu@12.34.56.78

Then open your web browser on your local system to:

http://127.0.0.1:9000/config/

Configure SSO connect via the web console.

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.

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.

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.

SSO Connect SSL Key and Certificate

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).

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.

IdP Metadata

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").

Identity Provider Attribute Mappings

Attribute Mappings do not require any changes. Select Save.

SSO Connect Status

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.

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.

Linux configuration with interactive mode

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

1. Stop the running SSOConnect process, if any, by hitting CTRL-C or killing the process.

2. 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.

3. 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.

4. In the SSO Connect directory start SSO Connect in configuration mode: $ java -jar SSOConnect.jar -config

5. You will be prompted to supply the following parameters:

6. Keeper Administrator email address (to login to the Keeper Admin Console for your company)

7. Keeper Administrator Master Password

8. Two-Factor code (if enabled on account)

9. 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.

SSO Connect will not automatically start after a configuration session so you need to start it:

$ java -jar SSOConnect.jar

Linux configuration through SSH with 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\]\]\[...\]

SSOConnect can also be configured via the following command line switches.

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.

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

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

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

[Unit]
Description=SSO Connect Java Daemon 

[Service]
WorkingDirectory=/path/to/keeper (i.e. /home/keeperservice/sso_connect)
User=<user> (i.e. root)
ExecStartPre=/bin/sleep 10 
ExecStart=/usr/bin/java -jar /path/to/keeper/SSOConnect.jar

[Install]
WantedBy=multi-user.target

"chmod" the file:

sudo chmod 644 /etc/systemd/system/ssoconnect.service

Enable the service to auto-start.

sudo systemctl enable ssoconnect.service

Run systemctl to start the service.

$ systemctl start ssoconnect
$ systemctl status ssoconnect

Troubleshooting Linux

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

http://127.0.0.1:9000/ping

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:

$ curl "https://<public_ip_or_dns>:<port>/ping"

Example request/response:

curl "https://sso.acme-demo.com:8443/ping"
​
{"configuration":"Running","sync_revision":41838,"sync":"Thu Nov 21 07:36:51 UTC 2019","version":"o14.1.2.4","sso":"Running","status":"Ready"}

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.

$ tail -f /path/to/keeper/logs/ssoconnect.log

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