Keycloak en producción

Todo el curso ha usado start-dev: HTTP, URL deducida de cada petición, admin de prueba. Aquí montas la tienda como en un servidor real, con HTTPS y un proxy delante, y ves qué cambia en los programas Go. Spoiler: casi nada, pero hay cuatro detalles que conviene no descubrir en producción.

1. Desarrollo frente a producción

2. La imagen optimizada

Algunas opciones de Keycloak son «de construcción»: la base de datos, si hay health y métricas… En desarrollo se aplican en cada arranque; en producción se fijan una vez al construir la imagen, y el servidor arranca con --optimized, más rápido y sin sorpresas.

# Keycloak «optimizado» para producción (lección 16): las opciones de build
# (base de datos, health, métricas) se fijan al construir la imagen, y el
# servidor arranca con «start --optimized», sin recompilarse en cada inicio.
FROM quay.io/keycloak/keycloak:26.8.0 AS builder
ENV KC_DB=postgres
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:26.8.0
COPY --from=builder /opt/keycloak/ /opt/keycloak/
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

3. Hostname, proxy y TLS

# Caddy termina TLS y pasa las peticiones a Keycloak por la red interna.
# «tls internal»: Caddy crea su propia CA y un certificado para localhost.
# En un servidor real pondrías tu dominio y Caddy pediría el certificado a
# Let's Encrypt (o usarías el de tu empresa).
https://localhost:8443 {
	tls internal
	reverse_proxy keycloak:8080
}

# La tienda con un Keycloak «como en producción» (lección 16). Solo cambia la
# infraestructura: el realm, los usuarios y el AD de prueba son los del paso.
#
#   cd infra/produccion
#   docker compose up -d --build
#   docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
#
# Keycloak queda en https://localhost:8443 (a través de Caddy). Su puerto
# 8080 y el de gestión (9000) no se publican: solo los ve la red interna.
services:
  ad:
    image: instantlinux/samba-dc:4.23.10-r0
    hostname: dc1
    cap_add: [SYS_ADMIN]
    environment:
      REALM: tienda.local
      WORKGROUP: TIENDA
      NETBIOS_NAME: DC1
      DOMAIN_ACTION: provision
      BIND_INTERFACES_ONLY: "no"
    secrets: [samba-admin-password]
    volumes:
      - ad-etc:/etc/samba
      - ad-lib:/var/lib/samba
      - ../ad/0globals.conf:/etc/samba/conf.d/0globals.conf:ro

  ad-seed:
    image: instantlinux/samba-dc:4.23.10-r0
    entrypoint: ["sh", "/seed.sh"]
    environment:
      AD_ADMIN_PASSWORD_FILE: /run/secrets/samba-admin-password
    secrets: [samba-admin-password]
    volumes:
      - ../ad/seed.sh:/seed.sh:ro
    depends_on: [ad]

  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
    env_file: secretos/produccion.env   # POSTGRES_PASSWORD
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"]
      interval: 5s
      timeout: 3s
      retries: 10

  keycloak:
    build: .
    command: start --optimized --import-realm
    environment:
      # URL pública: la que ven navegadores y programas, y la que va en «iss».
      KC_HOSTNAME: https://localhost:8443
      # TLS lo termina Caddy: Keycloak escucha HTTP solo en la red interna y
      # se fía de las cabeceras X-Forwarded-* que pone el proxy.
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      # Admin temporal para el primer arranque: crea uno permanente y bórralo.
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
    # KC_DB_PASSWORD y KC_BOOTSTRAP_ADMIN_PASSWORD: fuera de este archivo.
    env_file: secretos/produccion.env
    volumes:
      - ./realm:/opt/keycloak/data/import:ro
    extra_hosts:
      - "host.docker.internal:host-gateway"
    healthcheck:
      # La imagen no trae curl: preguntamos a /health/ready (puerto de gestión)
      # con bash y miramos el código HTTP: 200 = listo, 503 = aún no. (Buscar
      # «UP» en el cuerpo no sirve: los checks internos dicen UP antes.)
      test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/9000 && printf 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && head -1 <&3 | grep -q ' 200 '"]
      interval: 10s
      timeout: 5s
      retries: 30
      start_period: 30s
    depends_on:
      postgres:
        condition: service_healthy
      ad-seed:
        condition: service_completed_successfully

  caddy:
    image: caddy:2.11.7-alpine
    ports:
      - "127.0.0.1:8443:8443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
    depends_on:
      keycloak:
        condition: service_healthy

secrets:
  samba-admin-password:
    file: ../ad/admin-password

volumes:
  pgdata:
  ad-etc:
  ad-lib:
  caddy-data:

Los realms, con la URL pública

Dos cosas de los realms dependen de la URL de Keycloak: el proveedor de la empresa (lección 12) y la redirect URI de tienda-broker. tools/realm/produccion.py deriva los realms de producción de los de desarrollo cambiando solo lo que ve el navegador y el issuer; las llamadas de servidor a servidor (token, JWKS, logout) siguen por http://localhost:8080 dentro del contenedor. Probado: la empresa funciona igual detrás del proxy.

4. Lo que cambia en los programas Go

El issuer y la CA

Solo cambia una variable: OIDC_ISSUER=https://localhost:8443/realms/tienda (y KEYCLOAK_URL=https://localhost:8443 en admin-tool). Pero Go tiene que confiar en el certificado. Caddy crea su propia CA (tls internal); en un servidor real sería Let's Encrypt o la CA de tu empresa. Sin confiar en ella, salida real:

tls: failed to verify certificate: x509: certificate signed by unknown authority

Timeouts

go-oidc y x/oauth2 usan http.DefaultClient si no les das otro, y ese cliente no tiene timeout: si Keycloak deja de responder, cada login se queda colgado para siempre. Ambas librerías toman el cliente del contexto:

// Sin timeout, una petición a un Keycloak que no responde se queda
// colgada para siempre. go-oidc y x/oauth2 toman el cliente del contexto.
client := &http.Client{Timeout: 10 * time.Second}
ctx = oidc.ClientContext(ctx, client)
provider, err := oidc.NewProvider(ctx, cfg.Issuer)

// withClient añade al contexto el cliente HTTP con timeout para que x/oauth2 y
// go-oidc lo usen al hablar con Keycloak.
func (a *Auth) withClient(ctx context.Context) context.Context {
	return oidc.ClientContext(ctx, a.httpClient)
}

tienda-web lo usa en el canje del código, la renovación y userinfo. En api-pedidos basta con dárselo a NewProvider: lo vimos en el código de go-oidc, que guarda el contexto (sin su cancelación) para refrescar el JWKS cuando Keycloak rota las claves.

Cookies Secure

El paso 3 dejaba un comentario: «// Secure: true, // obligatorio en producción (HTTPS)». Ahora se decide solo: si la URL pública de tienda-web es https://, sus cookies llevan Secure. Probado con OIDC_REDIRECT_URL=https://tienda.example/callback:

Set-Cookie: tienda_state=I7LPYMNONBJT4DLFLUXIX7BHWA; Path=/callback; Max-Age=600; HttpOnly; Secure; SameSite=Lax

Secretos sin valor por defecto

Desde la lección 3, los secretos tienen un valor por defecto «solo para desarrollo». El riesgo es que lleguen a producción sin que nadie lo note. config.Secret lo impide:

// Package config lee la configuración de los programas de la tienda desde
// variables de entorno (lección 16).
package config

import (
	"log"
	"os"
)

// Env devuelve la variable de entorno key o, si no está, def.
func Env(key, def string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return def
}

// Production indica si el programa corre en producción (TIENDA_ENTORNO=produccion).
func Production() bool { return os.Getenv("TIENDA_ENTORNO") == "produccion" }

// Secret lee un secreto. En desarrollo usa devDefault si falta; en producción
// se niega a arrancar: un secreto «de ejemplo» en producción es peor que un error.
func Secret(key, devDefault string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	if Production() {
		log.Fatalf("falta %s: en producción los secretos no tienen valor por defecto", key)
	}
	return devDefault
}

$ TIENDA_ENTORNO=produccion go run ./cmd/web
falta OIDC_CLIENT_SECRET: en producción los secretos no tienen valor por defecto

5. Probarlo

cd tienda/pasos/paso-15/infra && docker compose down -v          # libera el AD de desarrollo
cd ../../paso-16/infra/produccion
docker compose up -d --build
docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt

cd ../..                                  # tienda/pasos/paso-16
export SSL_CERT_FILE=$PWD/infra/produccion/caddy-root.crt
export TIENDA_ENTORNO=produccion OIDC_ISSUER=https://localhost:8443/realms/tienda
go run ./cmd/api &
OIDC_CLIENT_SECRET=tienda-web-secret go run ./cmd/web &
OIDC_CLIENT_SECRET=facturacion-secret go run ./cmd/facturacion &

cd ../../..                               # course/
go -C tools/comprobar run . -paso 16 -keycloak https://localhost:8443 -servicios
# … las 18 comprobaciones en verde, ahora por HTTPS
# Todo en orden para el paso 16.

O todo de una vez, como hace la verificación del curso: tools/ci/verificar-produccion.sh (salida real: «✔ producción verificada (paso 16)», en algo más de un minuto). Comprueba también que desde fuera no se llega ni al 8080 ni al 9000.

Las métricas siguen ahí, para tu Prometheus, en el puerto de gestión (dentro de la red de Docker): /metrics devuelve, por ejemplo, keycloak_credentials_password_hashing_validations_total.

6. Antes de abrirlo al mundo

Lo que este paso no hace (y conviene repasar en tu despliegue). Son puntos de la documentación de Keycloak, no probados en el curso salvo donde se indica:

• Admin permanente. KC_BOOTSTRAP_ADMIN_* crea un admin temporal (el aviso amarillo de la consola). Crea uno de verdad, con segundo factor, y borra el temporal.
• Secretos de verdad. secretos/produccion.env lleva valores de ejemplo para que el curso funcione. En un despliegue real, los secretos del orquestador, un gestor como Vault o el config keystore de Keycloak. Keycloak no lee variables *_FILE como la imagen de PostgreSQL.
• Importar el realm, solo la primera vez. --import-realm salta los realms que ya existen; los cambios posteriores, con el aprovisionador de la lección 10 o una herramienta declarativa.
• Copias de seguridad de PostgreSQL: ahí está todo (usuarios, sesiones, claves de firma).
• Más de un nodo. Varias réplicas de Keycloak comparten caché; consulta la guía de alta disponibilidad de tu versión antes de escalar.
• Logs en JSON para tu sistema de logs: KC_LOG_CONSOLE_OUTPUT=json (probado: cada línea pasa a ser un objeto JSON).
• Protección contra fuerza bruta en el realm (Realm settings → Security defenses) y tiempos de vida de tokens y sesiones revisados.

Ejercicios

Errores comunes