Keycloak FIPS Tutorial

To deploy Keycloak in FIPS mode, you need a FIPS-approved keystore. In this tutorial we will use the Bouncy Castle FIPS KeyStore (termed BCFKS). A BCFKS keystore is a Java KeyStore (JKS) format provided by Bouncy Castle that is specifically designed for FIPS-compliant cryptography. The following guide involves the following components:

File	Purpose
`server.keystore` (BCFKS)	FIPS-approved keystore (private key + cert)
`truststore.bcfks`	FIPS-approved truststore (contains CA certs)
`myCA.crt` / `myCA.key`	Local CA (root) for signing/trusting dev certs
`keycloak.crt` / `keycloak.key`	Server certificate & key (PEM) for Keycloak

Prerequisites

Docker available locally
Token to pull images from the Minimus image registry
A working directory for keystores and certs

Deploy Keycloak for production

The following explains how to deploy Keycloak in either HTTPS mode or HTTP-dev mode.

Create a BCFKS Keystore (FIPS‑approved)

Use keytool from the Keycloak FIPS image to generate a BCFKS keystore and keypair (provider CCJ):

Create BCFKS keystore

docker run --rm \
  -v "$(pwd)":/tmp/keystore  \
  --entrypoint keytool  \
  reg.mini.dev/keycloak-fips \
  -J-Djava.security.properties=/usr/share/conf/java.security.append \
  -J-cp -J"/opt/keycloak/providers/*" \
  -v   -keystore /tmp/keystore/server.keystore \
  -storetype bcfks  \
  -providername CCJ \
  -alias "localhost" \
  -genkeypair  \
  -sigalg SHA512withRSA  \
  -keyalg RSA  \
  -dname CN="localhost" \
  -storepass "minimusstoretest2025"  \
  -keypass "minimusstorekeypass2025"

If you encounter a permissions-related error, grant write permissions to your working directory and rerun the above command:

sudo chown 1000:1000 "$(pwd)"
chmod 700 "$(pwd)"

keytool error: java.io.FileNotFoundException: /tmp/keystore/server.keystore (Permission denied)
java.io.FileNotFoundException: /tmp/keystore/server.keystore (Permission denied)

Verify the BCFKS keystore:

docker run --rm -v "$(pwd)":/tmp/keystore  \
  --entrypoint keytool  \
  reg.mini.dev/keycloak-fips \
  -J-Djava.security.properties=/usr/share/conf/java.security.append \
  -J-cp -J"/opt/keycloak/providers/*"  \
  -v   -keystore /tmp/keystore/server.keystore  \
  -storetype bcfks \
  -list   -storepass "minimusstoretest2025"

Keystore type: BCFKS
Keystore provider: CCJ

Your keystore contains 1 entry

Alias name: localhost
Creation date: Dec 29, 2025
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=localhost
Issuer: CN=localhost
Serial number: 7cd23b809f937152
Valid from: Mon Dec 29 15:50:44 GMT 2025 until: Sun Mar 29 15:50:44 GMT 2026
Certificate fingerprints:
         SHA1: 61:68:A4:62:D0:79:67:9F:35:A4:6A:E5:55:E6:FE:92:B7:22:21:1A
         SHA256: 66:BF:B2:98:97:BB:53:9F:27:1F:43:FB:C4:E3:5C:40:99:11:98:2B:79:A9:14:62:12:D8:8F:FE:1B:E9:57:7B
Signature algorithm name: SHA512WITHRSA
Subject Public Key Algorithm: 3072-bit RSA key
Version: 3


*******************************************

Generate a Local CA and Server Certificate (PEM)

To set up HTTPS using PEM files (instead of a keystore), follow the steps to create a local CA and sign a server certificate.

Generate a private key for the Certificate Authority (CA):

openssl genrsa -out myCA.key 4096
# Saves the key to the output file myCA.key
# Sets the key size to 4096 bits for extra security

Create a root self-signed CA certificate:

openssl req -x509 -new -nodes -key myCA.key \
 -sha256 -days 3650 -out myCA.crt  \
 -subj "/C=US/ST=Local/L=Local/O=MyOrg/OU=Dev/CN=MyLocalCA"

Generate a Server RSA private key for Keycloak:

openssl genrsa -out keycloak.key 2048
# Saves the key to the output file keycloak.key
# Sets the key size to 2048 bits for extra security

CSR for your Keycloak host (edit CN):

openssl req -new -key keycloak.key \
  -out keycloak.csr   \
  -subj "/C=US/ST=Local/L=Local/O=MyOrg/OU=Dev/CN=keycloak.local"

Create a file keycloak.ext containing certificate extension settings for a TLS certificate:

cat > keycloak.ext <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = keycloak.local
DNS.2 = localhost
EOF

Sign a Certificate Signing Request (CSR) with your CA:

openssl x509 -req -in keycloak.csr \
-CA myCA.crt -CAkey myCA.key -CAcreateserial \
-out keycloak.crt -days 825 -sha256 -extfile keycloak.ext

Certificate request self-signature ok
subject=C=US, ST=Local, L=Local, O=MyOrg, OU=Dev, CN=keycloak.local

Run ls to verify that the following certificates were created:
- CA: myCA.crt, myCA.key, myCA.srl
- Server (PEM): keycloak.crt, keycloak.key, keycloak.csr, keycloak.ext

Create a BCFKS Truststore (to trust your CA)

Import your CA into a BCFKS truststore:

Import CA into truststore

docker run --rm -v "$(pwd)":/tmp/keystore \
  --entrypoint keytool  \
  reg.mini.dev/keycloak-fips \
  -J-Djava.security.properties=/usr/share/conf/java.security.append  \
  -J-cp -J"/opt/keycloak/providers/*"  \
  -v   -keystore /tmp/keystore/truststore.bcfks  \
  -storetype bcfks   -providername CCJ  \
  -import   -file /tmp/keystore/myCA.crt  \
  -storepass "minimusstoretest2025"   -trustcacerts   -noprompt

Run Keycloak

To run in dev mode, deploy Keycloak in HTTP:

Run Keycloak in HTTP

docker run -d --rm -p 8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=minimusadmin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=minimusadminpass2025 \
reg.mini.dev/keycloak-fips \
start-dev --features=fips  --fips-mode=strict \
--https-key-store-password='minimusstoretest2025' \
--hostname=localhost   --log-level='INFO'

Visit the Keycloak console (UI) at http://localhost:8080.

Even in HTTP mode, FIPS checks still apply to admin and other passwords so ensure they have at least 14 characters.

To run in production, deploy Keycloak with the truststore in HTTPS:

Run Keycloak in HTTPS

docker run -d --rm -p 8443:8443 \
  -v "$(pwd)/keycloak.crt":/opt/keycloak/conf/tls.crt:ro \
  -v "$(pwd)/keycloak.key":/opt/keycloak/conf/tls.key:ro \
  -e KC_HTTPS_CERTIFICATE_FILE=/opt/keycloak/conf/tls.crt \
  -e KC_HTTPS_CERTIFICATE_KEY_FILE=/opt/keycloak/conf/tls.key \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=minimusadmin2025 \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=minimusadmin2025 \
  reg.mini.dev/keycloak-fips \
  start  --features=fips       --fips-mode=strict  \
  --https-key-store-password='minimusstoretest2025'  \
  --hostname=localhost       --log-level='INFO'

Visit the Keycloak console (UI) in HTTPS at https://localhost:8443.

Trust the CA locally (browser/curl)

sudo cp myCA.crt /usr/local/share/ca-certificates/myCA.crt
sudo update-ca-certificates

File hygiene

Change the file permissions in server.keystore so only the file owner has read/write access and nobody else has access:

chmod 600 *.key server.keystore *.bcfks || true

Troubleshooting

If you get an error password must be at least 112 bits, it means that one or more passwords is under 14 characters long. Passwords should be 16-24 characters. Check the passwords for the following variables: KC_BOOTSTRAP_ADMIN_PASSWORD, KC_HTTPS_KEY_STORE_PASSWORD, truststore password, etc.

Compliance

FIPS 140-3

Verify Images

Prerequisites

Deploy Keycloak for production

Troubleshooting

​Prerequisites

​Deploy Keycloak for production

​Troubleshooting

Prerequisites

Deploy Keycloak for production

Troubleshooting