The Federal Information Processing Standard Publication 140-2 (FIPS 140-2) is a U.S. government standard that specifies the security requirements for cryptographic modules protecting sensitive information. The first release of the Red Hat build of Keycloak includes FIPS 140-2 support. Established by the National Institute of Standards and Technology (NIST), FIPS 140-2 aims to standardize the design and implementation of cryptographic software and hardware for more secure usage.
The standard is widely used in various sectors, including federal agencies, defense, healthcare, and finance, to ensure that cryptographic processes meet a certain level of security. It is also often a requirement for technology products sold to the U.S. government. Products that claim to be FIPS 140-2 compliant usually undergo a rigorous testing process by accredited labs. Once they pass, they are added to the FIPS 140-2 validated products list.
Running the Red Hat build of Keycloak on a FIPS 140-2 enabled system ensures that the operating system and the Java environment are configured to operate in FIPS mode. When installing Red Hat Enterprise Linux (RHEL), enable FIPS mode. This will configure the system to use only FIPS 140-2 approved cryptographic algorithms. Verify FIPS mode is enabled by checking the system configuration. On RHEL, you can use the following command:
sysctl crypto.fips_enabled
sysctl: Reads and modifies kernel attributes.crypto.fips_enabled: Attribute to enable and disable FIPS at system level.
The above command should return crypto.fips_enabled = 1 if FIPS is enabled.
Red Hat Enterprise Linux 9 also contains four predefined cryptographic policies, one of which is FIPS. When the system is in FIPS mode, the Red Hat build of OpenJDK should also automatically switch to FIPS mode. This is the default behavior since RHEL 8.3. However, you might also need to configure the Red Hat Build of OpenJDK to use FIPS-compliant security providers explicitly. Learn more about setting up FIPS with Red Hat build of OpenJDK.
The Red Hat build of Keycloak supports the FIPS-validated BouncyCastle library. To run in FIPS-compliant mode, download the BouncyCastle-FIPS library and add it to the Keycloak distribution. When it is running in FIPS mode, it will use BouncyCastle. Red Hat build of Keycloak supports pkcs12 and bcfks keystores for use with the Keycloak SSL. For more details on how to set up the host operating system and cryptography, refer to the useful RHEL guide.
To run the Red Hat build of Keycloak in FIPS mode, use the following command:
bin/kc.[sh] start --features=fips --hostname=localhost --https-key-store-password=passwordpassword --log-level=INFO,org.keycloak.common.crypto:TRACE,org.keycloak.crypto:TRACE
bin/kc.[sh]: The command-line admin utility for Keycloak.Start: Starts the server.--features=fips --hostname=localhost: Enables FIPS on startup.--https-key-store-password=password: Password for the keystore.--log-level=INFO...: Log levels can be set via this parameter.
Strict mode
There is the fips-mode option, which is automatically set to non-strict when the FIPS feature is enabled. This means to run BCFIPS in the "non-approved mode". The more secure alternative is to use --features=fips --fips-mode=strict, in which case BouncyCastle FIPS will use "approved mode." Using that option results in stricter security requirements on cryptography and security algorithms.
When starting the server, you can check that the startup log contains KC provider with the note about Approved Mode such as the following:
KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurity
Migration from a non-FIPS environment
It is possible to migrate to a FIPS environment, including current data in use. However, restrictions and considerations exist. The following are considerations for migrations:
- Make sure all the Keycloak functionality relying on keystores use only supported keystore types. This differs based on whether you use strict or non-strict mode.
- Kerberos authentication may not work. If the authentication flow uses Kerberos authenticator, this authenticator will be automatically switched to DISABLED when migrated to FIPS environment. It is recommended to remove any Kerberos user storage providers from the realm and disable Kerberos related functionality in LDAP providers before switching to FIPS environment.
- Ensure that all the Keycloak functionality relying on keys (for example, realm or client keys) use RSA keys of at least 2048 bits.
- Ensure that clients relying on Signed JWT with Client Secret use at least 14-character secrets (ideally generated secrets).
- Password length restriction as previously described. If users have shorter passwords, start the server with the maximum padding length set to 14 of PBKDF2 provider. To avoid this option, all user passwords might require reset (i.e., by the forget password link) during the first authentication in the new environment.
Read the following documentation for more in-depth details on using and preparing for FIPS mode.
Get support for Red Hat build of Keycloak
Support is available to Red Hat customers with a subscription. Contact your local Red Hat representative or Red Hat Sales for details on how to enjoy world-class support offered by Red Hat and its worldwide partner network. According to the Red Hat Product Update and Support Lifecycle, customers can expect support for the Red Hat build of Keycloak and other runtimes.
Ready to get started with Red Hat build of Keycloak? Check out the following links to get you started:
- ZIP distributions are available through the customer portal.
- Container distributions and operators are available in the Red Hat Ecosystem Catalog.
- Product documentation is available on the Red Hat customer portal, including a migration guide to help you migrate your existing single sign-on deployments to the Red Hat build of Keycloak.
To learn more, visit Red Hat build of Keycloak.
