Keycloak
Overview
Section titled “Overview”Keycloak is an open-source identity and access management solution.
Key features:
- SSO (Single Sign-On)
- Identity brokering
- User federation
- Fine-grained authorization
Installation
Section titled “Installation”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:
shc -t master install keycloakCommon variables:
admin_user- Admin username (default: admin)admin_password- Admin password (auto-generated)public_host- Public hostnamedb_vendor- Database type (default: postgres)
Configuration
Section titled “Configuration”Keycloak integrates with PostgreSQL via plug/socket:
shc -t master install keycloak # Auto-wires to postgresAccess admin console:
- URL: https://{public_host}/admin
- Username: {admin_user}
- Password: (from vault)
shc vault get keycloak/admin_password
Backup
Section titled “Backup”Keycloak backups include:
- Realm configurations
- User data (via PostgreSQL)
- Themes and customizations
Use converters for realm export:
shc backup create --stack iamRealms (VApps)
Section titled “Realms (VApps)”Create additional realms as VApps:
shc install keycloak/realm --into iam --instance my-realm \ --var realm_name=my-realm --var realm_display_name="My Realm"Browser sign-in with a Kerberos ticket
Section titled “Browser sign-in with a Kerberos ticket”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:
shc update keycloak -t master \ --var enableKerberos=true \ --var kerberosTenant=corpSet 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.
| Variable | Default | |
|---|---|---|
enableKerberos | false | The switch. Off sweeps Kerberos out of every realm. |
kerberosTenant | empty | The one tenant whose realm the KDC serves, [a-z0-9_-]+. |
kerberosRealm | empty | The Kerberos realm; empty means <TENANT>.LOCAL. |
kdcHost | empty | The host clients reach the KDC on; empty means the publicUrl host. |
deviceLoginGroups | empty | Groups whose members may sign in to a joined device. |
deviceLoginWithOtherTenants | false | Publish 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, spnegoHttpSeed | vault | The KDC’s own keys, 64 hex each, minted once. |
kerberosHostSuffix | empty | The 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 | /admin | Full group paths, comma-separated, whose members may join a computer and get its host keytab. Empty lets nobody. |
kdcLdapSeed | vault | The 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:
shc update keycloak -t master --expose 88=keycloak --expose 88+udp=keycloakIn 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.LOCALFor 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
kinitfails. 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
kinitdon’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.
Troubleshooting
Section titled “Troubleshooting”Common issues:
Problem: Admin console not accessible Solution: Check public_host configuration and Traefik labels
Problem: Database connection failed Solution: Verify PostgreSQL socket integration