8000 fix: adds more validation of proxy-headers by shawkins · Pull Request #38092 · keycloak/keycloak · GitHub
[go: up one dir, main page]

Skip to content
Comment thread
vmuzikar marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,24 @@

import static org.keycloak.quarkus.runtime.configuration.mappers.PropertyMapper.fromOption;

import java.net.MalformedURLException;
import java.net.URL;
import java.util.Arrays;
import java.util.List;
import java.util.function.Consumer;
import java.util.stream.Stream;

import org.keycloak.common.Profile;
import org.keycloak.config.HostnameV2Options;
import org.keycloak.quarkus.runtime.Environment;
import org.keycloak.quarkus.runtime.cli.Picocli;
import org.keycloak.config.ProxyOptions;
import org.keycloak.quarkus.runtime.configuration.Configuration;
import org.keycloak.utils.SecureContextResolver;

public final class HostnameV2PropertyMappers {

private static final String CONTEXT_WARNING = "the server is running in an insecure context. Secure contexts are required for full functionality, including cross-origin cookies.";
private static final List<String> REMOVED_OPTIONS = Arrays.asList("hostname-admin-url", "hostname-path", "hostname-port", "hostname-strict-backchannel", "hostname-url", "proxy", "hostname-strict-https");

private HostnameV2PropertyMappers(){}
Expand All @@ -36,10 +43,66 @@ public static PropertyMapper<?>[] getHostnamePropertyMappers() {
}

public static void validateConfig(Picocli picocli) {
validateConfig(picocli::warn);
}

public static void validateConfig(Consumer<String> warn) {
List<String> inUse = REMOVED_OPTIONS.stream().filter(s -> Configuration.getOptionalKcValue(s).isPresent()).toList();

if (!inUse.isEmpty()) {
picocli.warn("Hostname v1 options %s are still in use, please review your configuration".formatted(inUse));
warn.accept("Hostname v1 options %s are still in use, please review your configuration".formatted(inUse));
}
boolean isProd = Environment.PROD_PROFILE_VALUE.equals(org.keycloak.common.util.Environment.getProfile());
boolean httpsEnabled = HttpPropertyMappers.isHttpsEnabled();
String host = Configuration.getConfigValue(HostnameV2Options.HOSTNAME).getValue();
String proxyHeaders = Configuration.getConfigValue(ProxyOptions.PROXY_HEADERS).getValue();
if (host != null && validateFullHostname(httpsEnabled, isProd, host, proxyHeaders, warn)) {
return;
}
if (httpsEnabled) {
return; // must be re-encrypt or passthrough. if passthrough, proxy headers must not be set
}
// should be edge
if (proxyHeaders != null) {
return;
}
if (isProd) {
String warning = CONTEXT_WARNING + " Also if you are using a proxy, requests from the proxy to the server will fail CORS checks with 403s because the wrong origin will be determined. Make sure `proxy-headers` are configured properly.";
if (host == null) {
warn.accept("With HTTPS not enabled, `proxy-headers` unset, and `hostname-strict=false`, " + warning);
} else if (!SecureContextResolver.isLocal(host)) {
warn.accept("Likely misconfiguration detected. With HTTPS not enabled, `proxy-headers` unset, and a non-URL `hostname`, " + warning);
} // else warn on prod
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why // else warn on prod? The warning si already there, no?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The else case here is something like hostname=http://localhost - doesn't seem like that would be used in production, but I wasn't sure if it warrented a warning.

}
}

static boolean validateFullHostname(boolean httpsEnabled, boolean isProd, String host, String proxyHeaders, Consumer<String> warn) {
try {
URL url = new URL(host);

if (!url.getProtocol().toUpperCase().equals("HTTPS")) {
if (isProd) {
if (!SecureContextResolver.isLocal(url.getHost())) {
warn.accept("Likely misconfiguration detected. `hostname` is configured to use HTTP instead of HTTPS, " + CONTEXT_WARNING);

// TODO: any hostname-admin specific validation?

} // else warn on prod?
if (httpsEnabled) {
warn.accept("Likely misconfiguration detected. HTTPS is enabled on the server, but `hostname` specifies HTTP.");
}
}
} else if (proxyHeaders == null) {
if (!httpsEnabled) {
// edge case
warn.accept("Likely misconfiguration detected. When using an edge proxy, you must use `proxy-headers`.");
}
// else might be allowable if HOST is overwritten
}

return true;
} catch (MalformedURLException e) {
return false;
}
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -159,13 +159,17 @@ public static PropertyMapper<?>[] getHttpPropertyMappers() {

public static void validateConfig() {
boolean enabled = isHttpEnabled(getOptionalKcValue(HttpOptions.HTTP_ENABLED.getKey()).orElse(null));
Optional<String> certFile = getOptionalValue(QUARKUS_HTTPS_CERT_FILES);
Optional<String> keystoreFile = getOptionalValue(QUARKUS_HTTPS_KEY_STORE_FILE);
if (!enabled && certFile.isEmpty() && keystoreFile.isEmpty()) {
if (!enabled && !isHttpsEnabled()) {
throw new PropertyException(Messages.httpsConfigurationNotSet());
}
}

public static boolean isHttpsEnabled() {
Optional<String> certFile = getOptionalValue(QUARKUS_HTTPS_CERT_FILES);
Optional<String> keystoreFile = getOptionalValue(QUARKUS_HTTPS_KEY_STORE_FILE);
return certFile.isPresent() || keystoreFile.isPresent();
}

private static String transformPath(String value, ConfigSourceInterceptorContext context) {
return value == null ? value : ClassPathUtils.toResourceName(Path.of(value));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,20 +16,26 @@
*/
package org.keycloak.quarkus.runtime.services.resources;

import java.util.stream.Stream;

import org.keycloak.config.HostnameV2Options;
import org.keycloak.config.HttpOptions;
import org.keycloak.config.ProxyOptions;

public class ConstantsDebugHostname {
public static final String[] RELEVANT_HEADERS = new String[] {
"Host",
"Forwarded",
public static final String[] X_FORWARDED_PROXY_HEADERS = new String[] {
"X-Forwarded-Host",
"X-Forwarded-Proto",
"X-Forwarded-Port",
"X-Forwarded-For"
};

public static final String FORWARDED_PROXY_HEADER = "Forwarded";

public static final String[] RELEVANT_HEADERS = Stream
.concat(Stream.of("Host", FORWARDED_PROXY_HEADER), Stream.of(X_FORWARDED_PROXY_HEADERS))
.toArray(String[]::new);

public static final String[] RELEVANT_OPTIONS_V2 = {
HostnameV2Options.HOSTNAME.getKey(),
HostnameV2Options.HOSTNAME_ADMIN.getKey(),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,35 +16,44 @@
*/
package org.keycloak.quarkus.runtime.services.resources;

import io.quarkus.resteasy.reactive.server.EndpointDisabled;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.Provider;
import org.keycloak.common.Profile;
import java.io.IOException;
import java.net.URI;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.TreeMap;
import java.util.stream.Stream;

import org.keycloak.common.util.UriUtils;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.quarkus.runtime.Environment;
import org.keycloak.quarkus.runtime.configuration.Configuration;
import org.keycloak.quarkus.runtime.configuration.mappers.HostnameV2PropertyMappers;
import org.keycloak.services.Urls;
import org.keycloak.services.cors.Cors;
import org.keycloak.theme.FreeMarkerException;
import org.keycloak.theme.Theme;
import org.keycloak.theme.freemarker.FreeMarkerProvider;
import org.keycloak.urls.UrlType;
import org.keycloak.utils.SecureContextResolver;

import java.io.IOException;
import java.net.URI;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.TreeMap;
import io.quarkus.resteasy.reactive.server.EndpointDisabled;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.Provider;

@Provider
@Path("/realms")
Expand Down Expand Up @@ -81,22 +90,26 @@ public String debug(final @PathParam("realmName") String realmName) throws IOExc

FreeMarkerProvider freeMarkerProvider = keycloakSession.getProvider(FreeMarkerProvider.class);

List<String> configWarnings = new ArrayList<String>();
HostnameV2PropertyMappers.validateConfig(configWarnings::add);

URI frontendUri = keycloakSession.getContext().getUri(UrlType.FRONTEND).getBaseUri();
URI backendUri = keycloakSession.getContext().getUri(UrlType.BACKEND).getBaseUri();
URI adminUri = keycloakSession.getContext().getUri(UrlType.ADMIN).getBaseUri();

String frontendTestUrl = getTest(realmModel, frontendUri);
String backendTestUrl = getTest(realmModel, backendUri);
String adminTestUrl = getTest(realmModel, adminUri);
String frontendTestUrl = getTest(realmModel, frontendUri, true);
String backendTestUrl = getTest(realmModel, backendUri, false);
String adminTestUrl = getTest(realmModel, adminUri, false);

Map<String, Object> attributes = new HashMap<>();
attributes.put("configWarnings", configWarnings);
attributes.put("frontendUrl", frontendUri.toString());
attributes.put("backendUrl", backendUri.toString());
attributes.put("adminUrl", adminUri.toString());

attributes.put("realm", realmModel.getName());
attributes.put("realmUrl", realmModel.getAttribute("frontendUrl"));
attributes.put("implVersion", Profile.isFeatureEnabled(Profile.Feature.HOSTNAME_V2) ? "V2" : "V1");
attributes.put("implVersion", "V2");

attributes.put("frontendTestUrl", frontendTestUrl);
attributes.put("backendTestUrl", backendTestUrl);
Expand All @@ -117,10 +130,44 @@ public String debug(final @PathParam("realmName") String realmName) throws IOExc
@GET
@Path("/{realmName}/" + DEFAULT_PATH_SUFFIX + "/" + PATH_FOR_TEST_CORS_IN_HEADERS)
@Produces(MediaType.TEXT_PLAIN)
public Response test(final @PathParam("realmName") String realmName) {
Response.ResponseBuilder builder = Response.ok(PATH_FOR_TEST_CORS_IN_HEADERS + "-OK");
String origin = keycloakSession.getContext().getRequestHeaders().getHeaderString(Cors.ORIGIN_HEADER);
builder.header(Cors.ACCESS_CONTROL_ALLOW_ORIGIN, origin);
public Response test(final @PathParam("realmName") String realmName, @DefaultValue("false") @QueryParam("frontEnd") boolean frontEnd) {
String text = "OK";
String corsOrigin = keycloakSession.getContext().getRequestHeaders().getHeaderString(Cors.ORIGIN_HEADER);
URI requestUri = keycloakSession.getContext().getUri().getRequestUri();
@vmuzikar vmuzikar May 7, 2025 •
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did some testing and this actually does not get us the "raw" request but one enriched by the Hostname provider, see:

this.hostname = hostnameProvider.getHostname(delegate, type);

@shawkins Could you please check it?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have. You only get the enrichment if you call getBaseUri. If you call getRequestUri, you get the underlying request:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then I might be doing something wrong. :)
I start KC with hostname=example.com and access http://localhost:8080/realms/master/hostname-debug. I would expect to get that warning but it's not emitted, and while debugging I can actually see that requestURI = http://example.com:8080/realms/master/hostname-debug/test?frontEnd=true.

@shawkins shawkins May 7, 2025 •
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you have hostname=example.com the urls tested by hostname-debug will be to example.com, not localhost. If you have a proxy setup for example.com, you should get the warning if it then accesses keycloak over localhost.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you have hostname=example.com the urls tested by hostname-debug will be to example.com, not localhost.

Right, sorry, I was stupid and also forgot I have example.com in my /etc/hosts. :D

LGTM, thanks. Let's get this merged finally.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to double check - do you think we need to review our usage of getRequestUri and the other methods on KeycloakUriInfo that expose the underlying delegate? I see several code paths using that, which makes using the full hostname url without proxy-headers problematic - or are we good with just requiring the proxy-headers to be be set?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or are we good with just requiring the proxy-headers to be be set

IMHO we're good for now - we say in docs proxy headers are required anyway for edge and reencrypt. If we did a refactor of getRequestUri, I would do that in a separate PR. But I wouldn't do that for now not to risk regressions.

String requestOrigin = UriUtils.getOrigin(requestUri);
URI frontendUri = keycloakSession.getContext().getUri(UrlType.FRONTEND).getBaseUri();

if (frontEnd) {
boolean originMatches = requestOrigin.equals(UriUtils.getOrigin(frontendUri));
HttpHeaders requestHeaders = keycloakSession.getContext().getRequestHeaders();
boolean fowarded = requestHeaders.getHeaderString(ConstantsDebugHostname.FORWARDED_PROXY_HEADER) != null;
boolean xfowarded = Stream.of(ConstantsDebugHostname.X_FORWARDED_PROXY_HEADERS)
.map(requestHeaders::getHeaderString).anyMatch(Objects::nonNull);

if (!originMatches) { // might fail CORS checks
text = "Default origin check failing, request hostname does not match frontend hostname. Please check you proxy settings.";
if (!keycloakSession.getContext().getHttpRequest().isProxyTrusted()) {
text += " Note the proxy is not trusted.";
}
if (!fowarded && !xfowarded) {
text += " No proxy headers are set on the request.";
}
}

boolean https = requestUri.getScheme().equals("https");
if (https) {
// if reencrypt, then proxy headers may need set
// if passthrough, then proxy headers should not be set

// TODO: not sure if there is great way to do this. Would likely need to check that a connection to the frontend uses the same
// cert as what is coming in on this request
} else if (!SecureContextResolver.isSecureContext(keycloakSession)) {
text += " Non-secure context detected - Keycloak will not function properly when accessed over http at a non-localhost host.";
}
}

Response.ResponseBuilder builder = Response.ok(text);
builder.header(Cors.ACCESS_CONTROL_ALLOW_ORIGIN, corsOrigin);
builder.header(Cors.ACCESS_CONTROL_ALLOW_METHODS, "GET");
return builder.build();
}
Expand All @@ -132,7 +179,6 @@ private void addOption(String key) {
}
}


private Map<String, String> getHeaders() {
Map<String, String> headers = new TreeMap<>();
HttpHeaders requestHeaders = keycloakSession.getContext().getRequestHeaders();
Expand All @@ -149,9 +195,10 @@ private void addProxyHeader(String header, Map<String, String> proxyHeaders, Htt
}
}

private String getTest(RealmModel realmModel, URI baseUri) {
private String getTest(RealmModel realmModel, URI baseUri, boolean frontEnd) {
return Urls.realmBase(baseUri)
.path("/{realmName}/{debugHostnameSettingsPath}/{pathForTestCORSInHeaders}")
.queryParam("frontEnd", frontEnd)
.build(realmModel.getName(), DEFAULT_PATH_SUFFIX, PATH_FOR_TEST_CORS_IN_HEADERS)
.toString();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@

<body>

<ul>
<#list configWarnings as warning>
<li>${warning}</li>
</#list>
</ul>

<table>
<tr>
<th>URL</th>
Expand Down Expand Up @@ -109,7 +115,7 @@
if (xhr.readyState == 4) {
clearTimeout(timeout);
if (xhr.status == 200) {
document.getElementById(responseId).textContent='OK';
document.getElementById(responseId).textContent=xhr.response;
} else {
document.getElementById(responseId).textContent='FAILED';
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -505,7 +505,7 @@ public void buildOptionChangedWithOptimized() {
public void buildOptionWithOptimized() {
build("build", "--metrics-enabled=true", "--db=dev-file");

NonRunningPicocli nonRunningPicocli = pseudoLaunch("start", "--optimized", "--http-enabled=true", "--hostname=keycloak");
NonRunningPicocli nonRunningPicocli = pseudoLaunch("start", "--optimized", "--http-enabled=true", "--hostname-strict=false");
assertEquals(CommandLine.ExitCode.OK, nonRunningPicocli.exitCode);
}

Expand Down Expand Up @@ -582,9 +582,30 @@ public void proxyProtolNotAllowedWithProxyHeaders() {
assertThat(nonRunningPicocli.getErrString(), containsString(" protocol cannot be enabled when using the `proxy-headers` option"));
}

@Test
public void hostnameProxyValidation() {
NonRunningPicocli nonRunningPicocli = pseudoLaunch("start", "--hostname=foo", "--http-enabled=true");
assertEquals(CommandLine.ExitCode.OK, nonRunningPicocli.exitCode);
assertThat(nonRunningPicocli.getOutString(), containsString("Likely misconfiguration detected"));
}

@Test
public void hostnameProxyValidationStrictFalse() {
NonRunningPicocli nonRunningPicocli = pseudoLaunch("start", "--hostname-strict=false", "--http-enabled=true");
assertEquals(CommandLine.ExitCode.OK, nonRunningPicocli.exitCode);
assertThat(nonRunningPicocli.getOutString(), containsString("With HTTPS not enabled"));
}

@Test
public void hostnameValidationHttp() {
NonRunningPicocli nonRunningPicocli = pseudoLaunch("start", "--hostname=http://host", "--http-enabled=true");
assertEquals(CommandLine.ExitCode.OK, nonRunningPicocli.exitCode);
assertThat(nonRunningPicocli.getOutString(), containsString("Likely misconfiguration detected"));
}

@Test
public void derivedPropertyUsage() {
NonRunningPicocli nonRunningPicocli = pseudoLaunch("start-dev", "--hostname=first-class", "--spi-hostname-v2-hostname=second-class", "--http-enabled=false");
NonRunningPicocli nonRunningPicocli = pseudoLaunch("start-dev", "--hostname=localhost", "--spi-hostname-v2-hostname=second-class");
assertEquals(CommandLine.ExitCode.OK, nonRunningPicocli.exitCode);
assertThat(nonRunningPicocli.getOutString(), containsString("Please use the first-class option `kc.hostname` instead of `kc.spi-hostname-v2-hostname`"));
}
Expand Down
Loading
0