Skip to content
SHC Docs

Keycloak

Keycloak is an open-source identity and access management solution.

Key features:

  • SSO (Single Sign-On)
  • Identity brokering
  • User federation
  • Fine-grained authorization

shc init installs SHC’s own Keycloak into the master tenant, SHC’s own tenant, and it runs nowhere else. To add it later, on a cluster whose shc init --modules-config left it out, name that tenant:

Terminal window
shc -t master install keycloak

Common variables:

  • admin_user - Admin username (default: admin)
  • admin_password - Admin password (auto-generated)
  • public_host - Public hostname
  • db_vendor - Database type (default: postgres)

Keycloak integrates with PostgreSQL via plug/socket:

Terminal window
shc -t master install keycloak # Auto-wires to postgres

Access admin console:

  • URL: https://{public_host}/admin
  • Username: {admin_user}
  • Password: (from vault) shc vault get keycloak/admin_password

Keycloak backups include:

  • Realm configurations
  • User data (via PostgreSQL)
  • Themes and customizations

Use converters for realm export:

Terminal window
shc backup create --stack iam

Create additional realms as VApps:

Terminal window
shc install keycloak/realm --into iam --instance my-realm \
--var realm_name=my-realm --var realm_display_name="My Realm"

A machine that logs in to the directory holds a Kerberos ticket, and the browser can sign in to Keycloak with it (SPNEGO), with no password prompt. The password form stays for every machine without a ticket.

One tenant per estate gets Kerberos, because the system Keycloak’s KDC serves one realm. Two variables on the system Keycloak turn it on, off by default:

Terminal window
shc update keycloak -t master \
--var enableKerberos=true \
--var kerberosTenant=corp

Set them in master’s platform config (modules.keycloak.vars), where no tenant admin can reach. The update restarts Keycloak, and publicUrl must be set: a browser asks for HTTP/<the host it signs in on>. The Kerberos realm is the tenant upper-cased plus .LOCAL (CORP.LOCAL); kerberosRealm names another. A tenant whose realm doesn’t exist yet is skipped with SHCKRBNOREALM and arms at the next keycloak update.

VariableDefault
enableKerberosfalseThe switch. Off sweeps Kerberos out of every realm.
kerberosTenantemptyThe one tenant whose realm the KDC serves, [a-z0-9_-]+.
kerberosRealmemptyThe Kerberos realm; empty means <TENANT>.LOCAL.
kdcHostemptyThe host clients reach the KDC on; empty means the publicUrl host.
deviceLoginGroupsemptyGroups whose members may sign in to a joined device.
deviceLoginWithOtherTenantsfalsePublish device_login on a domain other tenants also route, when kerberosTenant is one of them. Off, a domain shared by several tenants gets none.
kdcKrbtgtSeed, kdcKadminSeed, spnegoHttpSeedvaultThe KDC’s own keys, 64 hex each, minted once.
kerberosHostSuffixemptyThe DNS name a joined computer’s host/<name>.<suffix> principal sits under. Empty means devices. plus the publicUrl host’s parent, devices.corp.bitspur.com for auth.corp.bitspur.com. It never has to resolve. Joining needs enableLdap, but the suffix reaches vKDC whenever enableKerberos is on, because its startup purge drops every joined computer outside it. Changing it un-joins every computer.
kerberosHostEnrollGroups/adminFull group paths, comma-separated, whose members may join a computer and get its host keytab. Empty lets nobody.
kdcLdapSeedvaultThe key of the directory’s ldap/<publicUrl host> principal, which joined computers bind to with GSSAPI.

The keycloak-spnego job adds a shc-kerberos user storage component to the tenant’s realm, removes it from every other, and puts the browser flow’s Kerberos step at ALTERNATIVE ahead of any identity-provider redirect. The KDC’s own keys come from the three seeds, so nothing about them is in Keycloak’s database; the image writes the HTTP keytab to the container’s /tmp tmpfs at every start. Rotating a seed in the vault and updating keycloak invalidates every ticket at once. vKDC signs in as the master client vkdc, whose service account holds that client’s kerberos-dc role alone, and no admin of any realm can read a key.

Clients reach the KDC on port 88, which the package declares and never publishes. Publish it yourself, both transports:

Terminal window
shc update keycloak -t master --expose 88=keycloak --expose 88+udp=keycloak

In tofu that’s shc_stack_ports for keycloak with "88" and "88/udp". A container in a tenant never reaches 88 over the fabric.

Publish it on a private route only, and keep it off public interfaces. Clients need, in krb5.conf:

[libdefaults]
rdns = false
dns_canonicalize_hostname = false
[domain_realm]
.example.com = CORP.LOCAL

For TCP alone, add udp_preference_limit = 1. kdc = tcp/host is Heimdal’s spelling, and MIT reads it as a literal host name.

  • Kerberos keys derive from the cleartext password, AES only, in the tenant’s realm only, so a person who hasn’t signed in with a password since Kerberos came on has none and their kinit fails. One password sign-in in a browser fixes that. Every other realm stores no key, and each start deletes any it finds there.
  • A disabled, deleted or brute-force-locked user gets no ticket.
  • The KDC doesn’t report a failed preauth to Keycloak’s brute-force protection, so wrong passwords at kinit don’t lock the account.
  • A ticket signs in the existing local user of the same name. Nobody is imported or created, and removing the component touches no user.
  • A ticket sign-in finishes the browser flow, so it skips any second factor set on the password form.

Common issues:

Problem: Admin console not accessible Solution: Check public_host configuration and Traefik labels

Problem: Database connection failed Solution: Verify PostgreSQL socket integration