Manage Keycloak compliance

Set password policies

By default, Keycloak has no policy on passwords, but this identity provider provides different password policies available through the Keycloak Admin Console, such as password expiration, minimum length, or special characters.

To set password policies, complete the following steps in the Keycloak Admin Console:

1. In the navigation menu, click Authentication.
2. Click the Password Policy tab.
3. In the Add policy list, select the policy that you want to apply.
4. Enter a Policy value corresponding to the policy that you selected.
5. Click Save.

After saving the policy, Keycloak enforces the policy for new users and sets an update password action for existing users to ensure that they change their password the next time they log in.

Configure two-factor authentication

Configure a browser authentication flow using X.509 user-signed certificates as a two-factor authentication method for Keycloak. After this method is set up, users must enter a username password and present an X.509 certificate for authentication.

Enable two-factor authentication

Perform the following steps in the Keycloak Admin Console:

1. In the navigation menu, click Authentication.
2. Click the Flows tab and select the Browser flow.
3. Click Copy and enter X.509 Browser as the name of the new flow.
4. In the X.509 Browser Forms execution row, click Actions and select Add execution from the list.
5. Select X509/Validate Username Form as the provider and click Save.
6. In the Requirement column, click the REQUIRED option.
7. In the X.509 Browser Forms execution row, click Actions and select config from the list.
8. In the Alias field, enter config.
9. In the User Identity Source field, select Subject's Common Name.

10. In the User Mapping Method field, select Username or Email and click Save.

    

11. On the Authentication page, click the Bindings tab and set the Browser Flow to X.509 Browser.

To generate a user certificate, you must use the CA certificate to sign one. You have two options:

• Use a certificate generated by Cert-Manager
• Use your own certificate

Use a certificate generated by Cert-Manager

To use a certificate generated by Cert-Manager, complete the following steps:

1. Create a ca.pem file with a CA certificate:

   kubectl get secret -n bundledidp bundledidp-keycloak-https-ca -o=jsonpath='{.data.tls\.crt}' | base64 --decode | cat > ca.pem
   

2. Create a ca.key file with a CA private key:

   kubectl get secret -n bundledidp bundledidp-keycloak-https-ca -o=jsonpath='{.data.tls\.key}' | base64 --decode | cat > ca.key
   

Use your own certificate

By default, Keycloak uses the certificate generated by the Cert-Manager to serve TLS traffic. This generated certificate is also used to sign the user certificate for the two-factor authentication. Alternatively, you can use your own certificate to replace the default certificate, which results in the following outcomes:

• Keycloak uses a customer's certificate to serve TLS traffic.
• Two-factor authentication is based on a user certificate signed by the customer CA certificate.

In this example, your CA certificate and key are named ca.pem and ca.key.

1. Generate a private key for Keycloak:

   export USER=keycloak
   export PASSWORD=PASSWORD
   
   openssl genrsa -aes256 -passout pass:${PASSWORD} -out keycloak.pass.key 4096
   openssl rsa -passin pass:${PASSWORD} -in keycloak.pass.key -out keycloak.key
   

2. Generate the certificate for Keycloak. This certificate is used to serve TLS traffic in Keycloak:

   openssl req -new -key keycloak.key -subj \
   "/CN=bundledidp"  \
   -out ${USER}.csr
   openssl x509 -req -days 3650 -in keycloak.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out keycloak.pem
   

3. Create a PKCS12 file from your Keycloak certificate and generate the keystore:

   openssl pkcs12 -export -in keycloak.pem -inkey keycloak.key -out keycloak.p12 -password pass:${PASSWORD}
   keytool -importkeystore -srckeystore keycloak.p12 \
           -srcstoretype PKCS12 \
           -destkeystore keystore.jks \
           -deststoretype JKS \
           -srcstorepass ${PASSWORD} \
           -deststorepass password
   

4. Import the CA certificate to the truststore of Keycloak:

   keytool -import -alias keycloak -keystore truststore.jks \
           -file ca.pem \
           -deststorepass password
   

5. Delete the original certificate and secret generated by Cert-Manager:

   kubectl delete certificate -n bundledidp bundledidp-keycloak-https-ca
   kubectl delete certificate -n bundledidp bundledidp-keycloak-https
   
   kubectl delete secret -n bundledidp bundledidp-keycloak-https-ca
   kubectl delete secret -n bundledidp bundledidp-keycloak-https
   

6. Create secrets which contain your CA certificate and jks file:

   kubectl create secret -n bundledidp generic bundledidp-keycloak-https-ca --from-file=tls.crt=ca.pem
   
   kubectl create secret -n bundledidp generic bundledidp-keycloak-https --from-file=keystore.jks=keystore.jks --from-    file=truststore.jks=truststore.jks
   

7. Restart the Keycloak Pod:

   kubectl delete pods bundledidp-keycloak-0 -n bundledidp
   

Generate the user certificate

The user certificate signing process happens outside of Keycloak. As long as a certificate is trusted by the CA imported to Keycloak in the previous steps and has the Common Name field matched with a user, that specific user can use the certificate as a second factor.

Generate the certificate with a script (recommended)

Here's an example of a script that generates the user certificate:

#!/bin/bash
echo "## This will generate a user certificate"

read -p 'Username (Not email): ' USER
read -sp 'Password: ' PASSWORD

echo "## Generating keys"
openssl genrsa -aes256 -passout pass:${PASSWORD} -out ${USER}.pass.key 4096
openssl rsa -passin pass:${PASSWORD} -in ${USER}.pass.key -out ${USER}.key

echo "## Creating CSR"
openssl req -new -key ${USER}.key -out ${USER}.csr -subj "/CN=${USER}/O=GDCH/C=US/ST=/OU=/L="

echo "## Signing CSR"
openssl x509 -req -days 3650 -in ${USER}.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out ${USER}.pem

echo "## Exporting PFX (PCKS12) Certificate"
echo "Next will ask you to enter the password for importing the certificate to the browser."
echo "Note the password in a safe place."
openssl pkcs12 -export -out ${USER}.pfx -inkey ${USER}.key -in ${USER}.pem

Generate the certificate manually (not recommended)

1. Generate a user private key:

   export USER=USER
   export PASSWORD=PASSWORD
   
   openssl genrsa -aes256 -passout pass:${PASSWORD} -out ${USER}.pass.key 4096
   openssl rsa -passin pass:${PASSWORD} -in ${USER}.pass.key -out ${USER}.key
   

2. Generate a user-signed certificate request:

   # Set your username as the "Common Name"
   openssl req -new -key ${USER}.key -out ${USER}.csr
   

3. Generate a PFX user certificate:

   openssl x509 -req -days 3650 -in ${USER}.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out ${USER}.pem
   # Next will ask you to enter the password for importing the certificate to the browser.
   # Note the password in a safe place.
   openssl pkcs12 -export -out ${USER}.pfx -inkey ${USER}.key -in ${USER}.pem
   

4. Upload the PFX user certificate to your browser. For example, in a Chrome browser, complete the following steps:

   1. Go to chrome://settings/certificates and click Import.
   2. Select the PFX certificate generated from the previous step and click Import.
   Note: When you are prompted to enter the password to import the certificate, use the one that you entered from the previous step.

5. Go to KEYCLOAK_ADDRESS/realms/gpc/account. In the prompt tab, select the certificate that you just imported and click OK:

   

6. Log in with your username and password and click Sign In:

   

7. Click Continue in the certificate window.

Set login attempt threshold

Keycloak has brute force detection capabilities and can temporarily disable a user account if the number of login failures exceeds a specified threshold. This threshold can be configured to block an account from login either temporarily or permanently.

To set up the brute force detection, complete the following steps in the Keycloak Admin Console:

1. In the navigation menu, click Realm Settings.
2. Click the Security Defenses tab.
3. Click the Brute Force Detection tab.
4. Turn Enabled to on.

5. Set values in the fields to match compliance requirements, such as the following:

   • Max Login Failures
   • Wait Increment
   • Quick Login check
   • Max Wait
   • Failure Reset time

   

Connect to the GDC air-gapped appliance audit logging system

Enable audit logging in Keycloak

To enable audit logging, use the Keycloak Admin Console to complete the following steps:

1. In the navigation menu, click Events.
2. Click the Config tab.
3. In the Login Events Settings and the Admin Events Settings sections, set the Save Events toggle to ON.
4. In the Expiration field, specify how long you want to keep events stored.
5. In the Saved Types field, specify the different actions that you consider important for auditing.
6. Click Save.
7. Click the Login Events tab to see audit logs about user account operations.
8. Click the Admin Events tab to see audit logs about any action that an admin performs within the admin console.

Connect Keycloak audit logs to GDC air-gapped appliance

Keycloak provides built-in Service Provider Interfaces (SPIs) to enable audit logging. Audit logging export is configured in Keycloak to store a duplicate of the audit logs as files in the Pod. By default the logs are stored in the database). The GDC air-gapped appliance logging system uses the volume mount to pick up the log and parse the logs automatically.

Change the Keycloak theme

A theme provides one or more types to customize different aspects of Keycloak. The types available are:

• Account - Account management
• Admin - Admin Console
• Email - Emails
• Login - Login forms
• Welcome - Welcome page

To change the Keycloak theme, follow these steps:

1. Log into the Keycloak Admin Console.
2. Select your realm from the drop-down list.
3. Click Realm Settings.
4. Click the Themes tab.
5. To set the theme for the master Admin Console, set the Admin Console theme for the master realm.
6. To see the changes to the Admin Console, refresh the page.

Root admin account management

Keycloak is bootstrapped with an initial root admin account with a trivial username and password of admin/admin. To ensure the protection and security of this root account, complete the following manual steps as soon as the bootstrapping is completed:

• Set up a strong password for the root admin account
• Set up 2FA for the root admin account

We recommend that you escrow the credential to the root admin account to a secure place.