Last changed
Get notified of upcoming product changes, critical vulnerability notifications and patches and more.
Sign InChainguard Images are regularly-updated, minimal container images with low-to-zero CVEs.
This image is available on cgr.dev
:
Be sure to replace the ORGANIZATION
placeholder with the name used for your organization's private repository within the Chainguard registry.
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.
If you have a Zendesk account (typically set up for you by your Customer Success Manager) you can reach out to Chainguard's Customer Success team through our Zendesk portal.
Chainguard Images are a collection of container images designed for security and minimalism.
Many Chainguard Images are distroless; they contain only an open-source application and its runtime dependencies. These images do not even contain a shell or package manager. Chainguard Images are built with Wolfi, our Linux undistro designed to produce container images that meet the requirements of a secure software supply chain.
The main features of Chainguard Images include:
-dev
VariantsAs mentioned previously, Chainguard’s distroless Images have no shell or package manager by default. This is great for security, but sometimes you need these things, especially in builder images. For those cases, most (but not all) Chainguard Images come paired with a -dev
variant which does include a shell and package manager.
Although the -dev
image variants have similar security features as their distroless versions, such as complete SBOMs and signatures, they feature additional software that is typically not necessary in production environments. The general recommendation is to use the -dev
variants only to build the application and then copy all application artifacts into a distroless image, which will result in a final container image that has a minimal attack surface and won’t allow package installations or logins.
That being said, it’s worth noting that -dev
variants of Chainguard Images are completely fine to run in production environments. After all, the -dev
variants are still more secure than many popular container images based on fully-featured operating systems such as Debian and Ubuntu since they carry less software, follow a more frequent patch cadence, and offer attestations for what they include.
To better understand how to work with Chainguard Images, we encourage you to visit Chainguard Academy, our documentation and education platform.
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