Learn Keycloak - Keycloak Configuration

#Introduction

In episode 19 you successfully installed Keycloak and made sure the database is connected. Episode 20 is about tuning that instance so it's ready to use: per-realm settings, client settings, authentication flows, password policies, SMTP for transactional email, and configuration behind a reverse proxy. This is the episode that touches the admin console the most.

#Realm Settings

Almost all settings live in the Realm Settings menu and apply per realm. Here are its main categories.

#General Settings

Contains the realm name, alias, and display mode. The realm name determines part of the URL — id.example.com/realms/myrealm — so choose a name that stays stable and consistent from the start.

#Login Settings

This section controls login behavior: whether users can self-register (registration), the forgot password button, email verification, and remember me. The Default groups setting from episode 18 is also here.

#Keys (Realm Keys)

Keycloak signs tokens with a key pair managed per realm. Three key types are common:

The RSA key pair is generated automatically when the realm is created. Rotation and new key generation are done from the Keys tab.

#Email Configuration (SMTP)

SMTP is needed for password reset emails, account verification, and notifications. It can be configured via the Email tab in the admin console or via environment variables:

SMTP configuration via environment variables

KC_SMTP_HOST=smtp.example.com
KC_SMTP_PORT=587
KC_SMTP_FROM=no-reply@example.com
KC_SMTP_AUTH=true
KC_SMTP_USERNAME=noreply
KC_SMTP_PASSWORD=rahasia
KC_SMTP_STARTTLS=true

Always test with the "test connection" feature and send a real password reset email after configuring SMTP — this is the path that most often fails in production.

#Themes

Determines the login, account, admin, and email themes per realm. Full details are in episode 21.

#Localization

Sets the default language and available languages for login pages and emails. Combine with a custom message bundle so your preferred language is truly used.

#Security Defenses

Configures security headers (Content-Security-Policy, X-Frame-Options, and others) as well as brute force detection. This will be covered in depth in episode 24.

#HTTPS and Reverse Proxy

When Keycloak is installed behind a reverse proxy terminating TLS, tell it via KC_PROXY. The edge mode means TLS is terminated at the proxy, and Keycloak reads the forwarded headers:

Keycloak behind a reverse proxy

KC_PROXY=edge
KC_HOSTNAME=id.example.com
KC_HOSTNAME_STRICT=true

Without this setting, Keycloak can infer the protocol incorrectly and produce redirects with an HTTP scheme.

#Client Settings

Clients represent the applications that use Keycloak. Their important settings:

#Client ID

The unique identifier of the application, e.g. webapp or mobile-api. The client ID appears in the authorization URL and in tokens.

#Access Type

Historically Keycloak recognized three access types; recent versions simplify them into the Client authentication toggle:

Server-side applications use confidential; SPAs and mobile apps use public so the secret doesn't leak into the browser.

#Valid Redirect URIs

The list of URIs allowed as redirect destinations after login, e.g. https://app.example.com/callback. Wildcards are available, but being too loose risks open redirect — register URIs explicitly whenever possible.

#Web Origins (CORS)

Origins allowed for cross-origin requests, e.g. https://app.example.com. This is important for public clients so the browser doesn't block calls to Keycloak endpoints.

#Protocol

OIDC or SAML. Most modern applications use OIDC (based on OAuth2 and JWT); SAML is retained for legacy integrations.

#Fine Grain OpenID Connect Configuration

Advanced settings for OIDC: token signature algorithm, response mode, and claim shape in userinfo. Adjust to the application's needs, not just defaults.

#Authentication Flows

An authentication flow is the sequence of steps a user goes through. Several built-in flows:

To see the flow list from the terminal: kcadm.sh get authentication/flows -r myrealm. Custom flows for OTP and WebAuthn will be used in episode 23.

#Password Policies

Password policies are set in Realm Settings → Authentication → the Policies tab and apply to the entire realm:

A common production combination: length 12, all character classes, history 5, and blacklist active. Don't forget these policies only apply to passwords, not to other authentication factors.

#Closing

In episode 20, you tuned Keycloak: realm settings (general, login, keys, email, themes, localization, security defenses), client settings (ID, access type, redirect URIs, CORS, protocol, fine grain OIDC), authentication flows, password policies, plus SMTP and reverse proxy for production.

Key takeaways:

• KC_PROXY=edge for deployments behind a reverse proxy — without it the protocol can be detected incorrectly.
• Password policy is set per realm; combine length, history, and blacklist.
• Choose client authentication according to the application type: confidential for backends, public for SPAs.
• Test the password reset flow after configuring SMTP — don't wait until production to discover it.

In the next episode (episode 21), you'll change Keycloak's look so it doesn't feel generic: Themes & Customization — login, account, admin, email, and welcome themes.