Last changed
Get notified of upcoming product changes, critical vulnerability notifications and patches and more.
Sign InA wolfi-based image tailored for Keycloak, incorporating the required bouncycastle FIPS modules (bcfips) to facilitate Keycloak's operation in FIPS mode.
Both OpenJDK and Keycloak have been configured to harness the BouncyCastle FIPS API at their core. The included bcfips module meets FIPS 140-2 compliance requirements and is accredited under: FIPS certificate 4616.
This image is equipped with the essential components for Keycloak to operate in FIPS mode. However, it's important for users to ensure they use it in line with FIPS compliance standards.
This includes tasks such as keystore generation, configuration, and launching Keycloak with the correct configuration parameters. More guidance is provided in the sections below.
Keycloak requires a bcfips-compatible keystore to manage its SSL/TLS certificates.
Although Keycloak supports various keystore types, only BCKFS offers the capability to operate in approved (strict) mode under FIPS standards, ensuring only approved ciphers are used.
To create keystore in BCKFS format you can use keytool from this image like so:
To view the keystore
To create a truststore and import and trust an existing CA certifcate you can also use keytool:
When using keytool you may need to set the environment variable
JAVA_TOOL_OPTIONS
to set the --module-path
as documented in section 2.1.1
in the Bouncy Castle FIPS Java API User
Guide:
To use a truststore in a keycloak container configure it using javax.net.ssl
properties:
** Note on --truststore-paths
**
Currently it is not possible to use the --truststore-paths
option when using --features=fips --fips-mode=strict
, see this issue
Example of launching Keycloak in development
mode, with HTTP enabled and
strict hostname resolution not enforced:
In this example, the Keycloak UI is accessible via: http://localhost:8080.
Example of running Keycloak in production
mode, enforcing the use of HTTPS
and requiring a hostname to be provided:
In this example, the Keycloak UI is accessible via: https://localhost:8443.
You'll see debug logs such as the below if Keycloak is running in FIPS mode:
Additionally, you can check bcfips is enforcing minimum password lengths, by
running the container with a non-compliant admin password, such as 1234
:
Keycloak provides a mechanism to configure and customize the image. This process is outlined in the Keycloak image documentation.
There are subtle differences in the executable paths used in the Chainguard image. Below is the example copied from the documentation, updated with the correct paths:
production
modeError Message:
Solution:
BCFKS Keystores default to strict mode, and it's likely you omitted
--fips-mode=strict
in your arguments. If you wish to run in non-strict mode
with BCFKS, you need to include --https-key-store-type=bcfks
.
This is called out in the official documentation, but perhaps could benefit from additional clarification.
Error Message:
Solution:
The error indicates that a Keystore was detected, but there was an issue
parsing it. Usually this means that the password used to create the keystore
does not match what was provided as the --https-key-store-password
argument
to Keycloak.
production
modeError Message:
Solution:
This error usually indicates that a .keystore
was not detected in the
/usr/share/java/keycloak/conf
directory. Ensure you have created a Keystore
and it is accessible to the container in the expected directory.
Error Message:
Solution:
This is expected whenever Keycloak is running in strict
(approved) mode for
FIPS. Choose a longer admin password which is compliant. Refer to the Keycloak
FIPS documentation for more information.
Chainguard Images contain software packages that are direct or transitive dependencies. The following licenses were found in the "latest" version of this image:
Apache-2.0
BSD-3-Clause
FTL
GCC-exception-3.1
GPL-2.0-only
GPL-2.0-or-later
GPL-3.0-or-later
For a complete list of licenses, please refer to this Image's SBOM.
Software license agreementThis is a FIPS validated image for FedRAMP compliance.
This image is STIG hardened and scanned against the DISA General Purpose Operating System SRG with reports available.
Learn more about STIGsGet started with STIGs