Keycloak 26.4.0 behind Zuul in Kubernetes – best practice for public frontend URLs + internal token issuer ? #44453

saurabhPatel1712 · 2025-11-25T08:53:55Z

saurabhPatel1712
Nov 25, 2025

Hi all,

We are migrating from Keycloak 18 Wildfly to Keycloak 26.4.0 (Quarkus) in Kubernetes behind a Zuul edge proxy.

All browser-facing URLs (login redirects, “forgot password” email links, account console, admin console) must use the public domain → https://auth.company.com/auth/... (no port, no internal hostnames)
Token iss claim and all back-channel endpoints (token, introspection, JWKS, etc.) must remain the internal Kubernetes service URL → https://keycloak-prod.ns.svc.cluster.local:8000/auth/...
(many backend services validate the token issuer against the internal URL and we do not want to change hundreds of services)

We have the following setup today:

# Keycloak env
KC_HOSTNAME_URL=https://auth.company.com/auth
KC_HOSTNAME_ADMIN_URL=https://auth.company.com/auth
KC_HOSTNAME_STRICT=true
KC_HOSTNAME_STRICT_HTTPS=true
KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true
KC_HTTPS_PORT=8000
KC_HTTP_ENABLED=false
KC_PROXY_HEADERS=xforwarded

Zuul route

zuul.routes.keycloak:
  path: /auth/**
  url: https://keycloak-prod.ns.svc.cluster.local:8000
  stripPrefix: false
  sensitiveHeaders:

And a tiny pre-filter that forces the three public headers:

@Component
public class KeycloakFilter extends ZuulFilter {

  private static final Logger LOGGER = LoggerFactory.getLogger(KeycloakFilter .class);

  @Override
  public String filterType() {
    return FilterConstants.PRE_TYPE;
  }

  @Override
  public int filterOrder() {
    return FilterConstants.PRE_DECORATION_FILTER_ORDER + 1;
  }

  @Override
  public boolean shouldFilter() {
    String uri = RequestContext.getCurrentContext().getRequest().getRequestURI();
    LOGGER.info("ShouldBeFiltered by KeycloakFilter for request to {}", uri);
    boolean shouldBeFiltered = uri.contains("/auth/");
    if (shouldBeFiltered){
      LOGGER.info("ShouldBeFiltered {} by KeycloakFilter for request to {}", true, uri);
    }
    return shouldBeFiltered;
  }

  @Override
  public Object run() throws ZuulException {
    RequestContext ctx = RequestContext.getCurrentContext();
    LOGGER.info("Adding X-Headers");
    ctx.addZuulRequestHeader("X-Forwarded-Proto", "https");
    ctx.addZuulRequestHeader("X-Forwarded-Host", "auth.company.com");
    ctx.addZuulRequestHeader("X-Forwarded-Port", "443");
    return null;
  }

Questions:

Why the above approach didn't help to get issuer as internal kube url(https://keycloak-prod.ns.svc.cluster.local:8000/auth/**) ?
Please suggest the solution here. Currently, many backend services validate the token issuer against the internal URL. I followed the documentation here: https://www.keycloak.org/server/hostname#_backend

saurabhPatel1712 · 2025-11-25T08:59:07Z

saurabhPatel1712
Nov 25, 2025
Author

Please help here : @stianst @shawkins

0 replies

shawkins · 2025-11-25T13:18:18Z

shawkins
Nov 25, 2025
Collaborator

KC_HOSTNAME_STRICT_HTTPS=true

That's not a valid configuration option.

Kubernetes behind a Zuul edge proxy

Do you mean re-encrypt? It doesn't appear that http is enabled on the Keycloak server.

https://keycloak-prod.ns.svc.cluster.local:8000/auth/...

It doesn't appear that you have configured the relative path as auth, should this url include /auth?

Why the above approach didn't help to get issuer as internal kube url(https://keycloak-prod.ns.svc.cluster.local:8000/auth/**) ?

If you access the Keycloak server via a URL that appears to match the front-end, then the request will be treated as coming from the front-end.

Can you explain more behind the reasoning for the custom filter?

1 reply

saurabhPatel1712 Nov 25, 2025
Author

Hi @shawkins, thanks for the quick reply.

KC_HOSTNAME_STRICT_HTTPS=true

That's not a valid configuration option.

That's Correct it was typo from my side. We are using KC_HOSTNAME_STRICT as true

Kubernetes behind a Zuul edge proxy

Do you mean re-encrypt? It doesn't appear that http is enabled on the Keycloak server.

I mean our Keycloak and all microservices are behind the Zuul proxy. No, i haven't enabled this configuration KC_HTTP_ENABLED. Do we need to enable the same ?

https://keycloak-prod.ns.svc.cluster.local:8000/auth/...

It doesn't appear that you have configured the relative path as auth, should this url include /auth?

Yes, i have, this stuffs we are doing in the docker file like this

/opt/keycloak/keycloak/bin/kc.sh build --http-relative-path=/${WEB_CONTEXT} --health-enabled=true --metrics-enabled=true


/opt/keycloak/keycloak/bin/kc.sh start --optimized --verbose --https-certificate-file=${SECRETS_DIRECTORY}/service.crt
8000
 --https-certificate-key-file=${SECRETS_DIRECTORY}/service.key  --https-trust-store-type=JKS --https-trust-store-file=${JAVA_HOME}/lib/security/cacerts --https-trust-store-password=${JAVA_CACERTS_PASSWORD} --import-realm --log="console,file"  &

Why the above approach didn't help to get issuer as internal kube url(https://keycloak-prod.ns.svc.cluster.local:8000/auth/**) ?

If you access the Keycloak server via a URL that appears to match the front-end, then the request will be treated as coming from the front-end.

Can you explain more behind the reasoning for the custom filter?

With the filter i was trying if i need to pass any X-Forwaded-headers. Do we need to configure KC_PROXY_HEADERS=xforwarded ??
Currently with Zuul gateway and keycloak 18 wildfly, we are doing lots of stuffs with Pre and Post filter like

Pre-filter overwrites X-Forwarded-Host → internal host on a whitelist of sensitive paths
(so Keycloak builds redirects with internal URLs)
Post-filter does string replacement of the internal host → public host in Location headers and in every JSON/HTML response body
(so the browser never sees the internal service name)

shawkins · 2025-11-25T15:49:52Z

shawkins
Nov 25, 2025
Collaborator

I mean our Keycloak and all microservices are behind the Zuul proxy. No, i haven't enabled this configuration KC_HTTP_ENABLED. Do we need to enable the same ?

I just wanted to clarify as edge usually means https to the proxy, then http to the backend. If you are either doing re-encrypt or passthrough tls, you don't need http enabled.

--http-relative-path=/${WEB_CONTEXT}

Ok, so WEB_CONTEXT is set to auth.

With the filter i was trying if i need to pass any X-Forwaded-headers.

That's typically the job of the proxy. Is the proxy not doing that, or are you trying to make internal requests appear as if they are coming via a proxy instead.

Do we need to configure KC_PROXY_HEADERS=xforwarded ??

If you are doing anything other than https passthrough, yes you should set the proxy headers option: https://www.keycloak.org/server/reverseproxy#_configure_the_reverse_proxy_headers

Pre-filter overwrites X-Forwarded-Host → internal host on a whitelist of sensitive paths

This sounds different than the filter you are showing, and is not something that is typically done.

Post-filter does string replacement of the internal host → public host in Location headers and in every JSON/HTML response body
(so the browser never sees the internal service name)

Setting KC_HOSTNAME_URL=https://auth.company.com/auth means that the browser won't see any internal service names when accessing via the front-end.

2 replies

saurabhPatel1712 Nov 25, 2025
Author

Hi @shawkins , Thank you again for the continued help.

What configuration do you suggest to achieve our Goal. As you know,

Our Zuul Gateway adds the X-Forwarded-* headers and forwards to the internal Kubernetes service. Currently, I haven't configured anything. How should i set the X-Forwarded headers and what values if you can share some example based on current context ?
https://keycloak-prod.keycloak.svc.cluster.local:8000/auth
All our internal micro-services also call Keycloak directly on the same internal URL
https://keycloak-prod.keycloak.svc.cluster.local:8000/auth

Goal

Token iss claim as internal and Keycloak accessible at https://auth.company.com/auth
https://keycloak-prod.keycloak.svc.cluster.local:8000/auth/... (internal)

shawkins Nov 25, 2025
Collaborator

I think we touched on this before with #41858 (reply in thread)

Are your internal micro-services only making back-channel requests? If not it seems like you trying to effectively have two front-end urls share an issuer - that is not supported.

The best I believe you can do out-of-the-box is to not set the hostname, and instead use hostname-strict=false. The public access and the internal access will then be completely separate - effectively different front-ends / issuers. You can look at other issues / discussion on how to properly secure hostname-strict=false.

saurabhPatel1712 · 2025-12-03T13:15:41Z

saurabhPatel1712
Dec 3, 2025
Author

Hi @shawkins , yes, all our internal micro-services only making back-channel requests. So, currently we are going with the setup like below and with this setup Keycloak 26 is up and healthy. The Keycloak token is now having internal Kubernetes service URL.

/opt/keycloak/keycloak/bin/kc.sh build --http-relative-path=/${WEB_CONTEXT} --health-enabled=true --metrics-enabled=true
/opt/keycloak/keycloak/bin/kc.sh start --optimized --verbose --https-port=8000 --http-enabled=true --https-certificate-file=${SECRETS_DIRECTORY}/service.crt --https-certificate-key-file=${SECRETS_DIRECTORY}/service.key --https-trust-store-type=JKS --https-trust-store-file=${JAVA_HOME}/lib/security/cacerts --https-trust-store-password=${JAVA_CACERTS_PASSWORD} --import-realm --log="console,file" &

 - name: KC_HOSTNAME_STRICT
   value: "false"
 - name: KC_HOSTNAME_BACKCHANNEL_DYNAMIC
   value: "false"
 - name: KC_HTTP_ENABLED
   value: "true"
 - name: KC_HOSTNAME_DEBUG
   value: "true"
 - name: KC_HTTPS_PORT
   value: "8000"
 - name: KC_HTTP_PORT
   value: "8080"
 - name: KC_PROXY_HEADERS
   value: "xforwarded"

In Zuul gateway we have below filters for the URLS

LOGIN_ACTIONS_AUTH_URI = "/realms//login-actions/authenticate";
LOGIN_ACTIONS_ACTION_TOKEN_URI = "/realms//login-actions/action-token";
REQUIRED_ACTION_AUTH_URI = "/realms//login-actions/required-action";
PROTOCOL_OPENID_AUTH_URI = "/realms//protocol/openid-connect/";
LOGIN_ACTIONS_RESET_PASSWORD_URI = "/realms//login-actions/reset-credentials";
WHO_AM_I = "/admin//console/whoami";
ADMIN_REALMS = "/admin/realms/";
ADMIN_SERVER_INFO = "/admin/serverinfo";
ADMIN_MASTER_CONSOLE = "/admin/master/console/";
ADMIN_MASTER_CONSOLE_CONFIG = "/admin/master/console/config";

Pre-filter overwrites X-Forwarded-Host → internal host on a whitelist of sensitive paths
(so Keycloak builds redirects with internal URLs)

Post-filter does string replacement of the internal host → public host in Location headers and in every JSON/HTML response body
(so the browser never sees the internal service name)

1 reply

shawkins Dec 3, 2025
Collaborator

yes, all our internal micro-services only making back-channel requests.

The supported way to approach this scenario is to use KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true, and let everything use the public HOSTNAME as the issuer.

I know you are not trying to do that, but it's worth mentioning.

Pre-filter overwrites X-Forwarded-Host → internal host on a whitelist of sensitive paths
Post-filter does string replacement of the internal host → public host in Location headers and in every JSON/HTML response body

This is trying to make requests coming through the Zuul proxy seem as if they are internal. While Keycloak won't prevent you from doing this, it would not be considered supported.

saurabhPatel1712 · 2025-12-03T13:36:40Z

saurabhPatel1712
Dec 3, 2025
Author

Hi @shawkins, Currently we are facing another issue. When are trying to login in our UI application integrated with Keycloak 26.4.0, we are not able to successfully logged in to the application although in the Keycloak server side it shows user is successfully logged in.

While debugging I found this feature Exclude Issuer From Authentication Response

When its disabled in our public client, the multiple issuers will get appended in the redirect URL and our application keep on reauthenticating with keycloak.
When its enable in our public client, no issuer url will get appended in the redirect url but our application keep on reauthenticating with keycloak.
Additionally, I don't see session storage like keckloakstorage in the browser which we used to get in keycloak 18 or 22.
I have attached the features enabled in our keycloak 26.

0 replies

shawkins · 2025-12-03T14:06:07Z

shawkins
Dec 3, 2025
Collaborator

Currently we are facing another issue.

If you think you have found an issue, and it is reproducible in a supported configuration, please open an new issue https://github.com/keycloak/keycloak/issues

1 reply

saurabhPatel1712 Dec 3, 2025
Author

Yes Sure @shawkins. Many Many thanks for all the prompt support. Highly appreciated and Thanks again,

Keycloak 26.4.0 behind Zuul in Kubernetes – best practice for public frontend URLs + internal token issuer ? #44453

Uh oh!

Uh oh!

saurabhPatel1712 Nov 25, 2025

Replies: 6 comments · 5 replies

Uh oh!

saurabhPatel1712 Nov 25, 2025 Author

Uh oh!

shawkins Nov 25, 2025 Collaborator

Uh oh!

saurabhPatel1712 Nov 25, 2025 Author

Uh oh!

shawkins Nov 25, 2025 Collaborator

Uh oh!

saurabhPatel1712 Nov 25, 2025 Author

Uh oh!

Uh oh!

shawkins Nov 25, 2025 Collaborator

Uh oh!

saurabhPatel1712 Dec 3, 2025 Author

Uh oh!

shawkins Dec 3, 2025 Collaborator

Uh oh!

Uh oh!

saurabhPatel1712 Dec 3, 2025 Author

Uh oh!

shawkins Dec 3, 2025 Collaborator

Uh oh!

saurabhPatel1712 Dec 3, 2025 Author

saurabhPatel1712
Nov 25, 2025

Replies: 6 comments 5 replies

saurabhPatel1712
Nov 25, 2025
Author

shawkins
Nov 25, 2025
Collaborator

saurabhPatel1712 Nov 25, 2025
Author

shawkins
Nov 25, 2025
Collaborator

saurabhPatel1712 Nov 25, 2025
Author

shawkins Nov 25, 2025
Collaborator

saurabhPatel1712
Dec 3, 2025
Author

shawkins Dec 3, 2025
Collaborator

saurabhPatel1712
Dec 3, 2025
Author

shawkins
Dec 3, 2025
Collaborator

saurabhPatel1712 Dec 3, 2025
Author