Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Quarkus CXF security guide

This chapter provides information about security when working with Quarkus CXF extensions.

6.1. Security guide
Copy link

The security guide documents various security related aspects of Quarkus CXF:

6.1.1. SSL, TLS and HTTPS
Copy link

This section documents various use cases related to SSL, TLS and HTTPS.

Note

The sample code snippets used in this section come from the WS-SecurityPolicy integration test in the source tree of Quarkus CXF

6.1.1.1. Client SSL configuration
Copy link

If your client is going to communicate with a server whose SSL certificate is not trusted by the client’s operating system, then you need to set up a custom trust store for your client.

Tools like openssl or Java keytool are commonly used for creating and maintaining truststores.

We have examples for both tools in the Quarkus CXF source tree:

Once you have prepared the trust store, you need to configure your client to use it.

This is the easiest way to set the client trust store. The key role is played by the following properties:

Here is an example:

application.properties

# Client side SSL
quarkus.cxf.client.hello.client-endpoint-url = https://localhost:${quarkus.http.test-ssl-port}/services/hello
quarkus.cxf.client.hello.service-interface = io.quarkiverse.cxf.it.security.policy.HelloService
1 

quarkus.cxf.client.hello.trust-store-type = pkcs12
2 

quarkus.cxf.client.hello.trust-store = client-truststore.pkcs12
quarkus.cxf.client.hello.trust-store-password = client-truststore-password
Copy to Clipboard Toggle word wrap

1
pkcs12 and jks are two commonly used keystore formats. PKCS12 is the default Java keystore format since Java 9. We recommend using PKCS12 rather than JKS, because it offers stronger cryptographic algorithms, it is extensible, standardized, language-neutral and widely supported.
2
The referenced client-truststore.pkcs12 file has to be available either in the classpath or in the file system.

6.1.1.2. Server SSL configuration
Copy link

To make your services available over the HTTPS protocol, you need to set up server keystore in the first place. The server SSL configuration is driven by Vert.x, the HTTP layer of Quarkus. Quarkus HTTP guide provides the information about the configuration options.

Here is a basic example:

application.properties

# Server side SSL
quarkus.tls.key-store.p12.path = localhost-keystore.pkcs12
quarkus.tls.key-store.p12.password = localhost-keystore-password
quarkus.tls.key-store.p12.alias = localhost
quarkus.tls.key-store.p12.alias-password = localhost-keystore-password
Copy to Clipboard Toggle word wrap

6.1.1.3. Mutual TLS (mTLS) authentication
Copy link

So far, we have explained the simple or single-sided case where only the server proves its identity through an SSL certificate and the client has to be set up to trust that certificate. Mutual TLS authentication goes by letting also the client prove its identity using the same means of public key cryptography.

Hence, for the Mutual TLS (mTLS) authentication, in addition to setting up the server keystore and client truststore as described above, you need to set up the keystore on the client side and the truststore on the server side.

The tools for creating and maintaining the stores are the same and the configuration properties to use are pretty much analogous to the ones used in the Simple TLS case.

The mTLS integration test in the Quarkus CXF source tree can serve as a good starting point.

The keystores and truststores are created with openssl (or alternatively with Java Java keytool)

Here is the application.properties file:

application.properties

# Server keystore for Simple TLS
quarkus.tls.localhost-pkcs12.key-store.p12.path = localhost-keystore.pkcs12
quarkus.tls.localhost-pkcs12.key-store.p12.password = localhost-keystore-password
quarkus.tls.localhost-pkcs12.key-store.p12.alias = localhost
quarkus.tls.localhost-pkcs12.key-store.p12.alias-password = localhost-keystore-password
# Server truststore for Mutual TLS
quarkus.tls.localhost-pkcs12.trust-store.p12.path = localhost-truststore.pkcs12
quarkus.tls.localhost-pkcs12.trust-store.p12.password = localhost-truststore-password
# Select localhost-pkcs12 as the TLS configuration for the HTTP server
quarkus.http.tls-configuration-name = localhost-pkcs12

# Do not allow any clients which do not prove their indentity through an SSL certificate
quarkus.http.ssl.client-auth = required

# CXF service
quarkus.cxf.endpoint."/mTls".implementor = io.quarkiverse.cxf.it.auth.mtls.MTlsHelloServiceImpl

# CXF client with a properly set certificate for mTLS
quarkus.cxf.client.mTls.client-endpoint-url = https://localhost:${quarkus.http.test-ssl-port}/services/mTls
quarkus.cxf.client.mTls.service-interface = io.quarkiverse.cxf.it.security.policy.HelloService
quarkus.cxf.client.mTls.key-store = target/classes/client-keystore.pkcs12
quarkus.cxf.client.mTls.key-store-type = pkcs12
quarkus.cxf.client.mTls.key-store-password = client-keystore-password
quarkus.cxf.client.mTls.key-password = client-keystore-password
quarkus.cxf.client.mTls.trust-store = target/classes/client-truststore.pkcs12
quarkus.cxf.client.mTls.trust-store-type = pkcs12
quarkus.cxf.client.mTls.trust-store-password = client-truststore-password

# Include the keystores in the native executable
quarkus.native.resources.includes = *.pkcs12,*.jks
Copy to Clipboard Toggle word wrap

6.1.1.4. Enforce SSL through WS-SecurityPolicy
Copy link

The requirement for the clients to connect through HTTPS can be defined in a policy.

The functionality is provided by quarkus-cxf-rt-ws-security extension.

Here is an example of a policy file:

https-policy.xml

<?xml version="1.0" encoding="UTF-8"?>
<wsp:Policy wsp:Id="HttpsSecurityServicePolicy"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <wsp:ExactlyOne>
        <wsp:All>
            <sp:TransportBinding>
                <wsp:Policy>
                    <sp:TransportToken>
                        <wsp:Policy>
                            <sp:HttpsToken RequireClientCertificate="false" />
                        </wsp:Policy>
                    </sp:TransportToken>
                    <sp:IncludeTimestamp />
                    <sp:AlgorithmSuite>
                        <wsp:Policy>
                            <sp:Basic128 />
                        </wsp:Policy>
                    </sp:AlgorithmSuite>
                </wsp:Policy>
            </sp:TransportBinding>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>
Copy to Clipboard Toggle word wrap

The policy has to be referenced from a service endpoint interface (SEI):

HttpsPolicyHelloService.java

package io.quarkiverse.cxf.it.security.policy;

import jakarta.jws.WebMethod;
import jakarta.jws.WebService;

import org.apache.cxf.annotations.Policy;

/**
 * A service implementation with a transport policy set
 */
@WebService(serviceName = "HttpsPolicyHelloService")
@Policy(placement = Policy.Placement.BINDING, uri = "https-policy.xml")
public interface HttpsPolicyHelloService extends AbstractHelloService {

    @WebMethod
    @Override
    public String hello(String text);

}
Copy to Clipboard Toggle word wrap

With this setup in place, any request delivered over HTTP will be rejected by the PolicyVerificationInInterceptor: 

ERROR [org.apa.cxf.ws.pol.PolicyVerificationInInterceptor] Inbound policy verification failed: These policy alternatives can not be satisfied:
 {http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702}TransportBinding: TLS is not enabled
 ...
Copy to Clipboard Toggle word wrap

6.1.2. Authentication and authorization
Copy link

Note

The sample code snippets shown in this section come from the Client and server integration test in the source tree of Quarkus CXF. You may want to use it as a runnable example.

6.1.2.1. Client HTTP basic authentication
Copy link

Use the following client configuration options provided by quarkus-cxf extension to pass the username and password for HTTP basic authentication:

Here is an example:

application.properties

quarkus.cxf.client.basicAuth.wsdl = http://localhost:${quarkus.http.test-port}/soap/basicAuth?wsdl
quarkus.cxf.client.basicAuth.client-endpoint-url = http://localhost:${quarkus.http.test-port}/soap/basicAuth
quarkus.cxf.client.basicAuth.username = bob
quarkus.cxf.client.basicAuth.password = bob234
Copy to Clipboard Toggle word wrap

By default, the clients created by Quarkus CXF do not send the Authorization header, unless you set the quarkus.cxf.client."client-name".secure-wsdl-access to true:

application.properties

quarkus.cxf.client.basicAuthSecureWsdl.wsdl = http://localhost:${quarkus.http.test-port}/soap/basicAuth?wsdl
quarkus.cxf.client.basicAuthSecureWsdl.client-endpoint-url = http://localhost:${quarkus.http.test-port}/soap/basicAuthSecureWsdl
quarkus.cxf.client.basicAuthSecureWsdl.username = bob
quarkus.cxf.client.basicAuthSecureWsdl.password = ${client-server.bob.password}
quarkus.cxf.client.basicAuthSecureWsdl.secure-wsdl-access = true
Copy to Clipboard Toggle word wrap

6.1.2.2. Mutual TLS (mTLS) authentication
Copy link

See the Mutual TLS (mTLS) authentication section in SSL, TLS and HTTPS guide.

6.1.2.3. Securing service endpoints
Copy link

The server-side authentication and authorization is driven by Quarkus Security, especially when it comes to

There is a basic example in our Client and server integration test. Its key parts are:

  • io.quarkus:quarkus-elytron-security-properties-file dependency as an Identity provider

  • Basic authentication enabled and users with their roles configured in application.properties:

    application.properties

    quarkus.http.auth.basic = true
quarkus.security.users.embedded.enabled = true
quarkus.security.users.embedded.plain-text = true
quarkus.security.users.embedded.users.alice = alice123
quarkus.security.users.embedded.roles.alice = admin
quarkus.security.users.embedded.users.bob = bob234
quarkus.security.users.embedded.roles.bob = app-user
    Copy to Clipboard Toggle word wrap

  • Role-based access control enfoced via @RolesAllowed annotation:

BasicAuthHelloServiceImpl.java

package io.quarkiverse.cxf.it.auth.basic;

import jakarta.annotation.security.RolesAllowed;
import jakarta.jws.WebService;

import io.quarkiverse.cxf.it.HelloService;

@WebService(serviceName = "HelloService", targetNamespace = HelloService.NS)
@RolesAllowed("app-user")
public class BasicAuthHelloServiceImpl implements HelloService {
    @Override
    public String hello(String person) {
        return "Hello " + person + "!";
    }
}
Copy to Clipboard Toggle word wrap

You can enforce authentication through WS-SecurityPolicy, instead of Mutual TLS and Basic HTTP authentication for clients and services.

To enforce authentication through WS-SecurityPolicy, follow these steps:

  1. Add a supporting tokens policy to an endpoint in the WSDL contract.
  2. On the server side, implement an authentication callback handler and associate it with the endpoint in application.properties or via environment variables. Credentials received from clients are authenticated by the callback handler.
  3. On the client side, provide credentials through either configuration in application.properties or environment variables. Alternatively, you can implement an authentication callback handler to pass the credentials.

6.1.3.1. Specifying an Authentication Policy
Copy link

If you want to enforce authentication on a service endpoint, associate a supporting tokens policy assertion with the relevant endpoint binding and specify one or more token assertions under it.

There are several different kinds of supporting tokens policy assertions, whose XML element names all end with SupportingTokens (for example, SupportingTokens, SignedSupportingTokens, and so on). For a complete list, see the Supporting Tokens section of the WS-SecurityPolicy specification.

6.1.3.2. UsernameToken policy assertion example
Copy link

Tip

The sample code snippets used in this section come from the WS-SecurityPolicy integration test in the source tree of Quarkus CXF. You may want to use it as a runnable example.

The following listing shows an example of a policy that requires a WS-Security UsernameToken (which contains username/password credentials) to be included in the security header.

username-token-policy.xml

<?xml version="1.0" encoding="UTF-8"?>
<wsp:Policy
        wsp:Id="UsernameTokenSecurityServicePolicy"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
    xmlns:sp13="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200802"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <wsp:ExactlyOne>
        <wsp:All>
            <sp:SupportingTokens>
                <wsp:Policy>
                    <sp:UsernameToken
                        sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                        <wsp:Policy>
                            <sp:WssUsernameToken11 />
                            <sp13:Created />
                            <sp13:Nonce />
                        </wsp:Policy>
                    </sp:UsernameToken>
                </wsp:Policy>
            </sp:SupportingTokens>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>
Copy to Clipboard Toggle word wrap

There are two ways how you can associate this policy file with a service endpoint:

  • Reference the policy on the Service Endpoint Interface (SEI) like this:

    UsernameTokenPolicyHelloService.java

    @WebService(serviceName = "UsernameTokenPolicyHelloService")
@Policy(placement = Policy.Placement.BINDING, uri = "username-token-policy.xml")
public interface UsernameTokenPolicyHelloService extends AbstractHelloService {
    ...
}
    Copy to Clipboard Toggle word wrap

  • Include the policy in your WSDL contract and reference it via PolicyReference element.

When you have the policy in place, configure the credentials on the service endpoint and the client:

application.properties

# A service with a UsernameToken policy assertion
quarkus.cxf.endpoint."/helloUsernameToken".implementor = io.quarkiverse.cxf.it.security.policy.UsernameTokenPolicyHelloServiceImpl
quarkus.cxf.endpoint."/helloUsernameToken".security.callback-handler = #usernameTokenPasswordCallback

# These properties are used in UsernameTokenPasswordCallback
# and in the configuration of the helloUsernameToken below
wss.user = cxf-user
wss.password = secret

# A client with a UsernameToken policy assertion
quarkus.cxf.client.helloUsernameToken.client-endpoint-url = https://localhost:${quarkus.http.test-ssl-port}/services/helloUsernameToken
quarkus.cxf.client.helloUsernameToken.service-interface = io.quarkiverse.cxf.it.security.policy.UsernameTokenPolicyHelloService
quarkus.cxf.client.helloUsernameToken.security.username = ${wss.user}
quarkus.cxf.client.helloUsernameToken.security.password = ${wss.password}
Copy to Clipboard Toggle word wrap

In the above listing, usernameTokenPasswordCallback is a name of a @jakarta.inject.Named bean implementing javax.security.auth.callback.CallbackHandler. Quarkus CXF will lookup a bean with this name in the CDI container.

Here is an example implementation of the bean:

UsernameTokenPasswordCallback.java

package io.quarkiverse.cxf.it.security.policy;

import java.io.IOException;

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Named;

import org.apache.wss4j.common.ext.WSPasswordCallback;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
@Named("usernameTokenPasswordCallback") /* We refer to this bean by this name from application.properties */
public class UsernameTokenPasswordCallback implements CallbackHandler {

    /* These two configuration properties are set in application.properties */
    @ConfigProperty(name = "wss.password")
    String password;
    @ConfigProperty(name = "wss.user")
    String user;

    @Override
    public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
        if (callbacks.length < 1) {
            throw new IllegalStateException("Expected a " + WSPasswordCallback.class.getName()
                    + " at possition 0 of callbacks. Got array of length " + callbacks.length);
        }
        if (!(callbacks[0] instanceof WSPasswordCallback)) {
            throw new IllegalStateException(
                    "Expected a " + WSPasswordCallback.class.getName() + " at possition 0 of callbacks. Got an instance of "
                            + callbacks[0].getClass().getName() + " at possition 0");
        }
        final WSPasswordCallback pc = (WSPasswordCallback) callbacks[0];
        if (user.equals(pc.getIdentifier())) {
            pc.setPassword(password);
        } else {
            throw new IllegalStateException("Unexpected user " + user);
        }
    }

}
Copy to Clipboard Toggle word wrap

To test the whole setup, you can create a simple @QuarkusTest:

UsernameTokenTest.java

package io.quarkiverse.cxf.it.security.policy;

import org.assertj.core.api.Assertions;
import org.junit.jupiter.api.Test;

import io.quarkiverse.cxf.annotation.CXFClient;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
public class UsernameTokenTest {

    @CXFClient("helloUsernameToken")
    UsernameTokenPolicyHelloService helloUsernameToken;

    @Test
    void helloUsernameToken() {
        Assertions.assertThat(helloUsernameToken.hello("CXF")).isEqualTo("Hello CXF from UsernameToken!");
    }
}
Copy to Clipboard Toggle word wrap

When running the test via mvn test -Dtest=UsernameTokenTest, you should see a SOAP message being logged with a Security header containing Username and Password:

Log output of the UsernameTokenTest

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soap:mustUnderstand="1">
      <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-bac4f255-147e-42a4-aeec-e0a3f5cd3587">
        <wsse:Username>cxf-user</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">secret</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">3uX15dZT08jRWFWxyWmfhg==</wsse:Nonce>
        <wsu:Created>2024-10-02T17:32:10.497Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <ns2:hello xmlns:ns2="http://policy.security.it.cxf.quarkiverse.io/">
      <arg0>CXF</arg0>
    </ns2:hello>
  </soap:Body>
</soap:Envelope>
Copy to Clipboard Toggle word wrap

6.1.3.3. SAML v1 and v2 policy assertion examples
Copy link

The WS-SecurityPolicy integration test contains also analogous examples with SAML v1 and SAML v2 assertions.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top