Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Concepts and Setup

Configuring the Keycloak Server: keycloak.conf, Env Vars and CLI

Configure Keycloak with CLI arguments, KC_ environment variables and keycloak.conf, understand precedence, secrets, hostname, HTTP, database, logging and health settings.

A Keycloak server is configured with options: hostname, ports, database, logging and more. The same option can be given in several places, and knowing which place wins saves hours of "why is my setting ignored?". This lesson explains the sources, the naming rules, the important option groups and how to inspect the result.

Three places, one option

Take the HTTP port. You can set it three ways:

Terminal
# 1. command-line argument
bin/kc.sh start --http-port=8180

# 2. environment variable
export KC_HTTP_PORT=8180

# 3. conf/keycloak.conf
http-port=8180

Rules for the names:

  • CLI: --option-name=value, lowercase with dashes.
  • Environment: KC_ + the name in upper case with underscores, so http-port becomes KC_HTTP_PORT.
  • File: option-name=value, one per line, # for comments.

Precedence from highest to lowest: command-line arguments, environment variables, conf/keycloak.conf, defaults. If the same option appears in two places, the higher source wins. The file is best for stable server settings, environment variables for container deployments and secrets, and CLI arguments for one-off overrides.

Option groups you will use

Group Examples
Hostname hostname, hostname-admin, hostname-strict
HTTP and TLS http-enabled, http-port, https-port, https-certificate-file, https-certificate-key-file
Proxy proxy-headers (xforwarded or forwarded), http-enabled behind TLS termination
Database db (build), db-url, db-username, db-password, db-pool-max-size
Features features, features-disabled (build)
Cache cache (ispn default, or local for a single node), cache-stack
Observability health-enabled, metrics-enabled, http-management-port
Logging log (console,file), log-level (for example INFO,org.keycloak:debug), log-console-output=json

Run bin/kc.sh start --help for the list, or add --help-all for everything. The official All configuration page documents each option and marks build-time ones.

A realistic keycloak.conf

PROPERTIES
# conf/keycloak.conf
hostname=https://id.example.com
http-enabled=false
https-certificate-file=${kc.home.dir}conf/server.crt.pem
https-certificate-key-file=${kc.home.dir}conf/server.key.pem

db=postgres
db-url=jdbc:postgresql://db.internal:5432/keycloak
db-username=keycloak

health-enabled=true
metrics-enabled=true

log=console
log-console-output=json
log-level=INFO

Notice what is missing: db-password. Keep secrets out of files you commit to Git.

Secrets

Three safe options:

  1. An environment variable such as KC_DB_PASSWORD supplied by your orchestrator (Docker secrets, Kubernetes Secrets).
  2. A vault reference. Keycloak can read secrets from a Kubernetes-style directory using --vault=file --vault-dir=/opt/keycloak/vault; then in the configuration you refer to ${vault.db_password} style expressions in realm settings.
  3. A value in keycloak.conf with the file readable only by the service account.

Never put passwords in command lines on shared machines (they appear in the process list).

Hostname in one paragraph

The hostname is the public base URL Keycloak puts in tokens (iss), redirects and emails. In Keycloak 26 you give a full URL: --hostname=https://id.example.com. If a reverse proxy is in front, add the proxy settings (--proxy-headers=xforwarded) and let it terminate TLS with --http-enabled=true. A mismatch between what the browser sees and what Keycloak believes is the number-one cause of broken redirects and "invalid issuer" errors in apps. The deployment chapter of this course returns to it with a proxy diagram.

Inspect the effective configuration

Terminal
bin/kc.sh show-config

prints every option with the value and where it came from (CLI, env, file, default), which settles precedence arguments instantly. Passwords are masked.

Realm import at start and the data/import folder

Besides server options, you can load realm definitions at start. Put my-realm.json into data/import/ and run bin/kc.sh start-dev --import-realm; existing realms are skipped. In containers, mount a folder at /opt/keycloak/data/import.

Options as code (stand-in)

This runnable stand-in resolves options from the three sources with the real precedence rules and explains the origin of each value, just like show-config does. It is an illustration, not Keycloak code.

Node.js Stand-in: resolve option precedence

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run it and read the from column: the port is cli (8083) because the command line beats the environment (8082) and the file (8081).

A config linter (stand-in)

Before you start a production server, check its settings against a short list of common mistakes. This stand-in lints a settings object.

Node.js Stand-in: lint production settings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Common mistakes

  • Changing a build-time option (such as db) only in keycloak.conf after build and then starting with --optimized. Rebuild when build options change.
  • Setting a hostname with http:// and then wondering why browsers block mixed content.
  • Using KC_ names with dots or dashes. The environment form uses underscores only.
  • Putting http-enabled=true on an internet-facing server with no proxy in front.
  • Forgetting that start-dev ignores several production checks, so a config that works in dev may fail with start.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. If http-port is 8081 in keycloak.conf, KC_HTTP_PORT is 8082 and --http-port=8083 is on the command line, which port is used?

    CLI arguments beat environment variables, which beat keycloak.conf, which beats defaults.
  2. 2. What is the environment-variable name for the option db-username?

    Prefix KC_, upper case, dashes replaced by underscores.
  3. 3. Which command prints the effective configuration and its sources?

    show-config lists every option, its value and where the value came from.
  4. 4. Where is the safest place for a database password in a container deployment?

    Orchestrator secrets keep the value out of your repository and process lists.

Summary

  • Options come from CLI arguments, KC_ environment variables and conf/keycloak.conf, in that order of priority.
  • Names map mechanically: http-port is --http-port and KC_HTTP_PORT.
  • Know the groups: hostname, HTTP/TLS, proxy, database, features, cache, observability, logging.
  • Keep secrets out of files and command lines; use env vars, vault or orchestrator secrets.
  • show-config reveals the effective value and its source; rebuild when build-time options change.

Next: Your First Realm, User and Client