Prerequisites¶

• Keycloak database created.
• OpenLDAP running, with the reader service account and the ou=People and ou=Groups branches ready.
• cert-manager and ingress in place, so keycloak.<BASE_DOMAIN> can be served over HTTPS.

Deploy¶

ansible-playbook -i /path/to/inventory --tags keycloak kubernetes.yml

Add DNS for keycloak.<BASE_DOMAIN> — a CNAME to the ingress is typical. An /etc/hosts entry will carry you through the configuration below, but it is not a deployment; fix DNS before anything else points at Keycloak.

secretGenerator:
- name: dbuser
  literals:
  - username=<USERNAME>
  - password=<GENERATED_SECRET>
- name: kcadmin
  literals:
  - username=<USERNAME>
  - password=<GENERATED_SECRET>
configMapGenerator:
- name: keycloak-config
  literals:
  - KEYCLOAK_HOSTNAME=keycloak.<BASE_DOMAIN>
  - KEYCLOAK_LOGLEVEL=INFO
  - DB_VENDOR=postgres
  - DB_ADDR=<DATABASE_HOST>
  - DB_PORT=5432
  - PROXY_ADDRESS_FORWARDING=true
  - JDBC_PARAMS=connectTimeout=21600
namespace: keycloak
resources:
- deployment.yaml
- service.yaml
generatorOptions:
  disableNameSuffixHash: true

kubectl apply -k ./base/ -n keycloak

Realm¶

Create a realm named for your site (<SITE>). It can take a few moments to appear; confirm it is selected as the current realm before continuing — the rest of this configuration silently lands in master otherwise.

Configure → Realm settings:

Leave everything else at its default, and save at the bottom of the page.

LDAP user federation¶

Configure → User federation → Add LDAP provider, with the realm selected:

Use Test connection and Test authentication before going further. A toast in the upper right reports the result; if either fails, nothing below will work.

LDAP searching and updating:

Synchronization:

Leave Kerberos integration off, cache settings at DEFAULT, and advanced settings off. Save.

LDAP mappers¶

Configure → User federation → (the LDAP provider) → Mappers → Add mapper. Three mappers are needed.

entitlement¶

Preserve Group Inheritance must be off because POSIX groups are flat; leaving it on makes the sync fail on groups that have no parent.

name¶

roles¶

Everything not listed can stay at its default.

Client scope mappers¶

The DE reads name and entitlement out of the token, so both have to be added to the profile client scope. Manage → Client scopes → profile → Mappers → Add mapper → By configuration:

Leaving Full group path on prefixes every group with /, and the DE's entitlement checks then match nothing.

Authentication¶

Configure → Authentication. Leave the Flows tab alone. In Required actions, enable exactly these and disable the rest:

• Terms and Conditions
• Update Password
• Update Profile
• Verify Email
• Delete Credential
• Linking Identity Provider
• Update User Locale

Realm roles¶

Manage → Realm roles, add:

Clients¶

Eight clients. Manage → Clients → Create client. The create wizard presents fields in a different order than the finished client page, so work from the tables below rather than from wizard step order, and re-check the client detail page when you are done.

Every client secret below is read from the Credentials tab on the client detail page and written into group_vars/all.yml in your private inventory.

Interactive clients¶

All three: client authentication on, authorization off, valid post logout redirect URIs +. Authentication flow: Standard flow and Direct access grants checked and nothing else — except vice-<SITE>, which also needs Service account roles.

VICE service clients¶

Their client IDs default to the names above, so only the secrets need setting:

Remaining service clients¶

After Keycloak¶

The client secrets you just collected are inputs to the phase that follows, so finish this document before running further playbooks. Next:

1. Generate service signing keys.
2. Apply configuration, ingress, networking, and NATS.

Related¶

• Authentication architecture
• OpenLDAP
• Keycloak database