Have a separate docs page for configuring SSL on clients and server fix

#1076
quarkiverse · Dec 24, 2023 · 40838fc · 40838fc
1 parent 0b2c48c
commit 40838fc
Show file tree

Hide file tree

Showing 8 changed files with 384 additions and 20 deletions.
diff --git a/docs/modules/ROOT/examples/ws-security-policy/HttpsPolicyHelloService.java b/docs/modules/ROOT/examples/ws-security-policy/HttpsPolicyHelloService.java
@@ -0,0 +1,19 @@
+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);
+
+}
diff --git a/docs/modules/ROOT/examples/ws-security-policy/application.properties b/docs/modules/ROOT/examples/ws-security-policy/application.properties
diff --git a/docs/modules/ROOT/examples/ws-security-policy/https-policy.xml b/docs/modules/ROOT/examples/ws-security-policy/https-policy.xml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<wsp:Policy 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>
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -6,6 +6,7 @@
 ** xref:user-guide/package-for-jvm-and-native.adoc[Package for JVM and native]
 ** xref:user-guide/payload-logging.adoc[Logging]
 ** xref:user-guide/soap-payloads-with-jaxb.adoc[Complex SOAP payloads with JAXB]
+** xref:user-guide/ssl.adoc[SSL]
 ** xref:user-guide/advanced-soap-client-topics.adoc[Advanced SOAP client topics]
 ** xref:user-guide/advanced-soap-server-topics.adoc[Advanced SOAP server topics]
 ** xref:user-guide/generate-java-from-wsdl.adoc[Generate Java from WSDL]

diff --git a/docs/modules/ROOT/pages/user-guide/advanced-soap-client-topics.adoc b/docs/modules/ROOT/pages/user-guide/advanced-soap-client-topics.adoc
@@ -81,30 +81,11 @@ void onStart(@Observes StartupEvent ev) {
          }
      };
 
-     final Bus bus = BusFactory.getThreadDefaultBus();
+     final Bus bus = BusFactory.getDefaultBus();
      bus.setExtension(httpConduitConfigurer, HTTPConduitConfigurer.class);
 }
 ----
 
-To configure the `HttpConduit` for a single client in your application, use the example snippet below:
-
-[source,java]
-----
-    @Inject
-    @CXFClient
-    SomePortType portType;
-
-    @PostConstruct
-    void configurePortType() throws NoSuchAlgorithmException, UnrecoverableKeyException, KeyStoreException {
-        final var httpConduit = (HTTPConduit) ClientProxy.getClient(portType).getConduit();
-        final var tlsClientParameters = Optional.ofNullable(httpConduit.getTlsClientParameters()).orElseGet(TLSClientParameters::new);
-        tlsClientParameters.setCertAlias(config.clientCert().keyAlias());
-        tlsClientParameters.setKeyManagers(clientKeyManagers);
-        tlsClientParameters.setTrustManagers(clientTrustManagers);
-        httpConduit.setTlsClientParameters(tlsClientParameters);
-    }
-----
-
 [[pure-client]]
 == Pure client applications
 

diff --git a/docs/modules/ROOT/pages/user-guide/ssl.adoc b/docs/modules/ROOT/pages/user-guide/ssl.adoc
@@ -0,0 +1,87 @@
+= SSL
+
+This chapter documents various use cases related to SSL, TLS and HTTPS.
+
+NOTE: The sample code snippets used in this section come from the
+     https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/ws-security-policy[WS-SecurityPolicy integration test]
+     in the source tree of {quarkus-cxf-project-name}
+
+
+== Client SSL configuration
+
+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 doing that.
+You may want to check
+https://github.com/quarkiverse/quarkus-cxf/blob/main/integration-tests/ws-security-policy/pom.xml#L127-L440[some]
+https://github.com/quarkiverse/quarkus-cxf/blob/main/integration-tests/ws-security-policy/generate-certs.sh[examples]
+in {quarkus-cxf-project-name} source tree.
+
+Once you have prepared the trust store, you need to configure your client to use it.
+
+=== Set the client trust store in `application.properties`
+
+This is the easiest way to set the client trust store.
+The key role is played by the following properties:
+
+* `xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus.cxf.client.-clients-.trust-store[quarkus.cxf.client."clients".trust-store]`
+* `xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus.cxf.client.-clients-.trust-store-type[quarkus.cxf.client."clients".trust-store-type]`
+* `xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus.cxf.client.-clients-.trust-store-password[quarkus.cxf.client."clients".trust-store-password]`
+
+Here is an example:
+
+.application.properties
+[source,properties]
+----
+keystore.type = jks <1>
+include::example$ws-security-policy/application.properties[tag=client-trust-store]
+----
+
+<1> `pkcs12` trust store type is a common alternative to `jks`.
+<2> The referenced `client-truststore.jks` file has to be available in `src/main/resources` directory.
+
+== Server SSL configuration
+
+The server SSL configuration is driven by Quarkus HTTP layer a.k.a. Vert.x.
+https://quarkus.io/guides/http-reference#ssl[Quarkus HTTP guide] provides the information about the configuration options.
+
+Here is a basic example:
+
+.application.properties
+[source,properties]
+----
+include::example$ws-security-policy/application.properties[tag=server-key-store]
+----
+
+<1> The referenced `localhost.jks` file has to be available in `src/main/resources` directory.
+
+== Enforce SSL through WS-SecurityPolicy
+
+The requirement for the clients to connect through HTTPS can be defined in a policy.
+
+The functionality is provided by `xref:reference/extensions/quarkus-cxf-rt-ws-security.adoc[quarkus-cxf-rt-ws-security]` extension.
+
+Here is an example of a policy file:
+
+.https-policy.xml
+[source,properties]
+----
+include::example$ws-security-policy/https-policy.xml[]
+----
+
+The policy has to be referenced from a service endpoint interface (SEI):
+
+.HttpsPolicyHelloService.java
+[source,java]
+----
+include::example$ws-security-policy/HttpsPolicyHelloService.java[]
+----
+
+With this setup in place, any request delivered over HTTP will be rejected by the `PolicyVerificationInInterceptor`:
+
+[source,shell]
+----
+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
+ ...
+----
diff --git a/integration-tests/ws-security-policy/pom.xml b/integration-tests/ws-security-policy/pom.xml
@@ -77,6 +77,39 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <!-- Copy the sample code to docs module where Antora can see it -->
+                        <id>copy-resources-for-antora</id>
+                        <phase>compile</phase><!-- after source formatting -->
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>
+                                ${maven.multiModuleProjectDirectory}/docs/modules/ROOT/examples/ws-security-policy</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>src/main/resources</directory>
+                                    <includes>
+                                        <include>application.properties</include>
+                                        <include>https-policy.xml</include>
+                                    </includes>
+                                </resource>
+                                <resource>
+                                    <directory>src/main/java/io/quarkiverse/cxf/it/security/policy</directory>
+                                    <includes>
+                                        <include>HttpsPolicyHelloService.java</include>
+                                    </includes>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 

diff --git a/integration-tests/ws-security-policy/src/main/resources/application.properties b/integration-tests/ws-security-policy/src/main/resources/application.properties
@@ -3,10 +3,13 @@
 keystore.type = ${keystore.type}
 
 # Server side SSL
+# tag::server-key-store[]
+# <1>
 quarkus.http.ssl.certificate.key-store-file=localhost.${keystore.type}
 quarkus.http.ssl.certificate.key-store-password=password
 quarkus.http.ssl.certificate.key-store-key-alias=localhost
 quarkus.http.ssl.certificate.key-store-key-password=password
+# end::server-key-store[]
 
 # Disable HTTP
 #quarkus.http.insecure-requests = disabled
@@ -79,10 +82,14 @@ quarkus.cxf.endpoint."/helloSaml2".security.signature.properties."org.apache.ws.
 quarkus.cxf.endpoint."/helloSaml2".security.signature.properties."org.apache.ws.security.crypto.merlin.file" = bob.${keystore.type}
 
 # Clients
+# tag::client-trust-store[]
 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
+quarkus.cxf.client.hello.trust-store = ${keystore.type}
+# <2>
 quarkus.cxf.client.hello.trust-store = client-truststore.${keystore.type}
 quarkus.cxf.client.hello.trust-store-password = password
+# end::client-trust-store[]
 
 quarkus.cxf.client.helloAllowAll.client-endpoint-url = https://127.0.0.1:${quarkus.http.test-ssl-port}/services/hello
 quarkus.cxf.client.helloAllowAll.service-interface = io.quarkiverse.cxf.it.security.policy.HelloService