Setting up Keycloak

Prerequisites

Access and Organisation

• Request a new host and subdomain from the Infra administrator.
• Set up a redirect to the new Keycloak host.
• Ensure you have permissions to access the Keycloak admin console and the GitLab repository for realm generation.

Hardware / VM Requirements

• Virtual machine with a minimum of 512 MB RAM.

Time synchronisation

For all components (Keycloak, MIDGARD, ASGARD, etc.) to work together correctly, the time has to be synchronized. To achieve this, ensure that NTP is installed and configured on all affected environments.

Configuration Details

Docker compose parameters (Keycloak)

Parameters to review in docker-compose.yml:

• KC_HOSTNAME_URL: https://auth.quintessence.de
  
• KC_HOSTNAME_ADMIN_URL: https://auth.quintessence.de
• KEYCLOAK_ADMIN: admin username, currently 'admin'
• KEYCLOAK_ADMIN_PASSWORD: admin password
• Ports: adjust as needed to match your reverse proxy or exposure model

OAuth parameters (MG, KR, EOS, TOP)

Common parameters expected in oauth.properties:

• oauthHost: DNS name or IP address of the Keycloak host
• oauthPort: Keycloak port
• jsonWebKeysPath: path to Keycloak public key (JWKS) for the realm
• scope: application scope required by the SP (for example, midgard)
• minKidReloadTimeInSeconds: minimum interval to reload the public key
• audience: audience that SP validates; recommended to use the top-level domain
• issuer: full HTTPS issuer URL to the realm

Version-specific addition (new Keycloak versions):

• useHttps: set to true when using HTTPS and port 443

ASGARD configuration parameters

asgardConfig.groovy snippet to enable bearer token validation:

asgard {
security {
oauth {
oauthHost = System.getenv('security.oauth.oauthHost') ?: "10.0.58.1"
oauthPort = System.getenv('security.oauth.oauthPort') ?: "8180"
jsonWebKeysPath = "/realms/quintessence/protocol/openid-connect/certs"
scope = "asgard"
minKidReloadTimeInSeconds = "3600"
audience = "quintessence"
issuer = "http://keycloak-server.quintessence.net:8180/realms/quintessence"
}
}
}

For new Keycloak versions, add and adjust:

oauthHost = System.getenv('security.oauth.oauthHost') ?: "qckcldev-qcint.quintessence.de"
oauthPort = System.getenv('security.oauth.oauthPort') ?: "443"
useHttps = System.getenv('security.oauth.useHttps') ?: "true"

File location: quintessence-asgard-custom-{customer}/custom/{customer}/{environment}/apps/qc/asgard/conf/asgardConfig.groovy

Step-by-Step Setup

Step 1: Install and start Keycloak

Download the existing package (example):

keycloak-22.0.5_qc-10.77-SNAPSHOT.tar.gz

Place the package in the required directory and unpack it.

Adjust docker-compose.yml to set the hostname URLs, admin credentials, and ports as described in Configuration Details → Docker Compose parameters.

Start the container:

docker compose up -d

Step 2: Plan realms and IdP configuration

Create a realm for each environment: MIDGARD (MG), KRONOS AS (KR), KRONOS PH (EOS), Tour Operator Portal (TOP).

Important

ASGARD reuses MIDGARD's user management. No additional realm configuration in Keycloak is needed for ASGARD.

Step 3: Generate realm configuration from template

Clone the repository. Groovy must be installed on the host where the Realm generation script is executed.

git clone https://gitlab.quintessence.net/net.quintessence.security/keycloak-ressources

Run the script with the required parameters. The command differs by Keycloak version. Contact the Core Team if you are unsure which version is installed.

Keycloak v22 (example):

./src/main/resources/scripts/create_realm_from_template.sh \
-c "dtf" \
-e "qcdev" \
-a "mg" \
-i "10.10.109.50:8080"
-v "22"

Keycloak v26 (example):

./src/main/resources/scripts/create_realm_from_template.sh \
-c "dtf" \
-e "qcdev" \
-a "mg" \
-d "mgdtfdev"
-v "26"

Parameters:

• -c: customer short name (e.g., ew, lh, a3).
• -i: IP:Port of the MG / KR / EOS / TOP server (for example, 10.10.109.50:8080).
• -e: environment (qcdev, qctest, test, stage, qcref, prod).
• -a: application name (mg, kr, eos, top).
• -d: domain part of the URL (for example, prod.ew.internal.quintessence.de)
• -v: keycloak version.

Step 4: Import the realm

1. Open the Keycloak admin console.
2. In the dropdown menu, select Create realm.
3. Select Import file and upload the generated file.

Step 5: Create Client Credentials

1. Log in to the Keycloak admin console: https://auth.quintessence.de/admin/master/console.
2. In the upper left corner, select a realm from the drop-down menu.
3. From the left-hand navigation menu, select Clients > Keycloak and go to the Credentials tab.
4. Ensure "Client Authenticator" is set to Client Id and Secret (default).
5. At Client secret, select Regenerate to generate a password.
6. Copy the generated password.
7. From the left-hand navigation menu, select User Federation and select qc-user-provider.
8. Insert the password and save.

Step 6: Configure Password Policies

1. Log in to Keycloak and select the target realm.
2. In the left-hand menu, select Authentication.
3. On the main screen, go to the Policies tab, then Password policy.
4. Add a new policy by clicking Add policy, then Regular expression.
5. In the regex field, enter:

^[a-zA-Z0-9!";#$%&'()*+,-.:;<=>?@^_`{|}~]*$

After adding the regex, click Save and wait for the confirmation message Password policies successfully updated.

Step 7: Configure mail

1. From the left-hand navigation menu, select Realm Settings > Email.
2. Configure the fields as required. The field From is mandatory; recommended value: keycloak@quintessence.net.
3. Set up SMTP and authentication.
4. Test connection.
5. Save.

Step 8: Configure MG, KR, EOS, and TOP to acknowledge Keycloak

This activates validation of bearer tokens for these applications. Configure oauth.properties for each environment as described in Configuration Details for OAuth parameters.

Important

Ensure oauth.properties ends with a trailing empty line. Missing the final newline can cause the last property to be ignored.

oauthHost=internal DNS- or IP- address to Keycloak
oauthPort=Keycloak port
jsonWebKeysPath=path to Keycloak public key
scope=application | The app will validate if the token contains this predefined scope
minKidReloadTimeInSeconds=Min time to reload the public key
audience=SPs universe, recommended to use the top-level domain
issuer=https address to the realm / configuration of

Example (DTF DEV):

oauthHost=10.0.58.1
oauthPort="8180"
jsonWebKeysPath=/realms/dtfdev/protocol/openid-connect/certs
scope=midgard
minKidReloadTimeInSeconds="3600"
audience=quintessence
issuer=https://auth.quintessence.de/realms/dtfdev

For new Keycloak versions add:

oauthHost=qckcldev-qcint.quintessence.de
oauthPort="443"
useHttps=true

File location: quintessence-midgard-custom-{customer}/custom/{customer}/{environment}/apps/qc/{application}/conf/oauth.properties

Step 9: Configure ASGARD to acknowledge Keycloak

Enable bearer token validation in asgardConfig.groovy as described in Configuration Details for ASGARD configuration parameters

Validation & Testing

Check the status of the container:

docker ps -a

Admin console reachable at the configured hostname, for example:

https://auth.quintessence.de

Realm imported and visible. SMTP test passes in Realm Settings → Email → Test connection.

JWKS reachable:

https:///realms//protocol/openid-connect/certs

Application token validation works using the configured audience and issuer.

---

Proceed with: Activating QC SSO Login in Flight Deck

Changelog

Date	Author	Message
2026-03-06	aresnikowa	qc-0: postediting
2026-03-04	aresnikowa	qc-0: postediting
2026-03-04	aresnikowa	QC-47927: aligned with the template, mkDocs formatting alignment
2026-02-25	aresnikowa	QC-50171: in Keycloak folder, adjusted admonitions