Hi everyone,

I want to start a discussion on how to proceed with the ongoing issues around using the fixed hostname in Keycloak, providing some context and options.

First of all, for context:

Why does Keycloak use its own Hostnameprovider?

Keycloak advertises a number its URL in a number of places, including:

• Token issuer URL
• Links in emails
• Links in OpenID Connect Discovery

It is important that these are fixed and can’t be manipulated by end-users, for example by sending a modified Host header. This could for example lead to a password reset email being sent to a real user with links to “https://malicious-kc-facade.com/” that would allow the attacker to obtain the action token, passwords, etc. from the user. Similarly for the issued tokens it is important that an attacker is not able to have tokens issued with a fake/invalid token issuer, and that this part of the token is fixed.

The solution to this problem in previous versions of Keycloak was to allow hard-coding the base-url of Keycloak.

There are two additional complexities involved here:

1. Some clients are not contacting Keycloak through the external URL, but rather through some internal URL. This is why we have a different URL for backchannel requests, as these can be accessed internally, while frontchannel requests (like authorization grant) have to be accessed through the public/external URL. In many deployments however Keycloak is always accessed through the public URL, so there’s no need for this additional complexity, and it can also be a slight security hardening to prevent “dynamic” backchannel URLs.

Second, some users restrict the admin console/endpoints to internal URLs only and do not expose these publicly.

One additional thing is that some users expose different realms on different public URLs. This is why there’s an option to override the frontchannel URL for a specific realm through the realm config (admin console).

From a security perspective what is important is that the hostname in frontchannel URLs can’t be manipulated. URLs sent to end-users (emails, redirects, etc.) and token issuers must be the proper hostname of the server, and an attacker must not be able to redirect users to some other URL.

What's the state in the Quarkus distribution? (Keycloak 18 at the time of writing)

Requiring users to configure a full URL for the Keycloak server is not very elegant from a UX perspective, if we’d just transferred what we had in the Wildfly distribution to Quarkus it would be something like:

bin/kc.sh start –hostname-frontend-url=https://myhost:81232/

We’ve also had quite a few people having issues with configuring the hostname in the WildfFly distribution. So, there was a clear usability issue in the past we wanted to fix.

We tried to make it simpler by requiring people to only specify the hostname part, and be smart about the rest.

We also want to make Keycloak following current security best practices, so the production mode (invoking start) should always lead to a secure environment for managing OIDC.

The Issue with HOSTNAME_STRICT_HTTPS

Multiple Threads, Issues and discussions came up stating blank pages while e.g. accessing the administration console / login page. The answer was almost always sth around "set hostname-strict-https=false and it will work". That's true, but the issue is, this option should never have been made public. Instead, it is an internal option. Nevertheless, it is, by design, the only way to start Keycloak in production mode and Keycloak being able to successfully respond to HTTP requests.

So, this is a UX issue. For this UX issue, I created #11823 this draft PR to fix it automatically, based on some assumptions I made on how it should be set under the covers when invoking the production mode (start) and the different proxy configurations. You can find these in the table in the PRs description.

Now the problem with this PR is, that doing it like outlined would violate the "secure by design" principle of the production mode, as you would be able to access Keycloak using HTTP, and this should not happen. Without transport encryption, OIDC is pretty open to all kinds of attack vectors. This is formally true, however my experience shows that often cloud platforms are terminating TLS at the "edge" of their platform, usually a reverse proxy like NGINX, and internal traffic is done using HTTP. Other experiences vary. This is exactly what the proxy=edge mode for, so hostname-strict-https=false is set for that mode in the draft PR. Nevertheless this could also be circumvented by adding a redirect rule in your proxy from HTTP to HTTPS.

How to proceed?

After all, there's a trade-off to be made here.

Possible options:

1. use the proposed solution from the PR. Positive impact on User experience. Negative impact on security, under some circumstances. Slightly negative impact to startup performance, bc. we need to do multiple configuration lookups.

2. Set hostname-strict-https=true always for all proxy configurations. Instead of adding the rules directly to the code, add a section to the hostname documentation, stating sth around

The only way to run Keycloak and access it using HTTP in productionmode is to set hostname-strict-https=false. This is not secure and can lead to attack vectors being opened.

This would not lead to the potential security problems, but the UX is not great.
2a) Also: Provide a repository as a "go-to-showcase-solution", maybe in the quickstarts, maybe somewhere else, that includes automated E2E tests with one proxy implementation for all the different configuration modes.

2b) Follow-up question: Why differentiate the proxy options at all now on the keycloak side? It'd now be a boolean behaviour. So maybe also change proxy=edge/reencrypt/... to proxy=false/true? It's a breaking change, though.

2c) This behaviour would render the http-enabled option pretty useless to show to people/let people manipulate in the configuration. It is set to true in dev-mode (and hostname-strict-https=false also applies there), so we have a good devmode default.
It is set to false in production mode, so the default fits here also. Then we could leave it as is, but hide the configuration option like we do for hostname-strict-https. Also a possibly breaking change.

We decided internally for now to go with option 2, but I am still not sure if we should make the breaking changes and what you people think of it, so I wanted to reach out to the community first before proceeding, as this topic is just essential, yet complicated because of many parts involved.