SSO Connect On-Prem

Integration with Gemalto HSM

Keeper SSO Connect optionally integrates with on-premise and cloud-based Gemalto HSM devices for key protection and storage.

Integration with Gemalto HSM

Keeper SSO Connect HSM Overview

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.

Gemalto Luna HSM Instructions

HSM Requirements

  1. The Gemalto HSM must be running Luna firmware 6.2 or higher.

Network Requirements

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

Testing network access

$ telnet www.keepersecurity.com 443
Trying 52.204.60.27
Connected to www.keepersecurity.com.
Escape character is '^]'.

$ telnet push.services.keepersecurity.com 443
Trying 52.44.0.141...
Connected to push.services.keepersecurity.com.
Escape character is '^]'.

$ ssh <ip address of the HSM>
password: <admin-password>

Linux-specific requirements

CentOS 6 or 7 is preferred, but the software can run on Ubuntu with the following additions:

UBUNTU only:
$ sudo apt-get install zip unzip # used by the Luna installer
$ sudo apt-get install alien # used by the Luna installer to convert .rpm files
$ sudo apt-get install gcc-multilib # Because some Luna programs are 32-bit

If /lib/ld-linux.so.2 exists, go to the next section

If /lib/ld-linux.so.2 doesn't exist:
    if /usr/lib/ld-linux.so.2 exists:
        $ sudo ln -s /usr/lib/ld-linux.so.2 /lib/ld-linux.so.2
    if /lib32/ld-linux.so.2 exists:
        $ sudo ln -s /lib32/ld-linux.so.2 /lib/ld-linux.so.2
    otherwise (Ubuntu):
        $ sudo yum install gcc-multilib    # use yum or apt-get

If you are on Red Hat (CentOS), do this:
    $ sudo yum install glibc-devel.i686

Install the Luna Client

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:

$ tar xzf LunaClient_7.3.0-165.Linux.tar.gz
$ cd LunaClient_7.3.0-165_Linux/64
$ sudo sh install.sh
- Select Luna Network HSM
- Select (N)ext
- Select Luna JSP (Java)
- Select (I)nstall

$ sudo gpasswd --add <username> hsmusers
- type 'groups' to verify group membership
- You might need to create a new shell to recognize the new group

You might want to add this useful alias to your "~/.bash_profile" file.
alias luna='sudo /usr/safenet/lunaclient/bin/lunacm'

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

Configure Luna access

Requirements

  1. the IP address or hostname of the HSM machine.

  2. The admin password (also known as the Security Officer password).

  3. A unique string, such as the IP address of your current machine, or your name, etc.

  4. The password for the Crypto Officer for the partition.

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

Verify that the HSM is configured

  1. Start the Luna Client:

$ luna
lunacm (64-bit) v7.3.0-165. Copyright (c) 2018 SafeNet. All rights reserved.

lunacm:> clientconfig deploy -n <hsm-ip-address> -c <unique-string> -par <partition-name> -ur admin -pw <hsm-admin-password> -v

... make sure it finishes successfully


Available HSMs:

Slot Id -> 0 
Label -> [your-partition-name]
Serial Number -> 12345678987654321
Model -> LunaSA 7.3.0 
Firmware Version -> 7.3.0 
Configuration -> Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description -> Net Token Slot


Current Slot Id: 0


lunacm:>role login -n co
enter password: crypto-officer-password

Command Result : No Error

lunacm:>par con # display contents of partition
lunacm:>exit

Configure Keeper SSO Connect for HSM access

In addition to the normal SSO Connect configuration questions there are some HSM-specific questions as shown below.

$ java -jar SSOConnect.jar -config

... normal SSO Connect configuration questions...

Configure Secure Key Storage (y/N): y
IMPORTANT: Make sure that this server is already connected to a networked HSM or other secure key storage device.
Type of Secure Key Storage (Gemalto SafeNet Luna HSM): <return>
Secure storage device access parameters (slot,password): <return>
  slot: 0
  password: crypto-officer-password
A certificate chain is required in order to store an encryption key.
You may use the SSL certificate file entered previously, or use a different one.
Certificate chain file (/home/ubuntu/keeperSSO/data/sso_keystore.jks): <return>
Certificate chain file password (none): <return>
1 certificates found
Enable Secure Key Storage (Y/n): y

Troubleshooting

Troubleshooting the Configuration

  1. Verify that the server is appropriate. CentOS 6 or 7 is preferred. We do not support Windows at this time.

    $ rpm -q centos-release
centos-release-7-6.1810.2.el7.centos.x86_64

$ cat /etc/centos-release
CentOS Linux release 7.6.1810 (Core)

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

    $ sudo /usr/safenet/lunaclient/bin/lunacm

luna> role login -n co
(enter password)
luna> par con
If this HSM has been used with Keeper before, there will be an existing key with a name like Keeper SSO Properties 514320201573

  3. Verify that Java 1.8 or Java 11 is available.

    $ java -version
java version "1.8.0_201"
Java(TM) SE Runtime Environment (build 1.8.0_201-b09)
Java HotSpot(TM) 64-Bit Server VM (build 25.201-b09, mixed mode)

  4. Verify that the Luna libraries are available.

    $ ls sso_connect/*Luna*
libLunaAPI.so   LunaProvider.jar

  5. Verify that the correct ports are open The firewall must allow both inbound and outbound connections to/from ports 22 and 1792.

    If the firewall is local, use:
$ iptables -xvn -L

  6. Verify that the user is a member of the hsmusers group:

    $ whoami
centos

$ groups
centos adm wheel systemd-journal hsmusers

** The Luna software requires that the user accessing the Luna libraries be a member of the hsmusers group.
$ sudo gpasswd --add centos hsmusers
You will need to open a new shell to see that this command worked correctly.

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

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

  9. Verify that the app has read/write permissions to the data/ folder

    $ ls -ld data
drwxrwxr-x 2 centos centos  181 Feb  4 19:42 data

Troubleshooting the Operation

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

    $ more logs/ssoconnect.log

  2. The error will be a variation of "Unable to use Secure Key Storage". This indicates one of the following problems:

      a. Network problem accessing the HSM
     - Perform Step 2 of "Troubleshooting the Configuration" to verify access to the HSM.

  b. data/sks.properties is missing
     - if data/sks.properties is missing you will need to re-configure SSOConnect.

  c. The encrypted property files are missing
     - Check for data/instance.encp and data/shared.encp.

  d. The encryption key is missing from the HSM
     - Did somebody clear the HSM partition?  You will need to re-configure SSOConnect.

  e. The server may be out of disk space
     - clear some disk space.

  f. The encryption algorithm used is not supported on the HSM
     - The algorithm is AES/GCM/NoPadding.  Check with the device provider.

  g. The file data/sso-keystore.jks is missing
     - The program cannot store a key in the HSM without the certificate chain from the sso_keystore.jks file.
       Find the file and ensure that it is in the data folder.

Backup

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

Recovery

Server Failure

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.

HSM Failure

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.

PreviousIntegration with AWS CloudHSMNextUpgrading SSO Connect On-Prem

Last updated