The X.509 feature over REST using header/body…

Error message

The X.509 feature over REST using header/body authentication provides a tremendously convenient target for claiming user identities or obtaining TGTs without proof of private key ownership. To securely use this feature, network configuration MUST allow connections to the CAS server only from trusted hosts which in turn have strict security limitations and logging. Thus, TLS authentication shouldn't be activated together with header or body authentication.

What it means

CasX509RestAutoConfiguration.x509RestHttpRequestCredentialFactoryConfigurer validates the combination of cas.rest.x509 settings. If tlsClientAuth is enabled together with headerAuth or bodyAuth, it logs this security warning: header/body auth would let clients claim identities or get TGTs without proving possession of the X.509 private key, defeating mutual TLS. This is a configuration-time warning, not a runtime exception.

Solutions

Disable header-auth and body-auth (set them to false) when tls-client-auth is enabled
If you must keep header/body auth, restrict network access to CAS to fully trusted hosts with strict logging, as the warning prescribes
Terminate TLS yourself only if you re-inject validated client-cert headers from a trusted TLS-terminating proxy
Remove the unused x509 REST properties entirely if the feature is not needed

Example fix

// before
cas.rest.x509.tls-client-auth=true
cas.rest.x509.header-auth=true
// after
cas.rest.x509.tls-client-auth=true
cas.rest.x509.header-auth=false
cas.rest.x509.body-auth=false

Defensive patterns

Strategy: validation

Validate before calling

// fail startup/config validation when both are on
if (tlsClientAuth && (headerAuth || bodyAuth)) {
    throw new IllegalStateException('Disable header/body auth when TLS client auth is enabled');
}

Prevention

Never combine cas.rest.x509.tls-client-auth with header-auth/body-auth
Restrict network access to CAS when header/body X.509 auth is used
Review x509 REST properties during security audits

When it happens

Trigger: Setting cas.rest.x509.tls-client-auth=true while also setting cas.rest.x509.header-auth=true or cas.rest.x509.body-auth=true in application properties.

Common situations: Enabling all X.509 REST switches 'to be safe' during initial setup; copying a dev config with header auth into a production TLS-authenticated deployment; misunderstanding that header auth is meant for deployments where TLS termination happens without client certs.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/d1b8cff958ef2c07. Report an issue: GitHub.

Appendix: source

Thrown at support/cas-server-support-rest-x509/src/main/java/org/apereo/cas/config/CasX509RestAutoConfiguration.java:103

        @Bean
        @RefreshScope(proxyMode = ScopedProxyMode.DEFAULT)
        @ConditionalOnMissingBean(name = "x509RestHttpRequestCredentialFactoryConfigurer")
        public RestHttpRequestCredentialFactoryConfigurer x509RestHttpRequestCredentialFactoryConfigurer(
            @Qualifier("x509RestTlsClientCert")
            final ObjectProvider<RestHttpRequestCredentialFactory> x509RestTlsClientCert,
            @Qualifier("x509RestMultipartBody")
            final ObjectProvider<RestHttpRequestCredentialFactory> x509RestMultipartBody,
            @Qualifier("x509RestRequestHeader")
            final ObjectProvider<RestHttpRequestCredentialFactory> x509RestRequestHeader,
            final CasConfigurationProperties casProperties) {
            return factory -> {
                val restProperties = casProperties.getRest().getX509();
                val headerAuth = restProperties.isHeaderAuth();
                val bodyAuth = restProperties.isBodyAuth();
                val tlsClientAuth = restProperties.isTlsClientAuth();

                if (tlsClientAuth && (headerAuth || bodyAuth)) {
                    LOGGER.warn("The X.509 feature over REST using header/body authentication provides a tremendously "
                                + "convenient target for claiming user identities or obtaining TGTs without proof of private "
                                + "key ownership. To securely use this feature, network configuration MUST allow connections "
                                + "to the CAS server only from trusted hosts which in turn have strict security limitations "
                                + "and logging. Thus, TLS authentication shouldn't be activated together with header "
                                + "or body authentication.");
                }

                if (headerAuth) {
                    x509RestRequestHeader.ifAvailable(factory::registerCredentialFactory);
                }
                if (bodyAuth) {
                    x509RestMultipartBody.ifAvailable(factory::registerCredentialFactory);
                }
                if (tlsClientAuth) {
                    x509RestTlsClientCert.ifAvailable(factory::registerCredentialFactory);
                }
            };
        }

View on GitHub (pinned to e7288fc434)