此内容没有您所选择的语言版本。
Chapter 5. Quarkus CXF extensions reference
This chapter provides reference information about Quarkus CXF extensions.
5.1. Quarkus CXF
Core capabilities for implementing SOAP clients and JAX-WS services.
5.1.1. Maven coordinates
Create a new project using quarkus-cxf on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf</artifactId>
</dependency>5.1.2. Supported standards
5.1.3. Usage
There are several chapters in the User guide covering the usage of this extension.
5.1.4. Configuration
The padlock icon
indicates a configuration property that is fixed at build time. All other configuration properties are overridable at runtime.
| Configuration property | Type | Default |
|---|---|---|
|
|
| |
| The default path for CXF resources. Earlier versions
The default value before Quarkus CXF version 2.0.0 was
Environment variable: | ||
|
|
| |
| The size in bytes of the chunks of memory allocated when writing data. This is a very advanced setting that should only be set if you understand exactly how it affects the output IO operations of the application.
Environment variable: | ||
|
|
| |
| The size of the output stream response buffer in bytes. If a response is larger than this and no content-length is provided then the response will be chunked. Larger values may give slight performance increases for large responses, at the expense of more memory usage.
Environment variable: | ||
|
| ||
|
An URI base to use as a prefix of quarkus.cxf.decoupled-endpoint-base = https://api.example.com:${quarkus.http.ssl-port}${quarkus.cxf.path}
or, for plain HTTP: quarkus.cxf.decoupled-endpoint-base = http://api.example.com:${quarkus.http.port}${quarkus.cxf.path}
If you invoke your WS client from within a HTTP handler, you can leave this option unspecified and rather set it dynamically on the request context of your WS client using the import java.util.Map;
import jakarta.inject.Inject;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.UriInfo;
import jakarta.xml.ws.BindingProvider;
import io.quarkiverse.cxf.annotation.CXFClient;
import org.eclipse.microprofile.config.inject.ConfigProperty;
@Path("/my-rest")
public class MyRestEasyResource {
@Inject
@CXFClient("hello")
HelloService helloService;
@ConfigProperty(name = "quarkus.cxf.path")
String quarkusCxfPath;
@POST
@Path("/hello")
@Produces(MediaType.TEXT_PLAIN)
public String hello(String body, @Context UriInfo uriInfo) throws IOException {
// You may consider doing this only once if you are sure that your service is accessed
// through a single hostname
String decoupledEndpointBase = uriInfo.getBaseUriBuilder().path(quarkusCxfPath);
Map>String, Object< requestContext = ((BindingProvider)
helloService).getRequestContext();
requestContext.put("org.apache.cxf.ws.addressing.decoupled.endpoint.base",
decoupledEndpointBase);
return wsrmHelloService.hello(body);
}
}
Environment variable: | ||
|
|
| |
|
Specifies whether the message logging will be enabled for clients, services, both or none. This setting can be overridden per client or service endpoint using
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
| |
|
A message length in bytes at which it is truncated in the log. This setting can be overridden per client or service endpoint using
Environment variable: | ||
|
|
| |
|
A message length in bytes at which it will be written to disk.
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
List of | ||
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
List of | ||
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
List of | ||
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
List of | ||
|
A comma separated list of XML elements containing sensitive information to be masked in the log. This setting can be overridden per client or service endpoint using
Environment variable: | ||
|
List of | ||
|
A comma separated list of protocol headers containing sensitive information to be masked in the log. This setting can be overridden per client or service endpoint using
Environment variable: | ||
|
| ||
| The client service interface class name
Environment variable: | ||
|
|
| |
|
Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when configuring a client without annotation
Environment variable: | ||
|
|
| |
|
If
Setting this to
Environment variable: | ||
|
| ||
| The service endpoint implementation class
Environment variable: | ||
|
| ||
| The service endpoint WSDL path
Environment variable: | ||
|
| ||
| The URL of the SOAP Binding, should be one of four values:
Environment variable: | ||
|
| ||
| The published service endpoint URL
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
A message length in bytes at which it is truncated in the log. The default is given by
Environment variable: | ||
|
| ||
|
A message length in bytes at which it will be written to disk.
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
|
List of | |
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
|
List of | |
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
|
List of | |
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
|
List of | |
|
A comma separated list of XML elements containing sensitive information to be masked in the log. The default is given by
Environment variable: | ||
|
|
List of | |
|
A comma separated list of protocol headers containing sensitive information to be masked in the log. The default is given by
Environment variable: | ||
|
List of | ||
| A comma-separated list of fully qualified CXF Feature class names or named CDI beans. Examples: quarkus.cxf.endpoint."/hello".features = org.apache.cxf.ext.logging.LoggingFeature quarkus.cxf.endpoint."/fruit".features = #myCustomLoggingFeature
In the second case, the import org.apache.cxf.ext.logging.LoggingFeature;
import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.inject.Produces;
class Producers {
@Produces
@ApplicationScoped
LoggingFeature myCustomLoggingFeature() {
LoggingFeature loggingFeature = new LoggingFeature();
loggingFeature.setPrettyLogging(true);
return loggingFeature;
}
}
Environment variable: | ||
|
List of | ||
| The comma-separated list of Handler classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of InInterceptor classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of OutInterceptor classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of OutFaultInterceptor classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of InFaultInterceptor classes
Environment variable: | ||
|
|
| |
|
Select for which messages XML Schema validation should be enabled. If not specified, no XML Schema validation will be enforced unless it is enabled by other means, such as
Environment variable: | ||
|
| ||
| A URL, resource path or local filesystem path pointing to a WSDL document to use when generating the service proxy of this client.
Environment variable: | ||
|
| ||
| The URL of the SOAP Binding, should be one of four values:
Environment variable: | ||
|
| ||
| The client endpoint URL
Environment variable: | ||
|
| ||
| The client endpoint namespace
Environment variable: | ||
|
| ||
| The client endpoint name
Environment variable: | ||
|
| ||
| The username for HTTP Basic authentication
Environment variable: | ||
|
| ||
| The password for HTTP Basic authentication
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
A message length in bytes at which it is truncated in the log. The default is given by
Environment variable: | ||
|
| ||
|
A message length in bytes at which it will be written to disk.
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
| ||
|
If
Environment variable: | ||
|
|
List of | |
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
|
List of | |
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
|
List of | |
|
A comma separated list of additional binary media types to add to the default values in the
Environment variable: | ||
|
|
List of | |
|
A comma separated list of XML elements containing sensitive information to be masked in the log. The default is given by
Environment variable: | ||
|
|
List of | |
|
A comma separated list of protocol headers containing sensitive information to be masked in the log. The default is given by
Environment variable: | ||
|
List of | ||
| A comma-separated list of fully qualified CXF Feature class names. Example: quarkus.cxf.endpoint.myClient.features = org.apache.cxf.ext.logging.LoggingFeature
Environment variable: | ||
|
List of | ||
| The comma-separated list of Handler classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of InInterceptor classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of OutInterceptor classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of OutFaultInterceptor classes
Environment variable: | ||
|
List of | ||
| The comma-separated list of InFaultInterceptor classes
Environment variable: | ||
|
|
| |
| Specifies the amount of time, in milliseconds, that the consumer will attempt to establish a connection before it times out. 0 is infinite.
Environment variable: | ||
|
|
| |
| Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. 0 is infinite.
Environment variable: | ||
|
|
| |
| Specifies the amount of time, in milliseconds, used when requesting a connection from the connection manager(if appliable). 0 is infinite.
Environment variable: | ||
|
|
| |
| Specifies if the consumer will automatically follow a server issued redirection. (name is not part of standard)
Environment variable: | ||
|
|
| |
| Specifies the maximum amount of retransmits that are allowed for redirects. Retransmits for authorization is included in the retransmit count. Each redirect may cause another retransmit for a UNAUTHORIZED response code, ie. 401. Any negative number indicates unlimited retransmits, although, loop protection is provided. The default is unlimited. (name is not part of standard)
Environment variable: | ||
|
|
| |
| If true, the client is free to use chunking streams if it wants, but it is not required to use chunking streams. If false, the client must use regular, non-chunked requests in all cases.
Environment variable: | ||
|
|
| |
| If AllowChunking is true, this sets the threshold at which messages start getting chunked. Messages under this limit do not get chunked.
Environment variable: | ||
|
|
| |
| Specifies the chunk length for a HttpURLConnection. This value is used in java.net.HttpURLConnection.setChunkedStreamingMode(int chunklen). chunklen indicates the number of bytes to write in each chunk. If chunklen is less than or equal to zero, a default value will be used.
Environment variable: | ||
|
| ||
| Specifies the MIME types the client is prepared to handle (e.g., HTML, JPEG, GIF, etc.)
Environment variable: | ||
|
| ||
| Specifies the language the client desires (e.g., English, French, etc.)
Environment variable: | ||
|
| ||
| Specifies the encoding the client is prepared to handle (e.g., gzip)
Environment variable: | ||
|
| ||
| Specifies the content type of the stream being sent in a post request. (this should be text/xml for web services, or can be set to application/x-www-form-urlencoded if the client is sending form data).
Environment variable: | ||
|
| ||
| Specifies the Internet host and port number of the resource on which the request is being invoked. This is sent by default based upon the URL. Certain DNS scenarios or application designs may request you to set this, but typically it is not required.
Environment variable: | ||
|
|
| |
| The connection disposition. If close the connection to the server is closed after each request/response dialog. If Keep-Alive the client requests the server to keep the connection open, and if the server honors the keep alive request, the connection is reused. Many servers and proxies do not honor keep-alive requests.
Environment variable: | ||
|
| ||
| Most commonly used to specify no-cache, however the standard supports a dozen or so caching related directives for requests
Environment variable: | ||
|
|
| |
|
HTTP Version used for the connection. The default value
Some of these values might be unsupported by some
Environment variable: | ||
|
| ||
|
The value of the
Environment variable: | ||
|
| ||
|
An URI path (starting with
Environment variable: | ||
|
| ||
| Specifies the address of proxy server if one is used.
Environment variable: | ||
|
| ||
| Specifies the port number used by the proxy server.
Environment variable: | ||
|
| ||
| Specifies the list of hostnames that will not use the proxy configuration. Examples:
Environment variable: | ||
|
|
| |
| Specifies the type of the proxy server. Can be either HTTP or SOCKS.
Environment variable: | ||
|
| ||
| Username for the proxy authentication
Environment variable: | ||
|
| ||
| Password for the proxy authentication
Environment variable: | ||
|
| ||
|
Select the
Environment variable: | ||
|
| ||
| The trust store location for this client. The resource is first looked up in the classpath, then in the file system.
Environment variable: | ||
|
| ||
| The trust store password
Environment variable: | ||
|
|
| |
| The type of the trust store.
Environment variable: | ||
|
| ||
| Can be one of the following:
Environment variable: | ||
|
| ||
|
Select for which messages XML Schema validation should be enabled. If not specified, no XML Schema validation will be enforced unless it is enabled by other means, such as
Environment variable: | ||
5.2. Metrics Feature
Collect metrics using Micrometer.
Unlike CXF Metrics feature, this Quarkus CXF extension does not support Dropwizard Metrics. Only Micrometer is supported.
5.2.1. Maven coordinates
Create a new project using quarkus-cxf-rt-features-metrics on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-rt-features-metrics</artifactId>
</dependency>5.2.2. Usage
The integration of CXF into the Quarkus Micrometer ecosystem is implemented using io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature. As long as your application depends on quarkus-cxf-rt-features-metrics, an instance of QuarkusCxfMetricsFeature is created internally and enabled by default for all clients and service endpoints created by Quarkus CXF. You can disable it via quarkus.cxf.metrics.enabled-for, quarkus.cxf.client."clients".metrics.enabled and quarkus.cxf.endpoint."endpoints".metrics.enabled properties documented below.
5.2.2.1. Runnable example
There is an integration test covering Micrometer Metrics in the Quarkus CXF source tree.
Unsurprisingly, it depends on quarkus-cxf-rt-features-metrics
pom.xml
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-rt-features-metrics</artifactId>
</dependency>
It is using quarkus-micrometer-registry-prometheus extension to export the metrics in JSON format and for Prometheus:
pom.xml
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>
The following configuration is needed to be able to inspect the collected metrics over a REST endpoint:
application.properties
quarkus.micrometer.export.json.enabled = true quarkus.micrometer.export.json.path = metrics/json quarkus.micrometer.export.prometheus.path = metrics/prometheus
Having all the above in place, you can start the application in Dev mode:
$ mvn quarkus:dev
Now send a request to the HelloService:
$ curl \ -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:helloResponse xmlns:ns2="http://it.server.metrics.cxf.quarkiverse.io/"><return>Hello Joe!</return></ns2:helloResponse></soap:Body></soap:Envelope>' \ -H 'Content-Type: text/xml' \ -X POST \ http://localhost:8080/metrics/client/hello
After that, metrics are shown under cxf.server.requests in the output of the endpoint you configured above:
$ curl http://localhost:8080/q/metrics/json
metrics: {
...
"cxf.server.requests": {
"count;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 2,
"elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 64.4
},
...
}5.2.3. Configuration
Configuration property fixed at build time. All other configuration properties are overridable at runtime.
| Configuration property | Type | Default |
|---|---|---|
|
|
| |
|
Specifies whether the metrics collection will be enabled for clients, services, both or none. This global setting can be overridden per client or service endpoint using the
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
5.3. OpenTelemetry
Generate OpenTelemetry traces.
OpenTelemetry Metrics and Logging are not supported yet on neither Quarkus nor CXF side, hence Quarkus CXF cannot support them either. Therefore, tracing is the only OpenTelemetry feature supported by this extension.
5.3.1. Maven coordinates
Create a new project using quarkus-cxf-integration-tracing-opentelemetry on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-integration-tracing-opentelemetry</artifactId>
</dependency>5.3.2. Usage
This extension builds on top of org.apache.cxf.tracing.opentelemetry.OpenTelemetryFeature (for service endpoints) and org.apache.cxf.tracing.opentelemetry.OpenTelemetryClientFeature (for clients). Instances of these are created and configured internally using the instance of io.opentelemetry.api.OpenTelemetry provided by Quarkus OpenTelemetry.
The tracing is enabled by default for all clients and service endpoints created by Quarkus CXF, unless you disable it explicitly via quarkus.cxf.otel.enabled-for, quarkus.cxf.client."clients".otel.enabled or quarkus.cxf.endpoint."endpoints".otel.enabled.
5.3.2.1. Runnable example
There is an integration test covering OpenTelemetry in the Quarkus CXF source tree. It is using InMemorySpanExporter from io.opentelemetry:opentelemetry-sdk-testing, so that the spans can be inspected from tests easily. Refer to Quarkus OpenTelemetry guide for information about other supported span exporters and collectors.
5.3.3. Configuration
Configuration property fixed at build time. All other configuration properties are overridable at runtime.
| Configuration property | Type | Default |
|---|---|---|
|
|
| |
|
Specifies whether the OpenTelemetry tracing will be enabled for clients, services, both or none. This global setting can be overridden per client or service endpoint using the
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
5.4. WS-Security
Provides CXF framework’s WS-Security implementation allowing you to:
- Pass authentication tokens between services
- Encrypt messages or parts of messages
- Sign messages
- Timestamp messages
5.4.1. Maven coordinates
Create a new project using quarkus-cxf-rt-ws-security on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-rt-ws-security</artifactId>
</dependency>5.4.2. Supported standards
5.4.3. Usage
The CXF framework’s WS-Security (WSS) implementation is based on WSS4J. It can be activated in two ways:
- By using WS-SecurityPolicy
- By adding WSS4J interceptors to your clients and service endpoints.
WS-SecurityPolicy is preferable because in that way, the security requirements become a part of the WSDL contract. That in turn greatly simplifies not only the implementation of clients and service endpoints but also the interoperability between vendors.
Nevertheless, if you leverage WS-SecurityPolicy, CXF sets up the WSS4J interceptors under the hood for you.
We won’t explain the manual approach with WSS4J interceptors in detail here, but you can still refer to our WS-Security integration test as an example.
5.4.3.1. WS-Security via WS-SecurityPolicy
The sample code snippets used in this section come from the WS-SecurityPolicy integration test in the source tree of Quarkus CXF
Let’s say our aim is to ensure that the communication between the client and service is confidential (through encryption) and that the message has not been tampered with (through digital signatures). We also want to assure that the clients are who they claim to be by authenticating themselves by X.509 certificates.
We can express all these requirements in a single WS-SecurityPolicy document:
encrypt-sign-policy.xml
<?xml version="1.0" encoding="UTF-8" ?>
<wsp:Policy wsu:Id="SecurityServiceEncryptThenSignPolicy"
xmlns:wsp="http://www.w3.org/ns/ws-policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
<wsp:ExactlyOne>
<wsp:All>
1
<sp:AsymmetricBinding xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
<wsp:Policy>
2
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssX509V3Token11/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
<wsp:Policy>
<sp:WssX509V3Token11/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:ProtectTokens/>
<sp:OnlySignEntireHeadersAndBody/>
<sp:EncryptBeforeSigning/>
</wsp:Policy>
</sp:AsymmetricBinding>
3
<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body/>
</sp:SignedParts>
4
<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body/>
</sp:EncryptedParts>
<sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:MustSupportRefIssuerSerial/>
</wsp:Policy>
</sp:Wss10>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
- 1
AsymmetricBindingspecifies the use of asymmetric (public/private key) cryptography for securing the communication between two parties- 2
InitiatorTokenindicates that the initiator (sender) of the message will use an X.509 certificate token that must always be provided to the recipient.- 3
SignedPartsspecifies which parts of the SOAP message must be signed to ensure their integrity.- 4
EncryptedPartsspecifies the parts of the SOAP message that must be encrypted to ensure their confidentiality.
We set this policy on the Service Endpoint Interface (SEI) EncryptSignPolicyHelloService using @org.apache.cxf.annotations.Policy annotation:
EncryptSignPolicyHelloService.java
@WebService(serviceName = "EncryptSignPolicyHelloService")
@Policy(placement = Policy.Placement.BINDING, uri = "encrypt-sign-policy.xml")
public interface EncryptSignPolicyHelloService extends AbstractHelloService {
...
}
On the first sight, setting the policy on the SEI should suffice to enforce it on both the service and all clients generated from the SEI or from the WSDL served by the service. However, that’s not all. Security keys, usernames, passwords and other kinds of confidental information cannot be exposed in a public policy.
Those have to be set in the configuration.
The server and client references helloEncryptSign differently, since there are differences in what the reference represents:
The server reference is a path to the service endpoint, accessible via HTTP, which means it has to start with /.
The client reference is a label. It is used to group the client options and to specify the client for injection with @CXFClient("helloEncryptSign").
The label for the client can be completely different (for example, e.g. foo), or start with /. To associate with the service, the important thing is that you provide a correct client-endpoint-url value.
Let’s do it for the service first:
application.properties
# A service with encrypt-sign-policy.xml set
quarkus.cxf.endpoint."/helloEncryptSign".implementor = io.quarkiverse.cxf.it.security.policy.EncryptSignPolicyHelloServiceImpl
# can be jks or pkcs12 - set from Maven profiles in this test
keystore.type = ${keystore.type}
# Signature settings
quarkus.cxf.endpoint."/helloEncryptSign".security.signature.username = bob
quarkus.cxf.endpoint."/helloEncryptSign".security.signature.password = password
quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = ${keystore.type}
quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = bob
quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.file" = bob.${keystore.type}
# Encryption settings
quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.username = alice
quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = ${keystore.type}
quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = bob
quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.file" = bob.${keystore.type}
Similar setup is necessary on the client side:
application.properties
# A client with encrypt-sign-policy.xml set
quarkus.cxf.client.helloEncryptSign.client-endpoint-url = https://localhost:${quarkus.http.test-ssl-port}/services/helloEncryptSign
quarkus.cxf.client.helloEncryptSign.service-interface = io.quarkiverse.cxf.it.security.policy.EncryptSignPolicyHelloService
quarkus.cxf.client.helloEncryptSign.features = #messageCollector
# The client-endpoint-url above is HTTPS, so we have to setup the server's SSL certificates
quarkus.cxf.client.helloEncryptSign.trust-store = client-truststore.${keystore.type}
quarkus.cxf.client.helloEncryptSign.trust-store-password = password
# Signature settings
quarkus.cxf.client.helloEncryptSign.security.signature.username = alice
quarkus.cxf.client.helloEncryptSign.security.signature.password = password
quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = alice
quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.file" = alice.${keystore.type}
# Encryption settings
quarkus.cxf.client.helloEncryptSign.security.encryption.username = bob
quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = alice
quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.file" = alice.${keystore.type}
To inspect the flow of the messages, you can execute the EncryptSignPolicyTest as follows:
# Clone the repository $ git clone https://github.com/quarkiverse/quarkus-cxf.git -o upstream $ cd quarkus-cxf # Build the whole source tree $ mvn clean install -DskipTests -Dquarkus.build.skip # Run the test $ cd integration-tests/ws-security-policy $ mvn clean test -Dtest=EncryptSignPolicyTest
Some messages containing Signature elements and encrypted bodies are shown in the console output.
5.4.4. Configuration
Configuration property fixed at build time. All other configuration properties are overridable at runtime.
| Configuration property | Type | Default |
|---|---|---|
|
| ||
| The user’s name. It is used as follows:
Environment variable: | ||
|
| ||
|
The user’s password when a
Environment variable: | ||
|
| ||
|
The user’s name for signature. It is used as the alias name in the keystore to get the user’s cert and private key for signature. If this is not defined, then
Environment variable: | ||
|
| ||
|
The user’s password for signature when a
Environment variable: | ||
|
| ||
|
The user’s name for encryption. It is used as the alias name in the keystore to get the user’s public key for encryption. If this is not defined, then
For the WS-Security web service provider, the
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
| ||
|
The Crypto property configuration to use for signing, if Example [prefix].signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin [prefix].signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password [prefix].signature.properties."org.apache.ws.security.crypto.merlin.file" = certs/alice.jks
Environment variable: | ||
|
| ||
|
The Crypto property configuration to use for encryption, if Example [prefix].encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin [prefix].encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password [prefix].encryption.properties."org.apache.ws.security.crypto.merlin.file" = certs/alice.jks
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
|
| |
|
A message property for prepared X509 certificate to be used for encryption. If this is not defined, then the certificate will be either loaded from the keystore This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If Signature The label "unsigned" refers to an internal signature. Even if the token is signed by an external signature (as per the "sender-vouches" requirement), this boolean must still be configured if you want to use the token to set up the security context. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
The attribute URI of the SAML This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A String of regular expressions (separated by the value specified in This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The separator that is used to parse certificate constraints configured in This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
The actor or role name of the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
|
|
|
Whether to always encrypt This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
If Caching
Caching only applies when either a
Environment variable: | ||
|
|
| |
|
If Caching
Caching only applies when either a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
| |
|
If The "real" security errors should not be returned to the client in production, as they may leak information about the deployment, or otherwise provide an "oracle" for attacks.
Environment variable: | ||
|
|
| |
|
If
Works only with
Environment variable: | ||
|
| ||
|
If
Caching only applies when either a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
| Whether to store bytes (CipherData or BinarySecurityToken) in an attachment. The default is true if MTOM is enabled. Set it to false to BASE-64 encode the bytes and "inlined" them in the message instead. Setting this to true is more efficient, as it means that the BASE-64 encoding step can be skipped. This only applies to the DOM WS-Security stack. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If
Some frameworks cannot process the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If Some servers may not do client certificate verification at the start of the SSL handshake, and therefore the client certificates may not be available to the WS-Security layer for policy verification. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
The time in seconds to add to the Creation value of an incoming This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The time in seconds in the future within which the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The time in seconds to append to the Creation value of an incoming This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The time in seconds in the future within which the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
Set this property to point to a configuration file for the underlying caching implementation for the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
The Cache Identifier to use with the TokenStore. CXF uses the following key to retrieve a token store:
The default This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
The Subject Role Classifier to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
The Subject Role Classifier Type to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
| This configuration tag allows the user to override the default Asymmetric Signature algorithm (RSA-SHA1) for use in WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
| This configuration tag allows the user to override the default Symmetric Signature algorithm (HMAC-SHA1) for use in WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a
By default, WSS4J uses the The encrypted passwords must be stored in the format "ENC(encoded encrypted password)". This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
A reference to a Kerberos This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
| The security token lifetime value (in milliseconds). This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
| The JAAS Context name to use for Kerberos. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
| The Kerberos Service Provider Name (spn) to use. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
A reference to a fully configured
To work around the fact that Tip Check the Security Token Service (STS) extension page for more information about WS-Trust.
Environment variable: | ||
|
| ||
| A URL, resource path or local filesystem path pointing to a WSDL document to use when generating the service proxy of the STS client.
Environment variable: | ||
|
|
| |
| A fully qualified name of the STS service. Common values include:
Environment variable: | ||
|
|
| |
| A fully qualified name of the STS endpoint name. Common values include:
Environment variable: | ||
|
| ||
| The user name to use when authenticating against the STS. It is used as follows:
Environment variable: | ||
|
| ||
|
The password associated with the
Environment variable: | ||
|
|
| |
|
The user’s name for encryption. It is used as the alias name in the keystore to get the user’s public key for encryption. If this is not defined, then
For the WS-Security web service provider, the
Environment variable: | ||
|
|
| |
|
The Crypto property configuration to use for encryption, if Example [prefix].encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin [prefix].encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password [prefix].encryption.properties."org.apache.ws.security.crypto.merlin.file" = certs/alice.jks
Environment variable: | ||
|
|
| |
|
A reference to a
Environment variable: | ||
|
|
| |
|
A reference to a WCF’s trust server sometimes will encrypt the token in the response IN ADDITION TO the full security on the message. These properties control the way the STS client will decrypt the EncryptedData elements in the response.
These are also used by the
Environment variable: | ||
|
|
| |
|
The Crypto property configuration to use for encryption, if Example [prefix].token.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin [prefix].token.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password [prefix].token.properties."org.apache.ws.security.crypto.merlin.file" = certs/alice.jks
Environment variable: | ||
|
|
| |
| The alias name in the keystore to get the user’s public key to send to the STS for the PublicKey KeyType case.
Environment variable: | ||
|
|
|
|
| Whether to write out an X509Certificate structure in UseKey/KeyInfo, or whether to write out a KeyValue structure.
Environment variable: | ||
|
|
|
|
|
If
Environment variable: | ||
|
| ||
| The user’s name. It is used as follows:
Environment variable: | ||
|
| ||
|
The user’s password when a
Environment variable: | ||
|
|
| |
|
The user’s name for signature. It is used as the alias name in the keystore to get the user’s cert and private key for signature. If this is not defined, then
Environment variable: | ||
|
|
| |
|
The user’s password for signature when a
Environment variable: | ||
|
|
| |
|
The user’s name for encryption. It is used as the alias name in the keystore to get the user’s public key for encryption. If this is not defined, then
For the WS-Security web service provider, the
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
|
| |
|
A reference to a
Environment variable: | ||
|
|
| |
|
The Crypto property configuration to use for signing, if Example [prefix].signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin [prefix].signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password [prefix].signature.properties."org.apache.ws.security.crypto.merlin.file" = certs/alice.jks
Environment variable: | ||
|
|
| |
|
The Crypto property configuration to use for encryption, if Example [prefix].encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin [prefix].encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password [prefix].encryption.properties."org.apache.ws.security.crypto.merlin.file" = certs/alice.jks
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
|
| |
|
A message property for prepared X509 certificate to be used for encryption. If this is not defined, then the certificate will be either loaded from the keystore This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If Signature The label "unsigned" refers to an internal signature. Even if the token is signed by an external signature (as per the "sender-vouches" requirement), this boolean must still be configured if you want to use the token to set up the security context. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
The attribute URI of the SAML This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A String of regular expressions (separated by the value specified in This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The separator that is used to parse certificate constraints configured in This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
The actor or role name of the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
|
|
|
Whether to always encrypt This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If Caching
Caching only applies when either a
Environment variable: | ||
|
|
| |
|
If Caching
Caching only applies when either a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
|
|
|
If The "real" security errors should not be returned to the client in production, as they may leak information about the deployment, or otherwise provide an "oracle" for attacks.
Environment variable: | ||
|
|
| |
|
If
Works only with
Environment variable: | ||
|
| ||
|
If
Caching only applies when either a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
| Whether to store bytes (CipherData or BinarySecurityToken) in an attachment. The default is true if MTOM is enabled. Set it to false to BASE-64 encode the bytes and "inlined" them in the message instead. Setting this to true is more efficient, as it means that the BASE-64 encoding step can be skipped. This only applies to the DOM WS-Security stack. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If
Some frameworks cannot process the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If Some servers may not do client certificate verification at the start of the SSL handshake, and therefore the client certificates may not be available to the WS-Security layer for policy verification. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The time in seconds to add to the Creation value of an incoming This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The time in seconds in the future within which the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The time in seconds to append to the Creation value of an incoming This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The time in seconds in the future within which the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
Set this property to point to a configuration file for the underlying caching implementation for the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
The Cache Identifier to use with the TokenStore. CXF uses the following key to retrieve a token store:
The default This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
The Subject Role Classifier to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
The Subject Role Classifier Type to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then the This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
| This configuration tag allows the user to override the default Asymmetric Signature algorithm (RSA-SHA1) for use in WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
| This configuration tag allows the user to override the default Symmetric Signature algorithm (HMAC-SHA1) for use in WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a
By default, WSS4J uses the The encrypted passwords must be stored in the format "ENC(encoded encrypted password)". This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a Kerberos This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
| The security token lifetime value (in milliseconds). This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
|
|
|
If This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
|
| |
| The JAAS Context name to use for Kerberos. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
| The Kerberos Service Provider Name (spn) to use. This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
|
| ||
|
A reference to a This option is experimental, because it is not covered by tests yet.
Environment variable: | ||
5.5. WS-ReliableMessaging
WS-ReliableMessaging (WS-RM) is a protocol ensuring a reliable delivery of messages in a distributed environment even in presence of software, system, or network failures.
This extension provides CXF framework’s WS-ReliableMessaging implementation.
5.5.1. Maven coordinates
Create a new project using quarkus-cxf-rt-ws-rm on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-rt-ws-rm</artifactId>
</dependency>5.5.2. Supported standards
5.5.3. Usage
Once your application depends on quarkus-cxf-rt-ws-rm, WS-RM is enabled for all clients and service endpoints defined in application.properties. This is due to the fact that the quarkus.cxf.client.myClient.rm.enabled and quarkus.cxf.endpoint."/my-endpoint".rm.enabled properties are true by default.
Enabling WS-RM for a client or service endpoints means that WS-RM interceptors will be added to the given client or endpoint.
In addition to that you may want to set some of the configuration options or the following WS-Addressing options:
5.5.3.1. Runnable example
There is an integration test covering WS-RM with a decoupled endpoint in the Quarkus CXF source tree.
It is split into two separate applications that communicate with each other:
To run it, you need to install the server into your local Maven repository first
$ cd test-util-parent/test-ws-rm-server-jvm $ mvn clean install
And then you can run the test scenario implemented in the client module:
$ cd ../../integration-tests/ws-rm-client $ mvn clean test
The exchange of SOAP messages between the client, the server and the decoupled endpoint are shown in the console.
5.5.4. Configuration
Configuration property fixed at build time. All other configuration properties are overridable at runtime.
| Configuration property | Type | Default |
|---|---|---|
|
| ||
|
WS-RM version namespace:
Environment variable: | ||
|
| ||
|
WS-Addressing version namespace:
Environment variable: | ||
|
| ||
| A time duration in milliseconds after which the associated sequence will be closed if no messages (including acknowledgments and other control messages) were exchanged between the sender and receiver during that period of time. If not set, the associated sequence will never be closed due to inactivity.
Environment variable: | ||
|
|
| |
| A time duration in milliseconds between successive attempts to resend a message that has not been acknowledged by the receiver.
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
| ||
| A time duration in milliseconds within which an acknowledgement for a received message is expected to be sent by a RM destination. If not specified, the acknowledgements will be sent immediately.
Environment variable: | ||
|
| ||
|
A reference to a
Environment variable: | ||
|
|
| |
|
A reference to a
If the value is
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
|
|
| |
|
If
Environment variable: | ||
5.6. Security Token Service (STS)
Issue, renew and validate security tokens in context of WS-Trust.
5.6.1. Maven coordinates
Create a new project using quarkus-cxf-services-sts on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-services-sts</artifactId>
</dependency>5.6.2. Supported standards
5.6.3. Usage
Here are the key parts of a basic WS-Trust scenario:
-
WS-SecurityPolicy - except for defining security requirements, such as transport protocols, encryption and signing, it can also contain an
<IssuedToken>assertion. It specifies the requirements and constraints for these security tokens that the client must adhere to when accessing the service. - Security Token Service (STS) - issues, validates, and renews security tokens upon request. It acts as a trusted authority that authenticates clients and issues tokens that assert the client’s identity and permissions.
- Client - requests a token from the STS to access a web service. It must authenticate itself to the STS and provide details about the kind of token required.
- Service - relies on the STS to authenticate clients and validate their tokens.
5.6.3.1. Runnable example
There is an integration test covering WS-Trust in the Quarkus CXF source tree. Let’s walk through it and see how the individual parts are set to work together.
5.6.3.1.1. WS-SecurityPolicy
The policy is located in asymmetric-saml2-policy.xml file. Its key part is the <IssuedToken> assertion requiring a SAML 2.0 token:
asymmetric-saml2-policy.xml
<sp:IssuedToken
sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<sp:RequestSecurityTokenTemplate>
<t:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</t:TokenType>
<t:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey</t:KeyType>
</sp:RequestSecurityTokenTemplate>
<wsp:Policy>
<sp:RequireInternalReference />
</wsp:Policy>
<sp:Issuer>
<wsaws:Address>http://localhost:8081/services/sts</wsaws:Address>
<wsaws:Metadata xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance"
wsdli:wsdlLocation="http://localhost:8081/services/sts?wsdl">
<wsaw:ServiceName xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
xmlns:stsns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
EndpointName="UT_Port">stsns:SecurityTokenService</wsaw:ServiceName>
</wsaws:Metadata>
</sp:Issuer>
</sp:IssuedToken>
5.6.3.1.2. Security Token Service (STS)
The STS is implemented in Sts.java:
Sts.java
@WebServiceProvider(serviceName = "SecurityTokenService", portName = "UT_Port", targetNamespace = "http://docs.oasis-open.org/ws-sx/ws-trust/200512/", wsdlLocation = "ws-trust-1.4-service.wsdl")
public class Sts extends SecurityTokenServiceProvider {
public Sts() throws Exception {
super();
StaticSTSProperties props = new StaticSTSProperties();
props.setSignatureCryptoProperties("stsKeystore.properties");
props.setSignatureUsername("sts");
props.setCallbackHandlerClass(StsCallbackHandler.class.getName());
props.setIssuer("SampleSTSIssuer");
List<ServiceMBean> services = new LinkedList<ServiceMBean>();
StaticService service = new StaticService();
final Config config = ConfigProvider.getConfig();
final int port = LaunchMode.current().equals(LaunchMode.TEST) ? config.getValue("quarkus.http.test-port", Integer.class)
: config.getValue("quarkus.http.port", Integer.class);
service.setEndpoints(Arrays.asList(
"http://localhost:" + port + "/services/hello-ws-trust",
"http://localhost:" + port + "/services/hello-ws-trust-actas",
"http://localhost:" + port + "/services/hello-ws-trust-onbehalfof"));
services.add(service);
TokenIssueOperation issueOperation = new TokenIssueOperation();
issueOperation.setServices(services);
issueOperation.getTokenProviders().add(new SAMLTokenProvider());
// required for OnBehalfOf
issueOperation.getTokenValidators().add(new UsernameTokenValidator());
// added for OnBehalfOf and ActAs
issueOperation.getDelegationHandlers().add(new UsernameTokenDelegationHandler());
issueOperation.setStsProperties(props);
TokenValidateOperation validateOperation = new TokenValidateOperation();
validateOperation.getTokenValidators().add(new SAMLTokenValidator());
validateOperation.setStsProperties(props);
this.setIssueOperation(issueOperation);
this.setValidateOperation(validateOperation);
}
}
and configured in application.properties:
application.properties
quarkus.cxf.endpoint."/sts".implementor = io.quarkiverse.cxf.it.ws.trust.sts.Sts quarkus.cxf.endpoint."/sts".logging.enabled = pretty quarkus.cxf.endpoint."/sts".security.signature.username = sts quarkus.cxf.endpoint."/sts".security.signature.password = password quarkus.cxf.endpoint."/sts".security.validate.token = false quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12 quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.file" = sts.pkcs12
5.6.3.1.3. Service
The service is implemented in TrustHelloServiceImpl.java:
TrustHelloServiceImpl.java
@WebService(portName = "TrustHelloServicePort", serviceName = "TrustHelloService", targetNamespace = "https://quarkiverse.github.io/quarkiverse-docs/quarkus-cxf/test/ws-trust", endpointInterface = "io.quarkiverse.cxf.it.ws.trust.server.TrustHelloService")
public class TrustHelloServiceImpl implements TrustHelloService {
@WebMethod
@Override
public String hello(String person) {
return "Hello " + person + "!";
}
}
The asymmetric-saml2-policy.xml mentioned above is set in the Service Endpoint Interface TrustHelloService.java:
TrustHelloServiceImpl.java
@WebService(targetNamespace = "https://quarkiverse.github.io/quarkiverse-docs/quarkus-cxf/test/ws-trust")
@Policy(placement = Policy.Placement.BINDING, uri = "classpath:/asymmetric-saml2-policy.xml")
public interface TrustHelloService {
@WebMethod
@Policies({
@Policy(placement = Policy.Placement.BINDING_OPERATION_INPUT, uri = "classpath:/io-policy.xml"),
@Policy(placement = Policy.Placement.BINDING_OPERATION_OUTPUT, uri = "classpath:/io-policy.xml")
})
String hello(String person);
}
The service endpoint is configured in application.properties:
application.properties
quarkus.cxf.endpoint."/hello-ws-trust".implementor = io.quarkiverse.cxf.it.ws.trust.server.TrustHelloServiceImpl quarkus.cxf.endpoint."/hello-ws-trust".logging.enabled = pretty quarkus.cxf.endpoint."/hello-ws-trust".security.signature.username = service quarkus.cxf.endpoint."/hello-ws-trust".security.signature.password = password quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12 quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = service quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.file" = service.pkcs12 quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12 quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = service quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.file" = service.pkcs12
5.6.3.1.4. Client
Finally, for the SOAP client to be able to communicate with the service, its STSClient needs to be configured. It can be done in application.properties:
application.properties
quarkus.cxf.client.hello-ws-trust.security.sts.client.wsdl = http://localhost:${quarkus.http.test-port}/services/sts?wsdl
quarkus.cxf.client.hello-ws-trust.security.sts.client.service-name = {http://docs.oasis-open.org/ws-sx/ws-trust/200512/}SecurityTokenService
quarkus.cxf.client.hello-ws-trust.security.sts.client.endpoint-name = {http://docs.oasis-open.org/ws-sx/ws-trust/200512/}UT_Port
quarkus.cxf.client.hello-ws-trust.security.sts.client.username = client
quarkus.cxf.client.hello-ws-trust.security.sts.client.password = password
quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.username = sts
quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = client
quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.file" = client.pkcs12
quarkus.cxf.client.hello-ws-trust.security.sts.client.token.username = client
quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = client
quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.file" = client.pkcs12
quarkus.cxf.client.hello-ws-trust.security.sts.client.token.usecert = true
The properties for configuring the STS client are provided by the io.quarkiverse.cxf:quarkus-cxf-rt-ws-security extension and documented on its reference page.
Alternatively, the client can be set as a bean reference:
application.properties
quarkus.cxf.client.hello-ws-trust-bean.security.sts.client = #stsClientBean
In that case, the @Named bean needs to be produced programmatically, e.g. using @jakarta.enterprise.inject.Produces:
BeanProducers.java
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Produces;
import jakarta.inject.Named;
import org.apache.cxf.ws.security.SecurityConstants;
import io.quarkiverse.cxf.ws.security.sts.client.STSClientBean;
public class BeanProducers {
/**
* Create and configure an STSClient for use by the TrustHelloService client.
*/
@Produces
@ApplicationScoped
@Named("stsClientBean")
STSClientBean createSTSClient() {
/*
* We cannot use org.apache.cxf.ws.security.trust.STSClient as a return type of this bean producer method
* because it does not have a no-args constructor. STSClientBean is a subclass of STSClient having one.
*/
STSClientBean stsClient = STSClientBean.create();
stsClient.setWsdlLocation("http://localhost:8081/services/sts?wsdl");
stsClient.setServiceQName(new QName("http://docs.oasis-open.org/ws-sx/ws-trust/200512/", "SecurityTokenService"));
stsClient.setEndpointQName(new QName("http://docs.oasis-open.org/ws-sx/ws-trust/200512/", "UT_Port"));
Map<String, Object> props = stsClient.getProperties();
props.put(SecurityConstants.USERNAME, "client");
props.put(SecurityConstants.PASSWORD, "password");
props.put(SecurityConstants.ENCRYPT_PROPERTIES,
Thread.currentThread().getContextClassLoader().getResource("clientKeystore.properties"));
props.put(SecurityConstants.ENCRYPT_USERNAME, "sts");
props.put(SecurityConstants.STS_TOKEN_USERNAME, "client");
props.put(SecurityConstants.STS_TOKEN_PROPERTIES,
Thread.currentThread().getContextClassLoader().getResource("clientKeystore.properties"));
props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true");
return stsClient;
}
}
5.7. HTTP Async Transport
Implement async SOAP Clients using Apache HttpComponents HttpClient 5.
5.7.1. Maven coordinates
Create a new project using quarkus-cxf-rt-transports-http-hc5 on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-rt-transports-http-hc5</artifactId>
</dependency>5.7.2. Usage
Once the quarkus-cxf-rt-transports-http-hc5 dependency is available in the classpath, CXF will use HttpAsyncClient for asynchronous calls and will continue using HttpURLConnection for synchronous calls.
5.7.2.1. Generate async methods
Asynchronous client invocations require some additional methods in the service endpoint interface. That code is not generated by default.
To enable it, you need to create a JAX-WS binding file with enableAsyncMapping set to true:
The sample code snippets used in this section come from the HC5 integration test in the source tree of Quarkus CXF
src/main/resources/wsdl/async-binding.xml
<?xml version="1.0"?>
<bindings
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="https://jakarta.ee/xml/ns/jaxws"
wsdlLocation="CalculatorService.wsdl">
<bindings node="wsdl:definitions">
<enableAsyncMapping>true</enableAsyncMapping>
</bindings>
</bindings>
This file should then be passed to wsdl2java through its additional-params property:
application.properties
quarkus.cxf.codegen.wsdl2java.includes = wsdl/*.wsdl quarkus.cxf.codegen.wsdl2java.additional-params = -b,src/main/resources/wsdl/async-binding.xml
5.7.2.2. Asynchronous Clients and Mutiny
Once the asynchronous stubs are available, it is possible to wrap a client call in io.smallrye.mutiny.Uni as shown below:
package io.quarkiverse.cxf.hc5.it;
import java.util.concurrent.Future;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;
import org.jboss.eap.quickstarts.wscalculator.calculator.AddResponse;
import org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService;
import io.quarkiverse.cxf.annotation.CXFClient;
import io.smallrye.mutiny.Uni;
@Path("/hc5")
public class Hc5Resource {
@Inject
@CXFClient("myCalculator") // name used in application.properties
CalculatorService myCalculator;
@SuppressWarnings("unchecked")
@Path("/add-async")
@GET
@Produces(MediaType.TEXT_PLAIN)
public Uni<Integer> addAsync(@QueryParam("a") int a, @QueryParam("b") int b) {
return Uni.createFrom()
.future(
(Future<AddResponse>) myCalculator
.addAsync(a, b, res -> {
}))
.map(addResponse -> addResponse.getReturn());
}
}5.7.2.3. Thread pool
Asynchronous clients delivered by this extension leverage ManagedExecutor with a thread pool provided by Quarkus. The thread pool can be configured using the quarkus.thread-pool.* family of options. As a consequence of this, the executor and thread pool related attributes of org.apache.cxf.transports.http.configuration.HTTPClientPolicy are not honored for async clients on Quarkus.
You can see more details about the CXF asynchronous client and how to tune it further in CXF documentation.
5.8. XJC Plugins
XJC plugins for wsdl2java code generation. You’ll need to add this extension if you want to use any of the following in quarkus.cxf.codegen.wsdl2java.additional-params:
-
-xjc-Xbg- generategetFoo()instead ofisFoo()accessor methods for boolean fields. -
-xjc-Xdv- let the generated getter methods return the default value defined in the schema unless the field is set explicitly. -
-xjc-Xjavadoc- generate JavaDoc based onxs:documentationpresent in the schema. -
-xjc-Xproperty-listener- addPropertyChangeListenersupport to the generated beans. -
-xjc-Xts- generatetoString()methods in model classes. -
-xjc-Xwsdlextension- generate beans that can be used directly with WSDL4J as extensors in the WSDL.
Check the wsdl2java section of User guide for more details about wsdl2java.
5.8.1. Maven coordinates
Create a new project using quarkus-cxf-xjc-plugins on code.quarkus.redhat.com or add these coordinates to your existing project:
<dependency>
<groupId>io.quarkiverse.cxf</groupId>
<artifactId>quarkus-cxf-xjc-plugins</artifactId>
</dependency>