菜单
Operate, configure, deploy, secure, and integrate with Keycloak (open-source IAM) — the modern Quarkus distribution (24.x–26.6.x), the Keycloak Operator with `Keycloak` and `KeycloakRealmImport` CRDs, and realm/client/identity-provider configuration.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use this skill when authoring, reviewing, or fixing a vLLM Kubernetes manifest, Docker/Podman pod, or OpenShift ServingRuntime — even when the user does not say "vllm". Triggers on: lab cluster performance practices, cache mount + survival across pod restarts (/root/.cache, VLLM_CACHE_ROOT, TORCHINDUCTOR_CACHE_DIR, TRITON_CACHE_DIR, "do we have caches saved"), HF_TOKEN secret in pod env, liveness + readiness probe tuning (initialDelaySeconds, failureThreshold, "pod takes 12 min to boot"), serve_args review, --enforce-eager rationale, MoE deployment ("ep2 dp2", --enable-expert-parallel, expert-parallel sizing), TP/PP sizing, ConfigMap parser-plugin mount, image tag selection, cold-boot reduction, multi-node LWS + Ray, control planes (llm-d, production-stack, AIBrix, NVIDIA Dynamo, KServe), KEDA autoscaling, GAIE routing, disaggregated prefill/decode (Nixl/Mooncake/LMCache/MORI-IO), RHAIIS on OpenShift (SCC, arbitrary UID, Routes 60s, ModelCar, air-gapped). Lead with operator intent, not vendor names.
Autoresearch loop for Claude Code skills — greedy keep/discard hill climbing on a 10-dimension quality rubric, with blind subagent validation for self-scoring bias, plus a `freshen` mode that probes external references (release notes, docs, deprecation signals) and applies verified updates, plus a `trigger` mode that measures and tunes the skill's frontmatter description until it reliably fires when it should and stays silent when it shouldn't (60/40 train/test split, 3 runs/query, blinded test scores).
Migrate Redis deployments (especially Bitnami Redis Helm charts in Sentinel HA mode) to Valkey on Kubernetes, including fully air-gapped clusters. Core knowledge: the RDB-version wall (Valkey replicates/loads only from Redis ≤ 7.2.x; Redis 7.4+ writes RDB v12 which Valkey rejects; Valkey 9 writes its own v80 — a one-way door), the two transfer layers (version-bound REPLICAOF/DUMP-RESTORE vs version-agnostic logical replay with RedisShake or rdb-cli), a side-by-side cutover runbook, Valkey chart selection (groundhog2k / CloudPirates / official valkey-io tradeoffs), Bitnami-redis→valkey values translation, consumer-app reconnection (Sentinel discovery, master-set names, frozen redis_version 7.2.4), Prometheus exporter continuity, air-gap tool/image mirroring, and Argo CD source rewiring away from charts.bitnami.com. Part of the bitnami-exit suite.
Vet an open-source product for air-gap readiness BEFORE adoption. Answers eight questions — telemetry, does-opt-out-actually-work, proxy-in-disguise over a hosted API, runtime downloads, custom-CA support, feature-level content egress / offline degradation, day-two sustainment (feed mirroring, staleness), and a 4-grade verdict (air-gap-native / possible-with-mirror / proxy-in-disguise / no-go). Two-pass: static grep of source + container image (bundled fingerprint tables work offline), then an optional dynamic harness (--network=none, egress deny+log, mitmproxy CA injection, faketime). Writes AIRGAP-VETTING.json + .md. Use for any "should we adopt X?" question in a disconnected environment, not just when the user says "air gap".
Triage a batch of raw security findings. Verify each is real, collapse duplicates, re-rank by impact-on-asset x exploitability, and tag with an owner. Takes a directory or file of scanner output and writes TRIAGE.json + TRIAGE.md sorted by what actually needs engineering attention. Use when asked to "triage findings", "validate scanner output", "prioritize vulns", or "review the backlog". Runs interactively by default; pass --auto to skip the interview.
Generate candidate fixes for verified security findings. Consumes TRIAGE.json (preferred), VULN-FINDINGS.json, or an execution-harness results directory. Static-analysis input gets a per-finding patch subagent + an independent reviewer and is written as inert diffs for human review; results-directory input from an external execution harness (the defending-code reference pipeline, if installed) is delegated to its verified build→reproduce→regress→re-attack patch ladder. Writes PATCHES/bug_NN/{patch.diff,patch_result.json}, PATCHES.md, and PATCHES.json. Use when asked to "fix the findings", "patch these vulns", "generate fixes", or "close the loop on triage".
| name | keycloak-iam |
| description | Operate, configure, deploy, secure, and integrate with Keycloak (open-source IAM) — the modern Quarkus distribution (24.x–26.6.x), the Keycloak Operator with `Keycloak` and `KeycloakRealmImport` CRDs, and realm/client/identity-provider configuration. |
| when_to_use | Use whenever the user mentions Keycloak, Red Hat build of Keycloak (RHBK), `kc.sh`, `kcadm.sh`, `keycloak.conf`, `KC_*` / `KCRAW_*` env vars, the Keycloak Operator, a `Keycloak` or `KeycloakRealmImport` custom resource, or asks about server tuning (hostname / proxy / db / cache flags, `--optimized` builds), Kubernetes deployment (HA topology, probes, zero-downtime upgrades), security hardening (FGAP v2, client policies, FAPI, DPoP, JWT-Authz-Grant, federated client auth, redirect URI safety, CVEs), OIDC/SAML/IdP brokering with Keycloak as the IdP, LDAP/AD federation, themes / custom SPIs, or operations (Prometheus metrics, OTLP tracing, realm export/import, backup, upgrade matrix). In a thread already established as Keycloak-focused, keep triggering on follow-up realm/client/IdP/SSO questions even when "Keycloak" isn't repeated in every message. Do NOT trigger on generic IAM/SSO/OIDC questions with no Keycloak context (e.g. Auth0, Okta, Entra ID, Cognito, or a from-scratch OAuth server). |
This skill covers running, configuring, deploying, and integrating with Keycloak, the open-source identity & access management server. It targets the modern Quarkus-based distribution (24.x → 26.6.x as of May 2026; the legacy WildFly distribution was removed years ago). Information is current as of Keycloak 26.6.2 (released May 2026).
The Red Hat build of Keycloak (RHBK) is downstream of upstream Keycloak with longer support windows and the same surface area; advice here applies to both unless explicitly noted.
Keycloak is a large product. Don't try to load everything — route to one or two reference files based on what the user is asking, then go deep.
references/
├── server-config.md → CLI/env vars, kc.sh, kcadm.sh, hostname, db, cache,
│ TLS/proxy, logging, features, bootstrap-admin, KCRAW_
├── k8s-deployment.md → Operator install, Keycloak CR, KeycloakRealmImport,
│ raw manifests, HA topology, probes, autoscaling
├── security-hardening.md → Realm policies, brute force, FGAP v2, client policies
│ (FAPI/OAuth 2.1), DPoP, redirect URI safety, recent CVEs
├── integration.md → OIDC/SAML flows, IdP brokering, LDAP/AD federation,
│ themes, SPIs, admin clients (Java/JS/kcadm/Terraform)
├── observability.md → Metrics, OTLP tracing, structured logging, health
│ probes, troubleshooting recipes
└── upgrade-and-backup.md → Upgrade matrix, zero-downtime patches, realm
export/import, DB backup, disaster recovery
Routing cheatsheet:
| User question | Read first |
|---|---|
| "How do I set the hostname / proxy / DB?" | server-config.md |
| "Why is my login redirecting in a loop?" | server-config.md (hostname/proxy) |
| "How do I deploy Keycloak on Kubernetes?" / "Operator vs raw manifests" | k8s-deployment.md |
"Show me a Keycloak CR" / "What goes in spec.*?" | k8s-deployment.md + assets/examples/ |
| "How do I do zero-downtime upgrades?" | k8s-deployment.md + upgrade-and-backup.md |
| "Harden my realm" / "FAPI / OAuth 2.1 / DPoP / FGAP" | security-hardening.md |
| "Recent CVEs?" / "Is 26.x.y vulnerable?" | security-hardening.md §CVE table |
| "Wire my SPA / mobile app / service to Keycloak" | integration.md |
| "Configure SAML / OIDC IdP / LDAP / social login" | integration.md |
| "Custom theme / authenticator / event listener / mapper" | integration.md §SPIs / §Themes |
| "What metrics / Grafana dashboard / Prometheus / OTLP" | observability.md |
| "Realm export gotchas" / "How do I back up?" / "Liquibase migration stuck" | upgrade-and-backup.md |
When in doubt about a CLI flag, the source of truth is https://www.keycloak.org/server/all-config (full option index). When in doubt about a CR field, the source of truth is the CRD YAML in keycloak-k8s-resources at the version tag (see §"Authoritative sources" below).
Latest stable: Keycloak 26.6.2 (released 2026-05-19). 26.6.2 is a security-fix batch — operators on 26.6.0/26.6.1 should upgrade. Do not quote specific CVE IDs from memory; pull the authoritative list with gh api repos/keycloak/keycloak/security-advisories and gh release view 26.6.2 --repo keycloak/keycloak --json body. See security-hardening.md §CVE table for how to surface the current set.
Notable changes through the 26.x line:
| Version | Key changes (operator-relevant) |
|---|---|
| 26.6.x | Workflows, JWT Authorization Grant, Federated client auth, Zero-downtime patch updates, KCRAW_ env prefix, automatic K8s truststore, graceful HTTP shutdown, configurable Service name/port in Operator, organization groups, sensitive-info redaction in HTTP access logs. 26.6.2 (2026-05-19) is a security-fix batch — see the advisory feed for the CVE set it closes |
| 26.5.x | Token Exchange Standard (RFC 8693) GA, declarative-user-profile GA, FIPS via Bouncy Castle, ECC keys default for new realms, Java 25 added (server image still on JDK 21 for FIPS) |
| 26.4.x | hostname-v2 GA + hostname-v1 removed, Quarkus 3.20 LTS, --proxy-headers (replaces `--proxy edge |
| 26.3.x | Organizations GA, Account Console v3 GA, Admin UI on PatternFly React, FGAP v2 preview |
| 26.2.x | OIDC client policies v2, persistent user sessions GA |
| 26.0.0 | KEYCLOAK_ADMIN removed → KC_BOOTSTRAP_ADMIN_*, persistent user sessions on by default, hostname-v2 by default |
Always cross-check with the release-notes body via gh release view <tag> --repo keycloak/keycloak --json body --jq '.body'. Do not rely solely on this table — bump the date and verify.
When the user asks about something specific, prefer these sources over generic recall. Cited paths are relative to repo root — access via a local clone, or fetch via gh api repos/<owner>/<repo>/contents/<path>.
Upstream source (keycloak/keycloak)
quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/*PropertyMappers.javaquarkus/config-api/src/main/java/org/keycloak/config/*Options.javaoperator/src/main/java/org/keycloak/operator/themes/src/main/resources/theme/ + js/apps/{account-ui,admin-ui}/docs/guides/server/*.adoc, docs/guides/operator/*.adoc, docs/guides/high-availability/*.adocOperator install manifests (keycloak/keycloak-k8s-resources)
26.6.2) with three files under kubernetes/:
keycloaks.k8s.keycloak.org-v1.yml — the Keycloak CRDkeycloakrealmimports.k8s.keycloak.org-v1.yml — the KeycloakRealmImport CRDkubernetes.yml — Operator Deployment + RBAC + ServiceAccountmain branch has only the README + LICENSE; the actual manifests live in tags. Use git checkout <tag> against a clone, or gh api repos/keycloak/keycloak-k8s-resources/contents/kubernetes?ref=<tag> to fetch raw. (Do NOT assume the repo is stale just because main looks empty.)Online docs: https://www.keycloak.org/
/server/all-config — every CLI option, every default/server/configuration — concept overview, build-time vs runtime/operator/installation, /operator/basic-deployment, /operator/advanced-configuration, /operator/realm, /operator/keycloak-cr, /operator/rolling-updates/high-availability/ — multi-cluster, external Infinispan, CloudNativePG recipe/securing-apps/ — OIDC layers, SAML, DPoP, JWT-Authz-Grant, MCP authorization server (CIMD)/docs/<version>/server_admin/ and /docs/<version>/server_development/ — admin and SPI guidesgh CLI (per the user's gh-cli-preferred rule):
gh release view <tag> --repo keycloak/keycloak --json body --jq '.body'gh issue view <N> --repo keycloak/keycloakgh search issues --repo keycloak/keycloak "<query>"gh api repos/keycloak/keycloak/security-advisoriesWhen the user references a specific behavior, check the source clone or CRD YAML before answering — option names, defaults, and JSON field names get renamed across releases (e.g. --proxy edge|reencrypt|passthrough → --proxy-headers xforwarded|forwarded in 26.4; KEYCLOAK_ADMIN → KC_BOOTSTRAP_ADMIN_* in 26.0; the hostname-v2 rewrite). Stale answers are worse than "let me check."
These are the things that bite operators most. Don't suggest a Keycloak deployment that violates them without a stated reason.
kc.sh build before start --optimized in a custom image, or set spec.startOptimized: true only after baking the build. Otherwise startup pays the auto-build cost on every pod start.--hostname must be a real, externally-resolvable URL in production, with --hostname-strict=true (default). Do not run with hostname-strict=false outside of dev — it lets clients dictate the issuer.--proxy-headers=xforwarded|forwarded is required when behind any reverse proxy that does TLS termination or rewrites the Host header. Pair with --proxy-trusted-addresses to a CIDR that covers the proxy. Without this, login redirects loop.--db postgres (or another supported vendor). The default dev-file H2 is not for production and silently disables clustering. Postgres is the only DB that gets tested under load by upstream.quay.io/keycloak/keycloak:26.6.2), never latest. The nightly tag is for CI only./health/started, /health/live, /health/ready — not the main HTTP port. As of 26.6, probes return UP during DB migrations so Liquibase can finish without K8s killing the pod.PodDisruptionBudget, not an HPA.KC_BOOTSTRAP_ADMIN_USERNAME/PASSWORD exists only to create the first real admin via kcadm.sh, then should be removed. The bootstrap admin auto-expires after 120 minutes.26.6.2 is meant to manage Keycloak 26.6.2. Mixing major.minor versions across the operator/server boundary is unsupported and often breaks the CRD schema.When the user says "just stand one up so I can play," don't point them at kc.sh start-dev if they care about production fidelity — show them this instead. It's a Keycloak CR + Postgres + Ingress, no extra moving parts:
# 1. Install the operator (do this once per cluster)
# kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.6.2/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
# kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.6.2/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
# kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.6.2/kubernetes/kubernetes.yml
# 2. Create a TLS secret (cert-manager / hand-roll / etc.)
# 3. Create DB credentials secret (keys: username, password)
# 4. Deploy Keycloak
apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
name: keycloak
namespace: iam
spec:
instances: 2
image: quay.io/keycloak/keycloak:26.6.2
startOptimized: false # set true when the image is pre-baked with `kc.sh build`
hostname:
hostname: https://auth.example.com
strict: true
proxy:
headers: xforwarded
http:
tlsSecret: keycloak-tls # remove and use ingress for edge termination
db:
vendor: postgres
host: postgres-rw.iam.svc
database: keycloak
usernameSecret: { name: keycloak-db, key: username }
passwordSecret: { name: keycloak-db, key: password }
bootstrapAdmin:
user:
secret: keycloak-bootstrap-admin # keys: username, password
update:
strategy: Auto # zero-downtime patch updates (26.6+)
features:
enabled: ["organizations", "admin-fine-grained-authz:v2"]
See assets/examples/ for fuller examples (with HA tuning, KeycloakRealmImport, raw-manifest deployment without the operator, network policies).
hostname-strict=false "fixes" my login → No, it papers over a proxy/headers misconfig. Set --proxy-headers correctly instead.kc.sh build re-run; dropping a theme jar into a stock image at runtime no longer works. Themes are packaged into the optimized server jar.#47872, fixed in 26.6.1. Upgrade to the latest 26.6.x.KeycloakRealmImport is create-or-replace; it won't merge. Use kcadm.sh for incremental edits, or accept the realm-as-config GitOps trade-off.@keycloak/keycloak-admin-client package, fixed in 26.6.1. Use the latest 26.6.x.DELETE FROM DATABASECHANGELOGLOCK WHERE ID=1 (after confirming no other instance is migrating). See observability.md §troubleshooting for the safe procedure.KC_* substitution surprises with $ in passwords" → Use the new KCRAW_* prefix (26.6+) instead of KC_* for any value that contains $.--proxy-headers / `KC_PROXY_HEADERS` . Operators copy-paste; getting it half right costs them an hour.