Configure DCA Hardened Identity Provider — for Keycloak™

On this page: Installed version · First-boot credentials · Log in · Replace the bootstrap administrator · Network access · Database and single-node design · Data and logs · Upgrades · Backup and restore

Installed version

Keycloak 26.8.0 — the upstream server distribution, verified when the image was built three ways (a pinned sha256, Maven Central's .sha256 for the same artifact, and the release's GPG signature from the Keycloak Bot key), unpacked in /opt/keycloak and owned by the keycloak user. It runs in production mode (kc.sh start --optimized) on Ubuntu's OpenJDK 21 (openjdk-21-jre-headless) under keycloak.service; the build options were baked once with kc.sh build. Base OS: Ubuntu 24.04 LTS. Image built 2026-10-07; every build is gated on zero fixable HIGH or CRITICAL vulnerability findings.

sudo -u keycloak /opt/keycloak/bin/kc.sh --version

First-boot credentials

No administrator, realm or realm key ships in the image. On this VM's first boot, keycloak-firstboot.service generates a bootstrap administrator before Keycloak first starts; Keycloak then creates the master realm — with its own signing keys — and that administrator. keycloak-verify-firstboot.service proves the administrator gets a token from the running server and a wrong password is refused, then deletes the bootstrap environment file.

Log in

1. Connect with gcloud compute ssh INSTANCE_NAME --zone ZONE --tunnel-through-iap. The deployment package enables OS Login, so IAM decides who can SSH in; reading the credential files needs sudo, which OS Login grants to principals with the OS Admin Login role (roles/compute.osAdminLogin). IAP TCP forwarding needs a firewall rule that allows 35.235.240.0/20 to tcp:22 on the VM's network — the deployment package does not create one.
2. Open an SSH session that forwards the console port, and read the administrator credential in it:

   gcloud compute ssh INSTANCE_NAME --zone ZONE --tunnel-through-iap -- -L 8080:127.0.0.1:8080
   sudo cat /root/keycloak-admin-credentials.txt

3. On your workstation, open http://localhost:8080/admin/ and sign in to the master realm as admin. Plain HTTP is fine here because the tunnel ends on the VM's loopback; Keycloak refuses admin sign-in over plain HTTP from non-local addresses (the master realm requires SSL for external requests).

Replace the bootstrap administrator

Keycloak treats an administrator created this way as a temporary (bootstrap) admin, and the credential file says the same: sign in, create a permanent administrator, then delete or re-password admin.

1. In the master realm open Users → Add user, give the new administrator a username, and create it.
2. On its Credentials tab, set a password with Temporary turned off.
3. On its Role mapping tab, assign the master realm role admin.
4. Sign out, sign in as the new user, then delete the admin user — or give it a new password you keep elsewhere.

Network access

Option A — HTTPS on the VM (port 8443)

1. Get a certificate for the hostname your users and applications will use, and install it (full chain) and its key where the keycloak user can read them:

   sudo install -d -o root -g keycloak -m 0750 /etc/keycloak/tls
   sudo install -o root -g keycloak -m 0640 fullchain.pem /etc/keycloak/tls/tls.crt
   sudo install -o root -g keycloak -m 0640 privkey.pem  /etc/keycloak/tls/tls.key

2. Edit /opt/keycloak/conf/keycloak.conf with sudo. These are runtime options, so no kc.sh build is needed. Change the existing http-enabled and http-host lines rather than adding second copies:

   https-certificate-file=/etc/keycloak/tls/tls.crt
   https-certificate-key-file=/etc/keycloak/tls/tls.key
   https-port=8443
   hostname=https://idp.example.com:8443
   http-enabled=false
   http-host=0.0.0.0

3. Restart, and check the log for the HTTPS listener. Once a certificate is configured, the management interface on 9000 serves HTTPS too, so the health check becomes curl -fsSk https://127.0.0.1:9000/health/ready:

   sudo systemctl restart keycloak
   sudo journalctl -u keycloak -n 40 | grep -i listening

4. Open the port with the deployment package's firewall toggle: in its Networking section, tick "Allow TCP port 8443 traffic from the Internet" and enter your clients' CIDR ranges under "Source IP ranges for TCP port 8443 traffic". The toggle creates one VPC firewall rule, DEPLOYMENT-tcp-8443, allowing tcp:8443 from those ranges to VMs tagged DEPLOYMENT-deployment (DEPLOYMENT is your deployment name; the VM is DEPLOYMENT-vm). Use the narrowest ranges that work — 0.0.0.0/0, which the field shows only as a format example, would publish the port through the VM's external IP. Already deployed without the toggle? Create the same rule yourself:

   gcloud compute firewall-rules create DEPLOYMENT-tcp-8443 \
     --network NETWORK --direction INGRESS --allow tcp:8443 \
     --source-ranges 10.10.0.0/24 --target-tags DEPLOYMENT-deployment

5. Sign in at https://idp.example.com:8443/admin/ from an allowed range.

http-host sets the address of every Keycloak listener — HTTPS and the management interface on 9000 as well — so with 0.0.0.0 the health endpoints also answer on the VM's internal IP. The deployment package opens only 8443.

Option B — behind an HTTPS load balancer or reverse proxy

Terminate TLS in front of Keycloak and tell Keycloak about the proxy with proxy-headers=xforwarded (or forwarded) and hostname=https://idp.example.com. The proxy must reach Keycloak's HTTP port, so set http-host to an address it can reach and allow that port from the proxy's source ranges only — the deployment package's toggle covers 8443, not 8080.

Database and single-node design

The shipped keycloak.conf uses db=dev-file — Keycloak's embedded H2 file database, in /opt/keycloak/data/h2 — and cache=local, so this is a single node with no cluster traffic. Keycloak's own guidance for production is an external database. To move to PostgreSQL:

1. Stop Keycloak and export your realms and users:

   sudo systemctl stop keycloak
   sudo -u keycloak /opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/export

2. In keycloak.conf set db=postgres plus db-url, db-username and db-password.
3. db, cache, health and features are build options and the service starts with --optimized, so rebuild before starting:

   sudo -u keycloak /opt/keycloak/bin/kc.sh build
   sudo -u keycloak /opt/keycloak/bin/kc.sh import --dir /opt/keycloak/data/export
   sudo systemctl start keycloak

Data and logs

Upgrades

• Recommended: export your realms (above), deploy the newest image version, and import them there with kc.sh import while its service is stopped. The new VM creates its own bootstrap administrator on first boot; importing your master realm brings your own administrators across.
• In place: Keycloak is not an apt package on this image, so neither apt nor unattended-upgrades (enabled, for Ubuntu's updates including OpenJDK 21) ever changes it. Back up /opt/keycloak/data, unpack the newer, verified distribution next to /opt/keycloak, copy conf/keycloak.conf and data/ across, run kc.sh build as keycloak, and switch over; Keycloak migrates its database on the new version's first start. Read Keycloak's upgrading guide first.

Backup and restore

Stop keycloak and copy /opt/keycloak/data (the H2 database), or snapshot the boot disk. kc.sh export (service stopped) also gives a portable JSON copy of realms and users that kc.sh import restores.

Monitoring

• Health: curl -fsS http://127.0.0.1:9000/health/ready → status UP — wire this into an uptime check or your monitoring agent.
• The deployment package disables the Cloud Logging and Monitoring agents in instance metadata (google-logging-enable=0, google-monitoring-enable=0), and the image pre-installs no monitoring agent. Install the Google Cloud Ops Agent if you want logs and metrics in Cloud Logging and Cloud Monitoring; nothing phones home by default.

More: install · troubleshooting · security notes · support card. Questions: support@dcassociatesgroup.com — first response within 1 business day.

Keycloak™ names the open-source software this image packages. Derek Coleman & Associates Inc is not affiliated with or endorsed by the Keycloak project.