There are different ways to use HSMs in the ForgeRock Identity Platform. This is because encryption or signing may be configured at different levels and for different requirements, and HSMs may be used for some features and not for others. See HSMs and ForgeRock Software for further information.
For HSM support, ForgeRock software requires a client library that conforms to the PKCS#11 standard 2.20 or later. The PKCS#11 standard defines a cryptographic token interface, which is a platform-independent API for storing keys in an HSM.
HSMs can be certified to comply with international standards such as FIPS-140 and Common Criteria. An HSM that is certified to comply with these standards can be part of your supported ForgeRock solution.
There are a couple of known issues with early versions of Java 11 and PKCS#11, so you should ensure you are using Java 11.0.6 or later if you're implementing an HSM. See SSLHandshakeException or ClassCastException when using an HSM and Java 11 with ForgeRock products for further information.
ForgeRock does not maintain a list of supported HSM vendors.
The following sections provide details on how HSMs can be used with core components of the ForgeRock platform.
In summary, AM can use an HSM in the following ways:
- Signing and decrypting SAML assertions. Signing and decryption keys can be stored in an HSM.
JWT signatures. Since the allowed JWS algorithms are limited, you need to be sure that the algorithms are supported by the HSM. Typically, HSMs support asymmetric key pairs and RSA or ECDSA signatures with the following algorithms: RS256, RS384, RS512, ES256, ES384 and ES512. The PS256, PS384 and PS512 algorithms may also work with some hardware and more recent Java versions. Not all HSMs support symmetric keys. The following JWT-based functionality can make use of a signing key stored on an HSM:
- Client-based sessions. Including authentication sessions (when using the JWT authentication state management scheme) and SSO sessions.
- OAuth 2.0 access and refresh tokens. Note that only signed tokens are compatible with an HSM. Encrypted tokens use an algorithm that is incompatible with most HSMs.
- Tokens for maintaining the self-service state. If the HSM supports HMAC symmetric keys.
- OIDC ID tokens and signed UserInfo responses. When using a compatible algorithm. HS256, HS384 and HS512 algorithms use the client secret as the key as per the OIDC specification and are not compatible with an HSM.
- Audit log signing with a key provided by an HSM.
- Remote consent service secured requests and responses.
- Java and Web Agent tokens used during the SSO process.
JWT encryption. Some functionality includes support for encryption and decryption using an RSA key pair stored on an HSM. Typically, encryption will retrieve the public key from the HSM and perform operations locally, whereas decryption will be performed on the HSM using the private key. The following JWT-based functionality is compatible with HSM encryption:
- Client-based sessions
- Tokens for maintaining the self-service state
- OIDC encrypted request objects
Encrypted data at rest. The following functionality can be configured to encrypt data at rest using keys stored in an HSM:
- OATH, Push and WebAuthn device credential storage
See Configuring Secrets, Certificates, and Keys for information on configuring AM to use an HSM.
ForgeRock Directory Services (DS) servers support key management using a PKCS#11 token store. DS servers use an HSM only to hold asymmetric key pairs and, optionally, CA certificates.
See PKCS#11 Hardware Security Module for further information.
ForgeRock Identity Management (IDM) supports the configuration of external PKCS#11 compliant HSM devices to manage the keys used to secure identity management transactions. IDM supports the retrieval of secrets from HSMs either locally or over the network.
The use of HSMs for SSL connections in IDM will depend on the JVM settings, the J2EE container settings, the HSM vendor support for Java, and the HSM support for PKCS#11.
See Configuring IDM For a Hardware Security Module (HSM) Device for further information.