Integration with AWS CloudHSM
Keeper SSO Connect On-Prem optionally integrates with cloud-based Amazon HSM (CloudHsmV2) devices for key protection and storage.
Last updated
Keeper SSO Connect On-Prem optionally integrates with cloud-based Amazon HSM (CloudHsmV2) devices for key protection and storage.
Last updated
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.
Amazon currently allows only CloudHsmV2 for new HSM deployments; Keeper supports this version. a. Legacy Cloud HSM v1 hardware is not supported by Keeper.
Amazon HSM software currently supports Linux or Windows installations.
Port TCP/443 open, stateful outbound from Keeper SSO Connect to www.keepersecurity.com
Port TCP/2223 open, bidirectional from the SSO Connect machine to the HSM hardware
Port TCP/2225 open, bidirectional from the SSO Connect machine to the HSM hardware
Port TCP/8080 open, inbound from a Keeper Admin workstation to Keeper SSO Connect for admin GUI access (optional)
Provision your Amazon HSM cluster and install the HSM software on the SSO Connect machine as described in:
https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html
or
https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-win.html
You will need the Java libraries. On Linux the software is installed in /opt/cloudhsm.
Ensure that the cloudhsm_client service is running in the background:
Install SSO Connect as usual.
NOTE: The Amazon HSM Java software is supposed to recognize a file named HsmCredentials.properties on the Java Classpath.
However, this may not work for some reason. Instead you may need to set HSM_USER, HSM_PASSWORD, and HSM_PARTITION environment variables. For testing, you will probably have to set the shell variables.
Test the HSM connection:
It should print the keys in the HSM.
Configure SSO Connect as usual via the command line or in the admin interface at http://localhost:8080/config
a. Set the "Advertised Hostname", a. Add the SSL certificate, a. Add the SAML XML metadata file.
In the admin interface, the HSM configuration section is at the bottom of the Configuration page.
a. Select "Amazon CloudHsmV2" as the type, a. Some properties will appear in the box below. You probably don't need to change them. i. An exception would be if the certificate to be used to talk to the HSM is not the same certificate used for SSL in SSO Connect. i. You may need to enter a password for the certificate file (usually the same one used for the SSL certificate file). a. Click the Enabled/Disabled box, a. Click Save
SSO Connect should now restart and connect to the HSM. If the status page shows that HSM is enabled, it worked. In rare situations when startup is very slow you may need to click on the Status command again so that it updates the status.
If it didn't work, check the SSO Connect error log. The most common error is that it can't find the HSM credentials. Set the credentials as environment variables to ensure that they are available.
If it didn't work, check the error log. The most common error is that it can't find the HSM credentials. Set the credentials as environment variables to ensure that they are available.
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 the HSM device is accessible.
SSOconnect has a built-in test program copied from the Amazon test libraries:
It should print the keys stored in the HSM.
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:
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\.
If the SSO Connect server dies you will need to reinstall Amazon HSM and SSO Connect on the replacement machine using the standard 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.
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.
