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
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
Linux-specific requirements
CentOS 6 or 7 is preferred, but the software can run on Ubuntu with the following additions:
If /lib/ld-linux.so.2
exists, go to the next section
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:
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
the IP address or hostname of the HSM machine.
The admin password (also known as the Security Officer password).
A unique string, such as the IP address of your current machine, or your name, etc.
The password for the Crypto Officer for the partition.
The partition name where you will store keys (this should be already configured).
NOTE: If you haven't set up a partition yet, use the 'lunash' program and login as admin to create a partition. See the Gemalto Luna documentation.
Verify that the HSM is configured
Start the Luna Client:
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.
Troubleshooting
Troubleshooting the Configuration
Verify that the server is appropriate. CentOS 6 or 7 is preferred. We do not support Windows at this time.
Verify that the Luna client is correctly installed on the server. Run the Luna client and login as the Crypto Officer to verify that you can successfully login and display the contents of the partition.
Verify that Java 1.8 or Java 11 is available.
Verify that the Luna libraries are available.
Verify that the correct ports are open The firewall must allow both inbound and outbound connections to/from ports 22 and 1792.
Verify that the user is a member of the hsmusers group:
Verify that SSOconnect is installed on the machine.
Usually there is a folder called
sso_connect
,KeeperSSO
, or some similar name. The folder will contain many jar files.
Verify that you don't have a partial configuration in the
data
folder.If you previously tried and failed to configure KeeperSSO, it is
safe to delete the
KeeperSSO/data
folder and start over.
Verify that the app has read/write permissions to the
data/
folder
Troubleshooting the Operation
Check the log file for errors. The Secure Key Storage subsystem of SSOconnect will print an ERROR line to the log if it encounters a problem.
The error will be a variation of "Unable to use Secure Key Storage". This indicates one of the following problems:
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.
Last updated