Keycloak SSO Integration

Prev Next

Overview

This guide provides step-by-step instructions for integrating Keycloak Single Sign-On (SSO) with the Glasswall Halo platform in an offline (air-gapped), on-premises environment.

It assumes you’ve already deployed the Single Node Halo platform (e.g., on VMs via Proxmox or ESXi) and now want to enable OIDC-based SSO using Keycloak.

You’ll learn how to:

  • Set up a Keycloak server with HTTPS in an offline environment (using a preloaded container image or manual VM installation).
  • Import and customize the provided glasswall-realm.json Keycloak configuration.
  • Configure TLS certificates and DNS/host resolution for both Keycloak and Halo.
  • Deploy the Halo Portal and related services:
    • cdrplatform-portal
    • cdrplatform-portalaccess
    • cdrplatform-api-access

Glasswall Halo's Keycloak SSO Integration Guide

Prerequisites

Environment Requirements

  • This setup is intended for air-gapped or strictly on-premises environments.
  • The Single Node Halo cluster must already be deployed.
  • Internal DNS resolution must be in place, either via a local DNS server or manually through /etc/hosts entries.
  • Keycloak must be installed locally on a host or virtual machine.
    → Keycloak Documentation & Installation

Required Resources

  • A pre-configured realm file (glasswall-realm.json), provided by Glasswall Support.
  • Local access to Halo Helm charts for deployment within the Single Node Halo cluster.

DNS / Hosts configuration

Ensure the hostname for your Keycloak server is resolvable by both client machines and Halo platform components.

  • With internal DNS: Create an A record for keycloak.dev.local pointing to the Keycloak server’s IP address.
  • Without internal DNS: Add the following entry to the hosts file on each machine that needs access:

Step 1 - Configuring Keycloak for Glasswall Halo SSO

Glasswall provides a Keycloak realm configuration (as a JSON file) that defines the realm, clients, roles, and scopes needed for Halo's SSO.

You can import this configuration to avoid manual setup. In an offline setup, do this via the Keycloak Admin UI.

1.1 - Importing the Glasswall realm configuration

a. Obtain the realm export: You should have a file named glasswall-realm.json. This file contains the realm settings for Halo's SSO.

Glasswall realm summary

The Glasswall realm includes the following preconfigured items:

  • Realm ID: glasswall

  • Clients

    • halo-portal-client
    • halo-api-access
    • halo-portal-access

  • Key roles

    • Realm-level: Admin, User
    • Client-level: Halo client Admin and User roles.
    • Client Scopes (pre-configured with mappers):
    • PortalUserScope: Necessary claims (roles, email) to tokens.

  • Token lifespan

    • SSO Session Idle Timeout: 30 mins

  • Authentication: Standard username/password.

b. Log into Keycloak admin
- Using a web browser, navigate to the Keycloak admin console at https://<KEYCLOAK_HOST>:8443/ and log in with the master admin account.

01_keycloak

c. Import the realm.

  • In the admin console select the dropdown that currently shows "Master" and click Create Realm.

02_keycloak

  • From the Create Realm screen, select Import, and upload the glasswall-realm.json file.

03_keycloak

  • Keycloak will parse the file and populate the realm name (e.g., glasswall).
    • Confirm the import.

04_keycloak

d. Verify realm settings

  • After import, review key settings and ensure:
    • Realm name is glasswall.
    • Realm is enabled.
    • SSL Required: likely set to external.
    • Clients should include:
      • halo-portal-client
      • halo-portal-access
      • halo-api-access

05_keycloak

1.2 Customizing client settings (hostnames and redirect URIs)

Next, for each of the Halo clients, update config for your environment.

halo-portal-client (Frontend)

06_keycloak

  • Redirect URIs: https://halo.dev.local/authentication/*
  • Web Origins: https://halo.dev.local
  • Root URL (optional): https://halo.dev.local
  • Logout Redirect: https://halo.dev.local/authentication/logout-callback

07_keycloak

halo-portal-access (Backend)

  • Copy and save the Client Secret.
    • Redirect URIs: https://halo.dev.local/*
    • Web Origins: https://halo.dev.local

halo-api-access

  • Leave redirect settings as-is, and save each client’s settings.

08_keycloak

1.3 Creating users and assigning roles

Now you'll create users and assign Halo roles.

09_keycloak

a. In the glasswall realm, navigate to Users → Add User.
b. Fill in the username and details.
c. In Credentials section, set a password and uncheck "Temporary".
d. In Role Mappings, assign:

  • Realm roles:
    • Admin
    • User
  • Client roles:
    • halo-portal-client [admin, user]
    • halo-api-access [admin, user]
    • halo-portal-access [admin, user]

10_keycloak

An Admin user sees:

11_keycloak

And can manage:

12_keycloak

Including:

13_keycloak

Step 2 - TLS certificates and DNS considerations

Ensure proper TLS trust and DNS for all components.

2.1 TLS Trust

Halo platform services (Portal, Portal-Access, API-Access) must trust Keycloak’s certificate.

2.2 DNS and /etc/hosts

Ensure:

  • Keycloak hostname resolves for all services and users
  • Halo domains resolve as well

Step 3 - Deploying Halo services with Keycloak SSO (Helm configurations)

Halo is deployed via Helm; offline environments use charts bundled with the system.

Deploy Halo Portal

helm upgrade --install cdrplatform-portal ./cdrplatform-portal \
  --set image.tag="<IMAGE_TAG>" \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain="<PORTAL_DOMAIN>" \
  --set ingress.tls.secretName="<TLS_SECRET>" \
  --set configuration.BackendUrl="https://<PORTAL_DOMAIN>" \
  --set configuration.HaloVersion="2.9.0" \
  --set configuration.EnabledPages="SystemSettings,PolicySettings,ValidationSettings" \
  --set configuration.OIDC.ProviderOptions.Authority="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall" \
  --set configuration.OIDC.ProviderOptions.ClientId="halo-portal-client" \
  --set configuration.OIDC.ProviderOptions.RedirectUri="https://<PORTAL_DOMAIN>/authentication/login-callback" \
  --set configuration.OIDC.ProviderOptions.PostLogoutRedirectUri="https://<PORTAL_DOMAIN>/authentication/logout-callback" \
  --set configuration.OIDC.ProviderOptions.Scope="openid profile api://cdrplatform-portal-access/PortalUserScope" \
  --set configuration.OIDC.ProviderOptions.SilentCheckSsoRedirectUri="https://<PORTAL_DOMAIN>/silent-check-sso.html" \
  --set appenvironment.HTTP_CSP_FRAME_SRC="'self' https://<KEYCLOAK_DOMAIN>:8443 https://<PORTAL_DOMAIN>/silent-check-sso.html" \
  --set appenvironment.HTTP_CSP_CONNECT_SRC="'self' https://<KEYCLOAK_DOMAIN>:8443" \
  --set configuration.Authentication__Schemes__Bearer__RequireHttpsMetadata=true \
  --set configuration.Authentication__Schemes__Bearer__MetadataAddress="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall/.well-known/openid-configuration" \
  --set configuration.Logging__LogLevel__Keycloak="Debug"

Deploy Portal-Access

helm upgrade --install cdrplatform-portal-access ./cdrplatform-portal-access \
  --set image.tag="<IMAGE_TAG>" \
  --set ingress.tls.domain="<PORTAL_DOMAIN>" \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName="<TLS_SECRET>" \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://cdrplatform-portal-access" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__Authority="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__RequireHttpsMetadata=true \
  --set configuration.Authentication__Schemes__Bearer__MetadataAddress="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall/.well-known/openid-configuration" \
  --set configuration.Authentication__Schemes__Bearer__JwksUri="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall/protocol/openid-connect/certs"

Deploy API-Access

helm upgrade --install cdrplatform-api-access ./cdrplatform-api-access \
  --set image.tag="<IMAGE_TAG>" \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName="<TLS_SECRET>" \
  --set ingress.tls.domain="<PORTAL_DOMAIN>" \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://cdrplatform-api-access" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__Authority="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__RequireHttpsMetadata=true \
  --set configuration.Authentication__Schemes__Bearer__MetadataAddress="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall/.well-known/openid-configuration" \
  --set configuration.Authentication__Schemes__Bearer__JwksUri="https://<KEYCLOAK_DOMAIN>:8443/realms/glasswall/protocol/openid-connect/certs"

3.1 Post-deployment checklist

  • Ensure that the pods are running (no CrashLoopBackOff).
  • Also check that the logs show successful Keycloak OIDC config.

14_keycloak

Step 4 - Validation and testing SSO Integration

15_keycloak

4.1 Browser login test

a. Launch the Halo portal.
b. Get redirected to Keycloak login.

16_keycloak

c. Sign in to your account.

17_keycloak

d. Return to Halo after being authenticated.

18_keycloak

Step 5 - Troubleshooting

Misconfigured redirect URI

Check URIs match between portal and Keycloak.

Clock skew

Sync system clocks.

TLS trust errors

Ensure Halo trusts Keycloak’s cert.

References