[system] Fix Keycloak proxy configuration for v26.x#2125
Conversation
KC_PROXY=edge was deprecated and removed in Keycloak 26.x, causing "Non-secure context detected" warnings and broken cookie handling behind reverse proxy. Replace with KC_PROXY_HEADERS=xforwarded and KC_HTTP_ENABLED=true. Co-Authored-By: Claude <[email protected]> Signed-off-by: Kirill Ilin <[email protected]>
📝 WalkthroughWalkthroughThis change updates Keycloak's environment configuration by replacing the Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request updates the Keycloak StatefulSet configuration to ensure compatibility with Keycloak version 26.x and later. The changes resolve issues related to proxy handling and secure context detection that arose from the removal of a deprecated environment variable, thereby maintaining proper functionality when Keycloak is deployed behind a reverse proxy. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
sircthulhu
requested review from
IvanHunters,
androndo,
kvaps,
lexfrei and
lllamnyp
as code owners
dosubot
bot
added
size:XS
![gemini-code-assist[bot]](proxy.php?url=https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the Keycloak proxy configuration to align with the changes in Keycloak v26.x. The deprecated KC_PROXY environment variable is correctly replaced with KC_PROXY_HEADERS and KC_HTTP_ENABLED. This is a necessary change to ensure Keycloak functions correctly behind a reverse proxy that terminates TLS, and it resolves issues like incorrect cookie handling. The implementation is correct and follows the official Keycloak migration guide.
![coderabbitai[bot]](proxy.php?url=https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/system/keycloak/templates/sts.yaml`:
- Around line 85-88: Add the KC_PROXY_TRUSTED_ADDRESSES environment variable
alongside KC_PROXY_HEADERS and KC_HTTP_ENABLED to restrict which proxy IPs
Keycloak will trust; set KC_PROXY_TRUSTED_ADDRESSES to the ingress/proxy CIDR(s)
or comma-separated IPs (e.g., the cluster/load‑balancer subnet) so forwarded
headers cannot be spoofed, and ensure this env var is applied in the same
container spec where KC_PROXY_HEADERS and KC_HTTP_ENABLED are defined.
| - name: KC_PROXY_HEADERS | ||
| value: "xforwarded" | ||
| - name: KC_HTTP_ENABLED | ||
| value: "true" |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Keycloak 26 KC_PROXY deprecation migration KC_PROXY_HEADERS
💡 Result:
In Keycloak 26, the old --proxy / KC_PROXY setting is removed (it was deprecated since Keycloak 24). You must migrate to --proxy-headers / KC_PROXY_HEADERS, typically together with hostname (v2) options. [1] [2]
What to change
Before (deprecated/removed):
KC_PROXY=edge|reencrypt|passthrough|...
After (supported):
KC_PROXY_HEADERS=forwarded(if your proxy sets the standardForwardedheader), orKC_PROXY_HEADERS=xforwarded(if your proxy setsX-Forwarded-*headers). [3] [4]
Keycloak explicitly documents the mapping:
- CLI:
--proxy-headers - Env:
KC_PROXY_HEADERS - Values:
forwarded,xforwarded[4]
Typical “edge termination” replacement (TLS ends at the proxy)
If TLS is terminated at the reverse proxy (common “edge” setup), you usually need:
KC_PROXY_HEADERS=xforwardedKC_HTTP_ENABLED=true(because proxy → Keycloak is plain HTTP)KC_HOSTNAME=...(often best as a full external URL, e.g.https://auth.example.com, to avoid mixed/incorrect URLs) [3]
Security hardening you should add in 26+
If you enable proxy header parsing, consider restricting which proxy IPs are trusted:
- CLI:
--proxy-trusted-addresses=... - Env:
KC_PROXY_TRUSTED_ADDRESSES=...[4]
This feature was added alongside the proxy changes and is recommended to avoid trusting spoofed forwarded headers. [1] [2]
Sources: Keycloak 26 release announcement & release notes, and the official Reverse Proxy guide. [1] [2] [3] [4]
🏁 Script executed:
# First, locate and examine the file to understand its context
find . -path "*packages/system/keycloak/templates/sts.yaml" -type fRepository: cozystack/cozystack
Length of output: 108
🏁 Script executed:
# Examine the file content around the changed lines and broader context
cat -n packages/system/keycloak/templates/sts.yaml | head -150 | tail -80Repository: cozystack/cozystack
Length of output: 3381
🏁 Script executed:
# Also check if KC_PROXY_TRUSTED_ADDRESSES is configured anywhere in the file
grep -n "KC_PROXY_TRUSTED_ADDRESSES\|PROXY_TRUSTED" packages/system/keycloak/templates/sts.yamlRepository: cozystack/cozystack
Length of output: 45
🏁 Script executed:
# Verify the file structure - is this a custom template or vendored chart?
ls -la packages/system/keycloak/Repository: cozystack/cozystack
Length of output: 482
Configuration is correct for Keycloak 26.x, but add proxy trust restrictions for security.
The replacement of KC_PROXY=edge with KC_PROXY_HEADERS=xforwarded and KC_HTTP_ENABLED=true correctly aligns with Keycloak 26.x requirements (KC_PROXY was removed, KC_PROXY_HEADERS is the documented replacement). The configuration correctly enables HTTP when TLS is terminated at the ingress and trusts X-Forwarded-* headers.
Consider adding KC_PROXY_TRUSTED_ADDRESSES to restrict which proxy IPs are trusted and prevent spoofed forwarded headers—this is a recommended security hardening measure in Keycloak 26+ when proxy header parsing is enabled.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/system/keycloak/templates/sts.yaml` around lines 85 - 88, Add the
KC_PROXY_TRUSTED_ADDRESSES environment variable alongside KC_PROXY_HEADERS and
KC_HTTP_ENABLED to restrict which proxy IPs Keycloak will trust; set
KC_PROXY_TRUSTED_ADDRESSES to the ingress/proxy CIDR(s) or comma-separated IPs
(e.g., the cluster/load‑balancer subnet) so forwarded headers cannot be spoofed,
and ensure this env var is applied in the same container spec where
KC_PROXY_HEADERS and KC_HTTP_ENABLED are defined.
|
Successfully created backport PR for |
2 participants
What this PR does
Replace deprecated
KC_PROXY=edgewithKC_PROXY_HEADERS=xforwardedandKC_HTTP_ENABLED=truein the Keycloak StatefulSet template.KC_PROXYwas removed in Keycloak 26.x, causing "Non-secure context detected" warnings and broken cookie handling when running behind a reverse proxy with TLS termination.Release note
Summary by CodeRabbit
Release Notes