quarkusio/quarkus · error · SSLException

Hostname verification failure

Error message

Hostname verification failure

What it means

This SSLException is thrown by the Keycloak adapter's hostname verifier wrapper when the configured HostnameVerificationPolicy's underlying verifier rejects the hostname presented in the server's SSL session during an HTTPS handshake. It means the certificate's CN/SAN entries do not match the hostname the client is connecting to, so the TLS connection is aborted.

Source

Thrown at extensions/keycloak-authorization/runtime/src/main/java/io/quarkus/keycloak/pep/runtime/HttpClientBuilder.java:238

    }

    public HttpClientBuilder keyStore(KeyStore keyStore, char[] password) {
        this.clientKeyStore = keyStore;
        this.clientPrivateKeyPassword = new String(password);
        return this;
    }

    static class VerifierWrapper implements X509HostnameVerifier {
        protected HostnameVerifier verifier;

        VerifierWrapper(HostnameVerifier verifier) {
            this.verifier = verifier;
        }

        @Override
        public void verify(String host, SSLSocket ssl) throws IOException {
            if (!verifier.verify(host, ssl.getSession()))
                throw new SSLException("Hostname verification failure");
        }

        @Override
        public void verify(String host, X509Certificate cert) throws SSLException {
            throw new SSLException("This verification path not implemented");
        }

        @Override
        public void verify(String host, String[] cns, String[] subjectAlts) throws SSLException {
            throw new SSLException("This verification path not implemented");
        }

        @Override
        public boolean verify(String s, SSLSession sslSession) {
            return verifier.verify(s, sslSession);
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix the auth-server URL to use the exact hostname present in the Keycloak server certificate's CN/SAN entries.
2. Import the Keycloak server certificate into the configured truststore and ensure the hostname matches (truststore alone does not bypass hostname checks).
3. Set quarkus.oidc.tls.hostname-verification-algorithm / adapter config isAllowAnyHostname=true to relax hostname verification (dev/test only).
4. Use a properly signed certificate (or generate one with the correct SANs) on the Keycloak server.

Example fix

// before (quarkus.properties / application.properties)
quarkus.oidc.auth-server-url=https://127.0.0.1:8443/realms/quarkus
// after (use the name on the cert, or explicitly allow any hostname in dev)
quarkus.oidc.auth-server-url=https://localhost:8443/realms/quarkus
# dev/test only:
quarkus.keycloak.policy-enforcer.enable-https=false # or adapterConfig.setAllowAnyHostname(true)

// verify cert hostname before enabling policy enforcer
KeyStore ts = KeyStore.getInstance("PKCS12");
ts.load(new FileInputStream(truststorePath), tsPassword.toCharArray());
// ensure auth-server-url host equals a SAN/CN in the server certificate:
// keytool -list -v -keystore truststore.p12 | grep -i dns
String host = URI.create(authServerUrl).getHost();
if (!expectedSanPattern.matcher(host).matches()) throw new IllegalStateException("host mismatch");

try {
    client = HttpClientBuilder.create(adapterConfig).build();
} catch (SSLException e) {
    if (e.getMessage().contains("Hostname verification failure")) {
        log.error("Auth-server cert does not match host; fix URL or cert SANs", e);
    }
    throw e;
}

When it happens

Trigger: Making an HTTPS request from the Keycloak PEP (PolicyEnforcer/AuthzClient) to the Keycloak auth-server URL whose TLS certificate does not match the host in the URL (e.g. connecting via IP address or a different name than the cert's CN/SAN), while quarkus.keycloak.policy-enforcer... hostname verification is at the default (WILDCARD) policy instead of ANY.

Common situations: Local dev Keycloak started with a self-signed or generic certificate but accessed via localhost/IP; Docker/Kubernetes service names differing from cert SANs; hostname mismatch introduced when proxying or port-forwarding to the auth server.

Related errors

• Failed to create Keycloak Admin client SSLContext
• Specifying HostnameVerifier is not supported at the moment
• Trust options have already been set
• Key cert options have already been set
• This verification path not implemented

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/7ae380dc2cecf17b. Report an issue: GitHub.