Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Deployment and Operations

Production Configuration

Configure Keycloak for production: kc.sh start vs start-dev, hostname, TLS, reverse proxy headers, the build step, option precedence, environment variables and admin hardening.

Running kc.sh start-dev is perfect on a laptop and wrong for a public server. Development mode disables HTTPS requirements, relaxes the hostname rules, and caches little. Production mode is stricter by design: it refuses to start without a hostname and a way to serve HTTPS, and it expects a real database. This lesson covers the settings every production deployment needs and how Keycloak's configuration sources fit together.

Keycloak cannot run on this site. Commands and options below match recent Keycloak (Quarkus distribution) releases, but option names do change, so confirm them against the guide for your version. The TryIt blocks are stand-ins that resolve configuration and check a deployment sketch.

Start and build

The server has two phases:

  • Build: kc.sh build bakes in build-time options (database vendor, enabled features, health and metrics endpoints) so startup is fast.
  • Start: kc.sh start runs the server. It performs an automatic build if needed; kc.sh start --optimized skips it and assumes you built earlier.

Build-time options include --db, --features, --health-enabled, --metrics-enabled, and --cache. Changing one later needs a rebuild. Runtime options such as the database URL, hostname, and proxy settings can change per start. In containers, run kc.sh build in a Dockerfile stage and kc.sh start --optimized as the entrypoint.

The essentials

A production start usually sets:

Terminal
bin/kc.sh start --optimized \
  --hostname=auth.example.com \
  --http-enabled=true \
  --proxy-headers=xforwarded \
  --db=postgres \
  --db-url=jdbc:postgresql://db.internal:5432/keycloak \
  --db-username=keycloak \
  --db-password="$DB_PASSWORD"

What each does:

  • hostname: the public URL host (in newer versions you can give a full URL such as https://auth.example.com). Keycloak uses it to build issuer, redirect, and email links, so the iss claim in every token depends on it. Changing it later invalidates configured clients and cached tokens.
  • TLS: either terminate TLS in Keycloak with --https-certificate-file and --https-certificate-key-file, or terminate at a reverse proxy and let Keycloak speak HTTP internally with --http-enabled=true. Never expose HTTP to the internet.
  • proxy-headers: xforwarded or forwarded. They tell Keycloak to trust headers set by your proxy for client address, scheme, and host. Only enable them when Keycloak is reachable only through that proxy, otherwise clients can forge their IP.
  • db: production needs an external database (PostgreSQL is the most common choice). Never use the embedded dev database in production.
  • Management port: health and metrics are served on a separate management interface (port 9000 by default in recent versions), not on the public port. Keep it internal.

Option sources and precedence

You can supply the same option four ways. When several are set, Keycloak applies this order, highest first:

  1. Command-line argument (--hostname=...)
  2. Environment variable (KC_HOSTNAME=...)
  3. conf/keycloak.conf file (hostname=...)
  4. Built-in default

Environment variable names are the option name upper-cased, dashes replaced by underscores, and prefixed with KC_: db-url becomes KC_DB_URL. Secrets such as the DB password should come from environment or a secrets store, not from a file committed to Git. Keycloak also supports a vault for secrets referenced inside realm configuration.

JS Stand-in: resolve options and map env names

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

No output.

Reverse proxy and headers

A common layout is internet, load balancer or reverse proxy (nginx, HAProxy, a cloud load balancer), then Keycloak. The proxy must:

  • Terminate TLS with a valid certificate.
  • Pass X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host.
  • Forward only the paths you want public: expose /realms/ and /resources/, usually /admin/ only to a restricted network, and never /metrics or /health to the internet.
  • Keep timeouts generous enough for login flows.

A sample nginx location sketch (read-only; adjust to your environment):

NGINX
server {
  listen 443 ssl;
  server_name auth.example.com;

  location /realms/    { proxy_pass http://keycloak:8080; include /etc/nginx/proxy-headers.conf; }
  location /resources/ { proxy_pass http://keycloak:8080; include /etc/nginx/proxy-headers.conf; }
  location /admin/     { allow 10.0.0.0/8; deny all; proxy_pass http://keycloak:8080; }
  location /metrics    { return 404; }
}

First-start tasks

On the very first start, create the initial admin through KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD (older versions used KEYCLOAK_ADMIN). Then:

  1. Log in to the master realm admin console, create a real admin user with a strong password and MFA, and remove or disable the bootstrap account.
  2. Create your own realm(s); never use master for applications.
  3. Set SSL required to external requests or all requests for each realm (Realm settings > General).
  4. Configure email (Realm settings > Email) so verification and password reset work.
  5. Restrict who can reach the admin console.

A pre-flight check

Run a little script against your intended configuration before deploying. Here is the idea:

JS Stand-in: pre-flight check for a deployment sketch

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

No output.

Logging and secrets

  • Use JSON logging (--log-console-output=json) when logs go to a collector.
  • Set --log-level=info; raise a single category (for example org.keycloak.events:debug) temporarily instead of debug everywhere.
  • Never log secrets; check that tokens, passwords, and client secrets are not echoed.
  • Keep secrets in a manager (Kubernetes secrets, cloud secret store, vault), not in images.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the purpose of kc.sh build followed by start --optimized?

    Build-time options are baked into the distribution, then optimized start skips the rebuild.
  2. 2. Which source wins when a command-line argument and an environment variable set the same option?

    Precedence is CLI, then environment, then keycloak.conf, then defaults.
  3. 3. Why must proxy headers only be trusted behind a real proxy?

    Trusting forwarded headers from the open internet lets attackers lie about the source of requests.
  4. 4. What environment variable corresponds to the option db-url?

    Option names are upper-cased, dashes become underscores, and the KC_ prefix is added.

Summary

  • Use build then start --optimized in production; never start-dev.
  • Hostname, TLS or a trusted proxy, and an external database are mandatory.
  • Option precedence: CLI, environment, keycloak.conf, defaults.
  • Keep health, metrics, and the admin console off the public internet.
  • Replace the bootstrap admin and set realm SSL requirements.

Next: Database and Clustering