Author: asoldano Date: 2015-04-23 08:38:25 -0400 (Thu, 23 Apr 2015) New Revision: 19684 Added: stack/cxf/trunk/modules/dist/src/main/doc/chapter-8-Build_and_testsuite_framework.xml Modified: stack/cxf/trunk/modules/dist/src/main/doc/Book_Info.xml stack/cxf/trunk/modules/dist/src/main/doc/JBossWS-CXF.xml stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-3-JAX_WS_User_Guide.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml stack/cxf/trunk/modules/dist/src/main/doc/chapter-6-JBoss_Modules.xml Log: Updating release documentation Modified: stack/cxf/trunk/modules/dist/src/main/doc/Book_Info.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/Book_Info.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/Book_Info.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -4,7 +4,7 @@ <title>JBoss Web Services Documentation</title> <!--<subtitle></subtitle>--> <productname>JBossWS - CXF</productname> - <productnumber>4.3.0.Final</productnumber> + <productnumber>5.0.0.Final</productnumber> <!-- <edition>ToDo</edition> <pubsnumber>ToDo</pubsnumber> --> <abstract> Modified: stack/cxf/trunk/modules/dist/src/main/doc/JBossWS-CXF.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/JBossWS-CXF.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/JBossWS-CXF.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -10,6 +10,7 @@ <xi:include href="chapter-5-Advanced_User_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="chapter-6-JBoss_Modules.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="chapter-7-Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="chapter-8-Build_and_testsuite_framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </book> Modified: stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/Revision_History.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -116,6 +116,20 @@ </simplelist> </revdescription> </revision> + <revision> + <revnumber>5.0.0</revnumber> + <date>Fri Apr 23 2015</date> + <author> + <firstname>Alessio</firstname> + <surname>Soldano</surname> + <email&gt;alessio.soldano(a)jboss.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>JBossWS-CXF 5.0.0 documentation</member> + </simplelist> + </revdescription> + </revision> </revhistory> </simpara> </appendix> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-2-Quick_Start.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -4,7 +4,7 @@ <title>Quick Start</title> <para> - JBossWS uses the JBoss Application Server as its target container. The following examples focus on web service deployments that leverage EJB3 service implementations and the JAX-WS programming models. For further information on POJO service implementations and advanced topics you need consult the + JBossWS uses WildFly as its target container. The following examples focus on web service deployments that leverage EJB3 service implementations and the JAX-WS programming models. For further information on POJO service implementations and advanced topics you need consult the <link linkend="sid-3866716">user guide</link> . </para> @@ -197,7 +197,7 @@ <section id="sid-3735860_QuickStart-Consumingwebservices"> <title>Consuming web services</title> - <para>When creating web service clients you would usually start from the WSDL. JBossWS ships with a set of tools to generate the required JAX-WS artefacts to build client implementations. In the following section we will look at the most basic usage patterns. For a more detailed introduction to web service client please consult the user guide.</para> + <para>When creating web service clients you would usually start from the WSDL. JBossWS ships with a set of tools to generate the required JAX-WS artifacts to build client implementations. In the following section we will look at the most basic usage patterns. For a more detailed introduction to web service client please consult the user guide.</para> <section id="sid-3735860_QuickStart-Creatingtheclientartifacts"> <title>Creating the client artifacts</title> @@ -368,25 +368,16 @@ <code> <ulink url="https://repository.jboss.org/nexus/content/groups/public-jboss/... </code> - and - <ulink url="https://repository.jboss.org/nexus/content/groups/public-jboss/... - <code>org.jboss.ws.native:jbossws-native-client</code> - </ulink> - artifacts can be used for getting the whole jbossws client dependency trees for the JBossWS-CXF and JBossWS-Native stacks. Users should simply add a dependency on - <emphasis role="strong">one</emphasis> - of them (depending on the JBossWS stack in use) to their Maven project. + artifact can be used for getting the whole JBossWS client dependency. Users should simply add a dependency to it in their Maven project. </para> <para> - If you're running the client out of container, It's also recommended to properly setup JAXWS implementation endorsing, to use the JBossWS implementation of JAXWS API instead of relying on the implementation coming with the JDK; this is usually done by copying the + If you're running the client out of container, It's also recommended to properly setup JAXWS implementation endorsing, to make sure you use the JBossWS + <emphasis role="strong">implementation</emphasis> + of JAXWS API instead of relying on the implementation coming with the JDK; this is usually done by copying the <code> <ulink url="https://repository.jboss.org/nexus/content/groups/public-jboss/... </code> - (JBossWS-CXF stack) - <emphasis role="strong">or</emphasis> - <code> - <ulink url="https://repository.jboss.org/nexus/content/groups/public-jboss/... - </code> - (JBossWS-Native stack) jar into a local directory (e.g. + (JBossWS-CXF stack) jar into a local directory (e.g. <emphasis role="italics">project.build.directory/endorsed</emphasis> ) and then using that for compiling and running sources, for setting the <emphasis role="italics">java.endorsed.dirs</emphasis> @@ -458,7 +449,11 @@ </programlisting> </informalexample> <important> - <para>Endorsing of JAXWS API jar is used to force a API level different from the one included in the JDK. E.g. JAXWS 2.2 on JDK 1.6, or JAXWS 2.1 on JDK 1.7, etc.</para> + <para> + Endorsing of JAX-WS + <emphasis role="strong">api</emphasis> + jar is used to force a API level different from the one included in the JDK. E.g. JAXWS 2.2 on JDK 1.6, or JAXWS 2.1 on JDK 1.7, etc. So, depending on your environment, it might not be strictly required. + </para> </important> </section> <section id="sid-3735860_QuickStart-JBossModulesenvironment"> @@ -467,10 +462,10 @@ <para> An interesting approach for running a WS client is to leverage JBoss Modules, basically getting a classloading environment equivalent to the server container WS endpoints are run in. This is achieved by using the <emphasis role="italics">jboss-modules.jar</emphasis> - coming with AS 7 as follows: + coming with WildFly as follows: </para> <informalexample> - <programlisting>java -jar $JBOSS_HOME/jboss-modules.jar -mp $JBOSS_HOME/modules -jar client.jar</programlisting> + <programlisting>java -jar $WILDFLY_HOME/jboss-modules.jar -mp $WILDFLY_HOME/modules -jar client.jar</programlisting> </informalexample> <para> The @@ -501,20 +496,54 @@ <code>java</code> command or using <code>Ant</code> - ). The JBossWS testsuite can be used to derive the whole set of files to be used; the testsuite can be run either using Maven (from the source distribution) or Ant (from the binary distribution). A verbose execution reveals the list of jar. As for the Maven project approach mentioned above, properly setting + ). As for the Maven project approach mentioned above, properly setting <emphasis role="italics">java.endorsed.dirs</emphasis> system property is also required. </para> </section> </section> - <section id="sid-3735860_QuickStart-Appendix"> + </section> + <section id="sid-3735860_QuickStart-Mavenarchetypequickstart"> + + <title>Maven archetype quick start</title> + <para> + A convenient approach to start a new project aiming at providing and/or consuming a JAX-WS endpoint is to use the JBossWS + <emphasis role="italics">jaxws-codefirst</emphasis> + Maven Archetype. A starting project (including working build and sample helloworld client and endpoint) is created in few seconds. It's simply a matter of issuing a command and answering to simple questions on the desired artifact and group ids for the project being generated: + </para> + <informalexample> + <programlisting>&gt; mvn archetype:generate -Dfilter=org.jboss.ws.plugins.archetypes:</programlisting> + </informalexample> + <para>The generated project includes:</para> + <itemizedlist> + <listitem> + <para>a sample HelloWorld code-first POJO endpoint</para> + </listitem> + <listitem> + <para>an integration test that gets the WSDL contract for the above service, builds up a client and invokes the endpoint</para> + </listitem> + <listitem> + <para>a pom.xml for creating a war archive; the project has proper WS component dependencies and uses both wsprovide and wsconsume maven plugins for generating the contract for the code-first endpoint and then generating the client stubs for such contract</para> + </listitem> + <listitem> + <para>a plugin for deploying the archive on WildFly.</para> + </listitem> + </itemizedlist> + <para>The project is built and tested by simply running:</para> + <informalexample> + <programlisting>&gt; mvn wildfly:deploy +&gt; mvn integration-test</programlisting> + </informalexample> + <para>The build processes the various plugins and calls into the JBossWS tools to generate all the required classes for building the deployment archive and client. The user can test the sample, have a look at the project structure and then either trash the sample endpoint and testcase and replace them with his own components, or modify them step-by-step to achieve what he needs.</para> + </section> + <section id="sid-3735860_QuickStart-Appendix"> + + <title>Appendix</title> + <section id="sid-3735860_QuickStart-Samplewsdlcontract"> - <title>Appendix</title> - <section id="sid-3735860_QuickStart-Samplewsdlcontract"> - - <title>Sample wsdl contract</title> - <informalexample> - <programlisting> + <title>Sample wsdl contract</title> + <informalexample> + <programlisting> &lt;definitions name='ProfileMgmtService' targetNamespace='http://org.jboss.ws/samples/retail/profile' @@ -603,8 +632,7 @@ &lt;/service&gt; &lt;/definitions&gt; </programlisting> - </informalexample> - </section> + </informalexample> </section> </section> </chapter> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-3-JAX_WS_User_Guide.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-3-JAX_WS_User_Guide.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-3-JAX_WS_User_Guide.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -201,7 +201,7 @@ <programlisting>// Generated Service Class @WebServiceClient(name="StockQuoteService", targetNamespace="http://example.com/stocks";, wsdlLocation="http://example.com/stocks.wsdl") -publicclass StockQuoteService extends javax.xml.ws.Service +public class StockQuoteService extends javax.xml.ws.Service {    public StockQuoteService()    { @@ -311,7 +311,7 @@ <programlisting>@WebServiceClient(name = "TestEndpointService", targetNamespace = "http://org.jboss.ws/wsref",    wsdlLocation = "http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl") -publicclass TestEndpointService extends Service +public class TestEndpointService extends Service {     ... @@ -347,7 +347,7 @@ <listitem> <para>To define a reference whose type is a SEI. In this case, the type element MAY be present with its default value if the type of the reference can be inferred from the annotated field/method declaration, but the value element MUST always be present and refer to a generated service class type (a subtype of javax.xml.ws.Service). The wsdlLocation element, if present, overrides theWSDL location information specified in the WebService annotation of the referenced generated service class.</para> <informalexample> - <programlisting>publicclass EJB3Client implements EJB3Remote + <programlisting>public class EJB3Client implements EJB3Remote {    @WebServiceRef    public TestEndpointService service4; @@ -494,9 +494,9 @@ <informalexample> <programlisting>@WebService (name="PingEndpoint") @SOAPBinding(style = SOAPBinding.Style.RPC) -publicclass PingEndpointImpl +public class PingEndpointImpl { -   privatestatic String feedback; +   private static String feedback;       @WebMethod    @Oneway @@ -574,7 +574,7 @@ <informalexample> <programlisting>@WebService @HandlerChain(file = "jaxws-server-source-handlers.xml") -publicclass SOAPEndpointSourceImpl +public class SOAPEndpointSourceImpl {    ... }</programlisting> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-4-JAX_WS_Tools.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -507,6 +507,7 @@ -l, --load-consumer Load the consumer and exit (debug utility) -e, --extension Enable SOAP 1.2 binding extension -a, --additionalHeaders Enables processing of implicit SOAP headers + -d, --encoding=&lt;charset&gt; The charset encoding to use for generated sources -n, --nocompile             Do not compile generated sources</programlisting> </informalexample> <para> @@ -545,7 +546,9 @@ <title>Maven Plugin</title> <para> The wsconsume tools is included in the - <emphasis role="strong">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis> + <emphasis role="strong">org.jboss.ws.plugins:jaxws-tools-</emphasis> + <emphasis role="strong">maven-</emphasis> + <emphasis role="strong">plugin</emphasis> plugin. The plugin has two goals for running the tool, <emphasis role="italics">wsconsume</emphasis> and @@ -708,6 +711,17 @@ </row> <row> <entry> + <para>encoding</para> + </entry> + <entry> + <para>The charset encoding to use for generated sources.</para> + </entry> + <entry> + <para>${project.build.sourceEncoding}</para> + </entry> + </row> + <row> + <entry> <para>argLine</para> </entry> <entry> @@ -763,7 +777,9 @@ You can use <emphasis role="italics">wsconsume</emphasis> in your own project build simply referencing the - <emphasis role="italics">maven-jaxws-tools-plugin</emphasis> + <emphasis role="italics">jaxws-tools-</emphasis> + <emphasis role="italics">maven-</emphasis> + <emphasis role="italics">plugin</emphasis> in the configured plugins in your pom.xml file. </para> <para>The following example makes the plugin consume the test.wsdl file and generate SEI and wrappers' java sources. The generated sources are then compiled together with the other project classes.</para> @@ -773,8 +789,8 @@ &lt;plugins&gt; &lt;plugin&gt; &lt;groupId&gt;org.jboss.ws.plugins&lt;/groupId&gt; - &lt;artifactId&gt;maven-jaxws-tools-plugin&lt;/artifactId&gt; - &lt;version&gt;1.1.0.GA&lt;/version&gt; + &lt;artifactId&gt;jaxws-tools-maven-plugin&lt;/artifactId&gt; + &lt;version&gt;1.2.0.Beta1&lt;/version&gt; &lt;configuration&gt; &lt;wsdls&gt; &lt;wsdl&gt;${basedir}/test.wsdl&lt;/wsdl&gt; @@ -799,8 +815,8 @@ &lt;plugins&gt; &lt;plugin&gt; &lt;groupId&gt;org.jboss.ws.plugins&lt;/groupId&gt; - &lt;artifactId&gt;maven-jaxws-tools-plugin&lt;/artifactId&gt; - &lt;version&gt;1.1.0.GA&lt;/version&gt; + &lt;artifactId&gt;jaxws-tools-maven-plugin&lt;/artifactId&gt; + &lt;version&gt;1.2.0.Beta1&lt;/version&gt; &lt;configuration&gt; &lt;wsdls&gt; &lt;wsdl&gt;${basedir}/test.wsdl&lt;/wsdl&gt; @@ -833,8 +849,8 @@ &lt;plugins&gt; &lt;plugin&gt; &lt;groupId&gt;org.jboss.ws.plugins&lt;/groupId&gt; - &lt;artifactId&gt;maven-jaxws-tools-plugin&lt;/artifactId&gt; - &lt;version&gt;1.1.0.GA&lt;/version&gt; + &lt;artifactId&gt;jaxws-tools-maven-plugin&lt;/artifactId&gt; + &lt;version&gt;1.2.0.Beta1&lt;/version&gt; &lt;configuration&gt; &lt;wsdls&gt; &lt;wsdl&gt;${basedir}/test.wsdl&lt;/wsdl&gt; @@ -866,7 +882,7 @@ &lt;dependency&gt; &lt;groupId&gt;org.jboss.ws.cxf&lt;/groupId&gt; &lt;artifactId&gt;jbossws-cxf-client&lt;/artifactId&gt; - &lt;version&gt;4.0.0.GA&lt;/version&gt; + &lt;version&gt;5.0.0.Beta2&lt;/version&gt; &lt;/dependency&gt; &lt;/dependencies&gt;</programlisting> </informalexample> @@ -879,6 +895,15 @@ stack dependency to avoid that. </para> </tip> + <important> + <para> + Up to version 1.1.2.Final, the + <emphasis role="italics">artifactId</emphasis> + of the plugin was + <emphasis role="strong">maven-jaxws-tools-plugin</emphasis> + . + </para> + </important> </section> </section> <section id="sid-3866762_wsconsume-AntTask"> @@ -975,6 +1000,17 @@ </row> <row> <entry> + <para>encoding</para> + </entry> + <entry> + <para>The charset encoding to use for generated sources</para> + </entry> + <entry> + <para>n/a</para> + </entry> + </row> + <row> + <entry> <para>destdir</para> </entry> <entry> @@ -1175,7 +1211,9 @@ The <emphasis role="italics">wsprovide</emphasis> tools is included in the - <emphasis role="strong">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis> + <emphasis role="strong">org.jboss.ws.plugins:jaxws-tools-</emphasis> + <emphasis role="strong">maven-</emphasis> + <emphasis role="strong">plugin</emphasis> plugin. The plugin has two goals for running the tool, <emphasis role="italics">wsprovide</emphasis> and @@ -1331,7 +1369,9 @@ You can use <emphasis role="italics">wsprovide</emphasis> in your own project build simply referencing the - <emphasis role="italics">maven-jaxws-tools-plugin</emphasis> + <emphasis role="italics">jaxws-tools-</emphasis> + <emphasis role="italics">maven-</emphasis> + <emphasis role="italics">plugin</emphasis> in the configured plugins in your <emphasis role="italics">pom.xml</emphasis> file. @@ -1342,8 +1382,8 @@ &lt;plugins&gt; &lt;plugin&gt; &lt;groupId&gt;org.jboss.ws.plugins&lt;/groupId&gt; - &lt;artifactId&gt;maven-jaxws-tools-plugin&lt;/artifactId&gt; - &lt;version&gt;1.1.0.GA&lt;/version&gt; + &lt;artifactId&gt;jaxws-tools-maven-plugin&lt;/artifactId&gt; + &lt;version&gt;1.2.0.Beta1&lt;/version&gt; &lt;configuration&gt; &lt;verbose&gt;true&lt;/verbose&gt; &lt;endpointClass&gt;org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint&lt;/endpointClass&gt; @@ -1366,8 +1406,8 @@ &lt;plugins&gt; &lt;plugin&gt; &lt;groupId&gt;org.jboss.ws.plugins&lt;/groupId&gt; - &lt;artifactId&gt;maven-jaxws-tools-plugin&lt;/artifactId&gt; - &lt;version&gt;1.1.0.GA&lt;/version&gt; + &lt;artifactId&gt;jaxws-tools-maven-plugin&lt;/artifactId&gt; + &lt;version&gt;1.2.0.Beta1&lt;/version&gt; &lt;configuration&gt; &lt;verbose&gt;true&lt;/verbose&gt; &lt;endpointClass&gt;org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint2&lt;/endpointClass&gt; @@ -1398,7 +1438,7 @@ &lt;dependency&gt; &lt;groupId&gt;org.jboss.ws.cxf&lt;/groupId&gt; &lt;artifactId&gt;jbossws-cxf-client&lt;/artifactId&gt; - &lt;version&gt;4.0.0.GA&lt;/version&gt; + &lt;version&gt;5.0.0.Beta2&lt;/version&gt; &lt;/dependency&gt; &lt;/dependencies&gt;</programlisting> </informalexample> @@ -1411,6 +1451,15 @@ stack dependency to avoid that. </para> </tip> + <important> + <para> + Up to version 1.1.2.Final, the + <emphasis role="italics">artifactId</emphasis> + of the plugin was + <emphasis role="strong">maven-jaxws-tools-plugin</emphasis> + . + </para> + </important> </section> </section> <section id="sid-3866758_wsprovide-AntTask"> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-5-Advanced_User_Guide.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -38,7 +38,7 @@ instance being created on the JVM. </para> <important> - <para>On JBoss AS 7, the system property is easily set by adding what follows to the standalone / domain server configuration just after the extensions section:</para> + <para>On WildFly, the system property is easily set by adding what follows to the standalone / domain server configuration just after the extensions section:</para> <informalexample> <programlisting>&lt;system-properties&gt; &lt;property name="org.apache.cxf.logging.enabled" value="true"/&gt; @@ -65,7 +65,6 @@ <code&gt;(a)org.apache.cxf.annotations.Logging&lt;/code&gt; ). </para> - <para>Finally, the interceptors and feature can also be configured using Spring descriptors when Spring is available for the JBossWS-CXF integration on the application server.</para> <para> Please refer to the <ulink url="http://cxf.apache.org/docs/debugging-and-logging.html#Debugging... CXF documentation</ulink> @@ -94,7 +93,7 @@ <para> The configuration options are part of the <ulink url="https://docs.jboss.org/author/display/AS71/Web+services+configu... subsystem section</ulink> - of the JBoss Application Server 7 domain model. + of the WildFly domain model. </para> <informalexample> <programlisting> @@ -219,7 +218,7 @@ <code>&lt;config-file&gt;</code> can be used to associate any endpoint provided in the deployment with a given <link linkend="sid-41713670">endpoint configuration</link> - . Endpoint configuration are either specified in the referenced config file or in the JBoss AS 7 domain model (webservices subsystem). For further details on the endpoint configurations and their management in the domain model, please see the related + . Endpoint configuration are either specified in the referenced config file or in the WildFly domain model (webservices subsystem). For further details on the endpoint configurations and their management in the domain model, please see the related <ulink url="https://docs.jboss.org/author/display/AS71/Web+services+configu... . </para> @@ -359,50 +358,259 @@ on the wiki and at the examples in the sources. </para> </section> + <section id="sid-3866738_AdvancedUserGuide-WSDLsystempropertiesexpansion"> + + <title>WSDL system properties expansion</title> + <para> + See + <xref linkend="sid-83919125"/> + . + </para> + </section> <section id="sid-41713670"> <title>Predefined client and endpoint configurations</title> <section id="sid-41713670_Predefinedclientandendpointconfigurations-Overview"> <title>Overview</title> - <para>JBossWS enables extra setup configuration data to be predefined and associated with an endpoint. Endpoint configurations can include JAX-WS handlers and key/value properties declarations that control JBossWS and Apache CXF internals. Predefined endpoint configurations can be used for JAX-WS client and JAX-WS endpoint setup.</para> + <para>JBossWS permits extra setup configuration data to be predefined and associated with an endpoint or a client. Configurations can include JAX-WS handlers and key/value property declarations that control JBossWS and Apache CXF internals. Predefined configurations can be used for JAX-WS client and JAX-WS endpoint setup.</para> <para> - Endpoint configurations can be defined in the webservice subsystem and in a deployment descriptor file within the application. There can be many endpoint configuration definitions in the webservice subsystem and in an application. Each endpoint configuration must have a name that is unique within the server. Configurations defined in an application are local to the application. Endpoint implementations declare the use of a specific configuration through the use of the + Configurations can be defined in the webservice subsystem and in an application's deployment descriptor file. There can be many configuration definitions in the webservice subsystem and in an application. Each configuration must have a name that is unique within the server. Configurations defined in an application are local to the application. Endpoint implementations declare the use of a specific configuration through the use of the <code>org.jboss.ws.api.annotation.EndpointConfig</code> - annotation. An endpoint configuration defined in the webservices subsystem is available to all deployed applications on the server container and can be referenced by name in the annotation. An endpoint configuration defined in an application must be referenced by deployment descriptor file name and the configuration name in the annotation. + annotation. An endpoint configuration defined in the webservices subsystem is available to all deployed applications on the server container and can be referenced by name in the annotation. An endpoint configuration defined in an application must be referenced by both deployment descriptor file name and configuration name by the annotation. </para> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Handlers"> - - <title>Handlers</title> - <para>Each endpoint configuration may be associated with zero or more PRE and POST handler chains. Each handler chain may include JAXWS handlers. For outbound messages the PRE handler chains are executed before any handler that is attached to the endpoint using the standard means, such as with annotation @HandlerChain, and POST handler chains are executed after those objects have executed. For inbound messages the POST handler chains are executed before any handler that is attached to the endpoint using the standard means and the PRE handler chains are executed after those objects have executed.</para> - <informalexample> - <programlisting>* Server inbound messages + <para> + <emphasis role="strong">Handlers</emphasis> + </para> + <para>Each endpoint configuration may be associated with zero or more PRE and POST handler chains. Each handler chain may include JAXWS handlers. For outbound messages the PRE handler chains are executed before any handler that is attached to the endpoint using the standard means, such as with annotation @HandlerChain, and POST handler chains are executed after those objects have executed. For inbound messages the POST handler chains are executed before any handler that is attached to the endpoint using the standard means and the PRE handler chains are executed after those objects have executed.</para> + <informalexample> + <programlisting>* Server inbound messages Client --&gt; ... --&gt; POST HANDLER --&gt; ENDPOINT HANDLERS --&gt; PRE HANDLERS --&gt; Endpoint * Server outbound messages Endpoint --&gt; PRE HANDLER --&gt; ENDPOINT HANDLERS --&gt; POST HANDLERS --&gt; ... --&gt; Client</programlisting> - </informalexample> - <para>The same applies for client configurations.</para> - </section> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Properties"> - - <title>Properties</title> - <para>Key/value properties are used for controlling both some Apache CXF internals and some JBossWS options. Specific supported values are mentioned where relevant in the rest of the documentation.</para> - </section> + </informalexample> + <para>The same applies for client configurations.</para> + <para> + <emphasis role="strong">Properties</emphasis> + </para> + <para>Key/value properties are used for controlling both some Apache CXF internals and some JBossWS options. Specific supported values are mentioned where relevant in the rest of the documentation.</para> </section> <section id="sid-41713670_Predefinedclientandendpointconfigurations-Assigningconfigurations"> <title>Assigning configurations</title> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Endpointconfigurationassignment"> + <para>Endpoints and clients are assigned configuration through different means. Users can explicitly require a given configuration or rely on container defaults. The assignment process can be split up as follows:</para> + <itemizedlist> + <listitem> + <para>Explicit assignment through annotations (for endpoints) or API programmatic usage (for clients)</para> + </listitem> + <listitem> + <para>Automatic assignment of configurations from default descriptors</para> + </listitem> + <listitem> + <para>Automatic assignment of configurations from container</para> + </listitem> + </itemizedlist> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-Explicitconfigurationassignment"> - <title>Endpoint configuration assignment</title> - <para> - Annotation - <code>org.jboss.ws.api.annotation.EndpointConfig</code> - is used to assign an endpoint configuration to a JAX-WS endpoint implementation. When assigning a configuration that is defined in the webservices subsystem only the configuration name is specified. When assigning a configuration that is defined in the application, the relative path to the deployment descriptor and the configuration name must be specified. - </para> - <informalexample> - <programlisting>@EndpointConfig(configFile = "WEB-INF/jaxws-endpoint-config.xml", configName = "Custom WS-Security Endpoint") + <title>Explicit configuration assignment</title> + <para>The explicit configuration assignment is meant for developer that know in advance their endpoint or client has to be setup according to a specified configuration. The configuration is either coming from a descriptor that is included in the application deployment, or is included in the application server webservices subsystem management model.</para> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-ConfigurationDeploymentDescriptor"> + + <title>Configuration Deployment Descriptor</title> + <para> + Java EE archives that can contain JAX-WS client and endpoint implementations can also contain predefined client and endpoint configuration declarations. All endpoint/client configuration definitions for a given archive must be provided in a single deployment descriptor file, which must be an implementation of schema + <ulink url="http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1... + . Many endpoint/client configurations can be defined in the deployment descriptor file. Each configuration must have a name that is unique within the server on which the application is deployed. The configuration name can't be referred to by endpoint/client implementations outside the application. Here is an example of a descriptor, containing two endpoint configurations: + </para> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" + xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"&gt; + &lt;endpoint-config&gt; + &lt;config-name&gt;org.jboss.test.ws.jaxws.jbws3282.Endpoint4Impl&lt;/config-name&gt; + &lt;pre-handler-chains&gt; + &lt;javaee:handler-chain&gt; + &lt;javaee:handler&gt; + &lt;javaee:handler-name&gt;Log Handler&lt;/javaee:handler-name&gt; + &lt;javaee:handler-class&gt;org.jboss.test.ws.jaxws.jbws3282.LogHandler&lt;/javaee:handler-class&gt; + &lt;/javaee:handler&gt; + &lt;/javaee:handler-chain&gt; + &lt;/pre-handler-chains&gt; + &lt;post-handler-chains&gt; + &lt;javaee:handler-chain&gt; + &lt;javaee:handler&gt; + &lt;javaee:handler-name&gt;Routing Handler&lt;/javaee:handler-name&gt; + &lt;javaee:handler-class&gt;org.jboss.test.ws.jaxws.jbws3282.RoutingHandler&lt;/javaee:handler-class&gt; + &lt;/javaee:handler&gt; + &lt;/javaee:handler-chain&gt; + &lt;/post-handler-chains&gt; + &lt;/endpoint-config&gt; + &lt;endpoint-config&gt; + &lt;config-name&gt;EP6-config&lt;/config-name&gt; + &lt;post-handler-chains&gt; + &lt;javaee:handler-chain&gt; + &lt;javaee:handler&gt; + &lt;javaee:handler-name&gt;Authorization Handler&lt;/javaee:handler-name&gt; + &lt;javaee:handler-class&gt;org.jboss.test.ws.jaxws.jbws3282.AuthorizationHandler&lt;/javaee:handler-class&gt; + &lt;/javaee:handler&gt; + &lt;/javaee:handler-chain&gt; + &lt;/post-handler-chains&gt; + &lt;/endpoint-config&gt; +&lt;/jaxws-config&gt; +</programlisting> + </informalexample> + <para>Similarly, client configurations can be specified in descriptors (still implementing the schema mentioned above):</para> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" + xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"&gt; + &lt;client-config&gt; + &lt;config-name&gt;Custom Client Config&lt;/config-name&gt; + &lt;pre-handler-chains&gt; + &lt;javaee:handler-chain&gt; + &lt;javaee:handler&gt; + &lt;javaee:handler-name&gt;Routing Handler&lt;/javaee:handler-name&gt; + &lt;javaee:handler-class&gt;org.jboss.test.ws.jaxws.clientConfig.RoutingHandler&lt;/javaee:handler-class&gt; + &lt;/javaee:handler&gt; + &lt;javaee:handler&gt; + &lt;javaee:handler-name&gt;Custom Handler&lt;/javaee:handler-name&gt; + &lt;javaee:handler-class&gt;org.jboss.test.ws.jaxws.clientConfig.CustomHandler&lt;/javaee:handler-class&gt; + &lt;/javaee:handler&gt; + &lt;/javaee:handler-chain&gt; + &lt;/pre-handler-chains&gt; + &lt;/client-config&gt; + &lt;client-config&gt; + &lt;config-name&gt;Another Client Config&lt;/config-name&gt; + &lt;post-handler-chains&gt; + &lt;javaee:handler-chain&gt; + &lt;javaee:handler&gt; + &lt;javaee:handler-name&gt;Routing Handler&lt;/javaee:handler-name&gt; + &lt;javaee:handler-class&gt;org.jboss.test.ws.jaxws.clientConfig.RoutingHandler&lt;/javaee:handler-class&gt; + &lt;/javaee:handler&gt; + &lt;/javaee:handler-chain&gt; + &lt;/post-handler-chains&gt; + &lt;/client-config&gt; +&lt;/jaxws-config&gt; +</programlisting> + </informalexample> + </section> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-Applicationserverconfigurations"> + + <title>Application server configurations</title> + <para> + WildFly allows declaring JBossWS client and server predefined configurations in the + <emphasis role="italics">webservices</emphasis> + subsystem section of the server model. As a consequence it is possible to declare server-wide handlers to be added to the chain of each endpoint or client assigned to a given configuration. + </para> + <para> + Please refer to the + <ulink url="https://docs.jboss.org/author/display/WFLY9/Web+services+config... documentation</ulink> + for details on managing the + <emphasis role="italics">webservices</emphasis> + subsystem such as adding, removing and modifying handlers and properties. + </para> + <para> + The allowed contents in the + <emphasis role="italics">webservices</emphasis> + subsystem are defined by the + <ulink url="https://github.com/jbossas/jboss-as/blob/7.2.0.Final/build/src/... + included in the application server. + </para> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-Standardconfigurations"> + + <title>Standard configurations</title> + <para> + Clients running in-container as well as endpoints are assigned standard configurations by default. The defaults are used unless different configurations are set as described on this page. This enables administrators to tune the default handler chains for client and endpoint configurations. The names of the default client and endpoint configurations, used in the webservices subsystem are + <code>Standard-Client-Config</code> + and + <code>Standard-Endpoint-Config</code> + respectively. + </para> + </section> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-Handlersclassloading"> + + <title>Handlers classloading</title> + <para> + When setting a server-wide handler, please note the handler class needs to be available through each ws deployment classloader. As a consequence proper module dependencies might need to be specified in the deployments that are going to leverage a given predefined configuration. A shortcut is to add a dependency to the module containing the handler class in one of the modules which are already automatically set as dependencies to any deployment, for instance + <code>org.jboss.ws.spi</code> + . + </para> + </section> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-Examples"> + + <title>Examples</title> + <example> + <title>JBoss AS 7.2 default configurations</title> + <programlisting> +&lt;subsystem xmlns="urn:jboss:domain:webservices:2.0"&gt; + &lt;!-- ... --&gt; + &lt;endpoint-config name="Standard-Endpoint-Config"/&gt; + &lt;endpoint-config name="Recording-Endpoint-Config"&gt; + &lt;pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM"&gt; + &lt;handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/&gt; + &lt;/pre-handler-chain&gt; + &lt;/endpoint-config&gt; + &lt;client-config name="Standard-Client-Config"/&gt; +&lt;/subsystem&gt;</programlisting> + </example> + <example> + <title>A configuration file for a deployment specific ws-security endpoint setup</title> + <programlisting> +&lt;jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"&gt; + &lt;endpoint-config&gt; + &lt;config-name&gt;Custom WS-Security Endpoint&lt;/config-name&gt; + &lt;property&gt; + &lt;property-name&gt;ws-security.signature.properties&lt;/property-name&gt; + &lt;property-value&gt;bob.properties&lt;/property-value&gt; + &lt;/property&gt; + &lt;property&gt; + &lt;property-name&gt;ws-security.encryption.properties&lt;/property-name&gt; + &lt;property-value&gt;bob.properties&lt;/property-value&gt; + &lt;/property&gt; + &lt;property&gt; + &lt;property-name&gt;ws-security.signature.username&lt;/property-name&gt; + &lt;property-value&gt;bob&lt;/property-value&gt; + &lt;/property&gt; + &lt;property&gt; + &lt;property-name&gt;ws-security.encryption.username&lt;/property-name&gt; + &lt;property-value&gt;alice&lt;/property-value&gt; + &lt;/property&gt; + &lt;property&gt; + &lt;property-name&gt;ws-security.callback-handler&lt;/property-name&gt; + &lt;property-value&gt;org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback&lt;/property-value&gt; + &lt;/property&gt; + &lt;/endpoint-config&gt; +&lt;/jaxws-config&gt;</programlisting> + </example> + <example> + <title>JBoss AS 7.2 default configurations modified to default to SOAP messages schema-validation on</title> + <programlisting>&lt;subsystem xmlns="urn:jboss:domain:webservices:2.0"&gt; + &lt;!-- ... --&gt; + &lt;endpoint-config name="Standard-Endpoint-Config"&gt; + &lt;property name="schema-validation-enabled" value="true"/&gt; + &lt;/endpoint-config&gt; + &lt;!-- ... --&gt; + &lt;client-config name="Standard-Client-Config"&gt; + &lt;property name="schema-validation-enabled" value="true"/&gt; + &lt;/client-config&gt; +&lt;/subsystem&gt;</programlisting> + </example> + </section> + </section> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-EndpointConfigannotation"> + + <title>EndpointConfig annotation</title> + <para> + Once a configuration is available to a given application, the + <code>org.jboss.ws.api.annotation.EndpointConfig</code> + annotation is used to assign an endpoint configuration to a JAX-WS endpoint implementation. When assigning a configuration that is defined in the webservices subsystem only the configuration name is specified. When assigning a configuration that is defined in the application, the relative path to the deployment descriptor and the configuration name must be specified. + </para> + <informalexample> + <programlisting>@EndpointConfig(configFile = "WEB-INF/my-endpoint-config.xml", configName = "Custom WS-Security Endpoint") public class ServiceImpl implements ServiceIface { public String sayHello() @@ -410,21 +618,8 @@ return "Secure Hello World!"; } }</programlisting> - </informalexample> - </section> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-EndpointConfigurationDeploymentDescriptor"> - - <title>Endpoint Configuration Deployment Descriptor</title> - <para> - Java EE archives that can contain JAX-WS endpoint implementations can also contain predefined endpoint configurations. All endpoint configuration definitions for a given archive must be provided in a single deployment descriptor file. The file must reside in directory WEB-INF for a web application and directory META-INF for a client and EJB application. The file name must end with extension .xml and be an implementation of schema - <ulink url="http://anonsvn.jboss.org/repos/jbossws/spi/tags/jbossws-spi-2.1... - . Common practice is to use the file name jaxws-endpoint-config.xml but this is not required. - </para> - <para>Many endpoint configurations can be defined within the deployment descriptor file. Each configuration must have a name that is unique within the server on which the application is deployed. The configuration name is not referencable by endpoint implementations outside the application.</para> - </section> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Clientconfigurationassignment"> - - <title>Client configuration assignment</title> + </informalexample> + </section> <section id="sid-41713670_Predefinedclientandendpointconfigurations-JAXWSFeature"> <title>JAXWS Feature</title> @@ -442,12 +637,12 @@ ... Service service = Service.create(wsdlURL, serviceName); -Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/jaxws-client-config.xml", "Custom Client Config")); +Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config")); port.echo("Kermit"); ... or .... -port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/jaxws-client-config.xml", "Custom Client Config"), true); //setup properties too from the configuration +port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/my-client-config.xml", "Custom Client Config"), true); //setup properties too from the configuration port.echo("Kermit"); ... or ... @@ -463,9 +658,9 @@ artifact. </para> </section> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Explicitsetup"> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-ExplicitsetupthroughAPI"> - <title>Explicit setup</title> + <title>Explicit setup through API</title> <para>Alternatively, JBossWS API comes with facility classes that can be used for assigning configurations when building a client. JAXWS handlers read from client configurations as follows:</para> <informalexample> <programlisting>import org.jboss.ws.api.configuration.ClientConfigUtil; @@ -476,18 +671,18 @@ Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class); BindingProvider bp = (BindingProvider)port; -ClientConfigUtil.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 1"); +ClientConfigUtil.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config 1"); port.echo("Kermit"); ... ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); -configurer.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 2"); +configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config 2"); port.echo("Kermit"); ... -configurer.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 3"); +configurer.setConfigHandlers(bp, "META-INF/my-client-config.xml", "Custom Client Config 3"); port.echo("Kermit"); @@ -507,18 +702,18 @@ Service service = Service.create(wsdlURL, serviceName); Endpoint port = service.getPort(Endpoint.class); -ClientConfigUtil.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 1"); +ClientConfigUtil.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config 1"); port.echo("Kermit"); ... ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); -configurer.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 2"); +configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config 2"); port.echo("Kermit"); ... -configurer.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 3"); +configurer.setConfigProperties(port, "META-INF/my-client-config.xml", "Custom Client Config 3"); port.echo("Kermit"); @@ -539,111 +734,69 @@ </para> </section> </section> - </section> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Applicationserverconfigurations"> - - <title>Application server configurations</title> - <para> - JBoss Application Server 7.x allows declaring JBossWS client and server predefined configurations in the - <emphasis role="italics">webservices</emphasis> - subsystem section of the server model. As a consequence it is possible to declare server-wide handlers to be added to the chain of each endpoint or client assigned to a given configuration. - </para> - <para> - Please refer to the - <ulink url="https://docs.jboss.org/author/display/AS71/Web+services+configu... Application Server 7 documentation</ulink> - for any detail on managing the - <emphasis role="italics">webservices</emphasis> - subsystem to add, remove or modify handlers and properties. - </para> - <para> - The allowed contents in the - <emphasis role="italics">webservices</emphasis> - subsystem are defined by the - <ulink url="https://github.com/jbossas/jboss-as/blob/master/build/src/main/... - included in the application server. - </para> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Standardconfigurations"> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-Automaticconfigurationfromdefaultdescriptors"> - <title>Standard configurations</title> + <title>Automatic configuration from default descriptors</title> <para> - Clients running in-container as well as endpoints are assigned standard configurations by default. Those are used unless different configurations are set as previously described. This way administrators can tune default handler chains for client and endpoints developers did not assign a specific configuration to. The name for such default configuration, to be used in the JBoss AS 7 webservices subsystem are - <code>Standard-Client-Config</code> - and - <code>Standard-Endpoint-Config</code> - . + In some cases, the application developer might not be aware of the configuration that will need to be used for its client and endpoint implementation, perhaps because that's a concern of the application deployer. In other cases, explicit usage (compile time dependency) of JBossWS API might not be accepted. To cope with such scenarios, JBossWS allows including default client ( + <code>jaxws-client-config.xml</code> + ) and endpoint ( + <code>jaxws-endpoint-config.xml</code> + ) descriptor within the application (in its root), which are parsed for getting configurations any time a configuration file name is not specified. </para> + <para>If the configuration name is also not specified, JBossWS automatically looks for a configuration named the same as</para> + <itemizedlist> + <listitem> + <para>the endpoint implementation class (full qualified name), in case of JAX-WS endpoints;</para> + </listitem> + <listitem> + <para>the service endpoint interface (full qualified name), in case of JAX-WS clients.</para> + </listitem> + </itemizedlist> + <para> + No automatic configuration name is selected for + <code>Dispatch</code> + clients. + </para> + <para> + So, for instance, an endpoint implementation class + <code>org.foo.bar.EndpointImpl</code> + for which no pre-defined configuration is explicitly set will cause JBossWS to look for a + <emphasis role="italics">org.foo.bar.EndpointImpl</emphasis> + named configuration within a + <emphasis role="italics">jaxws-endpoint-config.xml</emphasis> + descriptor in the root of the application deployment. Similarly, on client side, a client proxy implementing + <code>org.foo.bar.Endpoint</code> + interface (SEI) will have the setup read from a + <emphasis role="italics">org.foo.bar.Endpoint</emphasis> + named configuration in + <emphasis role="italics">jaxws-client-config.xml</emphasis> + descriptor. + </para> </section> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Handlersclassloading"> + <section id="sid-41713670_Predefinedclientandendpointconfigurations-Automaticconfigurationassignmentfromcontainersetup"> - <title>Handlers classloading</title> + <title>Automatic configuration assignment from container setup</title> + <para>JBossWS fall-backs to getting predefined configurations from the container setup whenever no explicit configuration has been provided and the default descriptors are either not available or do not contain relevant configurations. This gives additional control on the JAX-WS client and endpoint setup to administrators, as the container setup can be managed independently from the deployed applications.</para> + <para>JBossWS hence accesses the webservices subsystem the same as explained above for explicitly named configuration; the default configuration names used for look are</para> + <itemizedlist> + <listitem> + <para>the endpoint implementation class (full qualified name), in case of JAX-WS endpoints;</para> + </listitem> + <listitem> + <para>the service endpoint interface (full qualified name), in case of JAX-WS clients.</para> + </listitem> + </itemizedlist> <para> - When setting a server-wide handler, please note the handler class needs to be available either through each ws deployment classloader or the - <code>org.jboss.as.webservices.server.integration:main</code> - module classloader. As a consequence proper module dependencies might need to be specified either in the deployments that are going to leverage a given predefined configuration or directly in the previously mentioned AS7 module. + <code>Dispatch</code> + clients are not automatically configured. If no configuration is found using names computed as above, the + <code>Standard-Client-Config</code> + and + <code>Standard-Endpoint-Config</code> + configurations are used for clients and endpoints respectively </para> </section> </section> - <section id="sid-41713670_Predefinedclientandendpointconfigurations-Examples"> - - <title>Examples</title> - <example> - <title>JBoss AS 7.2 default configurations</title> - <programlisting> -&lt;subsystem xmlns="urn:jboss:domain:webservices:1.2"&gt; - &lt;!-- ... --&gt; - &lt;endpoint-config name="Standard-Endpoint-Config"/&gt; - &lt;endpoint-config name="Recording-Endpoint-Config"&gt; - &lt;pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM"&gt; - &lt;handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/&gt; - &lt;/pre-handler-chain&gt; - &lt;/endpoint-config&gt; - &lt;client-config name="Standard-Client-Config"/&gt; -&lt;/subsystem&gt;</programlisting> - </example> - <example> - <title>A configuration file for a deployment specific ws-security endpoint setup</title> - <programlisting> -&lt;jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"&gt; - &lt;endpoint-config&gt; - &lt;config-name&gt;Custom WS-Security Endpoint&lt;/config-name&gt; - &lt;property&gt; - &lt;property-name&gt;ws-security.signature.properties&lt;/property-name&gt; - &lt;property-value&gt;bob.properties&lt;/property-value&gt; - &lt;/property&gt; - &lt;property&gt; - &lt;property-name&gt;ws-security.encryption.properties&lt;/property-name&gt; - &lt;property-value&gt;bob.properties&lt;/property-value&gt; - &lt;/property&gt; - &lt;property&gt; - &lt;property-name&gt;ws-security.signature.username&lt;/property-name&gt; - &lt;property-value&gt;bob&lt;/property-value&gt; - &lt;/property&gt; - &lt;property&gt; - &lt;property-name&gt;ws-security.encryption.username&lt;/property-name&gt; - &lt;property-value&gt;alice&lt;/property-value&gt; - &lt;/property&gt; - &lt;property&gt; - &lt;property-name&gt;ws-security.callback-handler&lt;/property-name&gt; - &lt;property-value&gt;org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback&lt;/property-value&gt; - &lt;/property&gt; - &lt;/endpoint-config&gt; -&lt;/jaxws-config&gt;</programlisting> - </example> - <example> - <title>JBoss AS 7.2 default configurations modified to default to SOAP messages schema-validation on</title> - <programlisting>&lt;subsystem xmlns="urn:jboss:domain:webservices:1.2"&gt; - &lt;!-- ... --&gt; - &lt;endpoint-config name="Standard-Endpoint-Config"&gt; - &lt;property name="schema-validation-enabled" value="true"/&gt; - &lt;/endpoint-config&gt; - &lt;!-- ... --&gt; - &lt;client-config name="Standard-Client-Config"&gt; - &lt;property name="schema-validation-enabled" value="true"/&gt; - &lt;/client-config&gt; -&lt;/subsystem&gt;</programlisting> - </example> - </section> </section> <section id="sid-3866749"> @@ -702,7 +855,7 @@ &lt;/jboss-web&gt; </programlisting> </informalexample> - <para>The security domain as well as its the authentication and authorization mechanisms are defined differently depending on the JBoss Application Server in use.</para> + <para>The security domain as well as its the authentication and authorization mechanisms are defined differently depending on the server in use.</para> </section> <section id="sid-3866749_Authentication-UseBindingProvidertosetprincipal%2Fcredential"> @@ -776,7 +929,7 @@ <important> <para> For further information on configuring security domains in WildFly, please refer to - <ulink url="https://docs.jboss.org/author/display/WFLY8/Security+subsystem+... + <ulink url="https://docs.jboss.org/author/display/WFLY9/Security+subsystem+... . </para> </important> @@ -876,7 +1029,7 @@ <title>JBossWS integration layer with Apache CXF</title> <para> - All JAX-WS functionalities provided by JBossWS on top of JBoss Application Server are currently served through a proper integration of the JBoss Web Services stack with most of the + All JAX-WS functionalities provided by JBossWS on top of WildFly are currently served through a proper integration of the JBoss Web Services stack with most of the <ulink url="http://cxf.apache.org/">Apache CXF</ulink> project modules. </para> @@ -888,10 +1041,10 @@ </para> <itemizedlist> <listitem> - <para>allowing using standard webservices APIs (including JAX-WS) on JBoss Application Server; this is performed internally leveraging Apache CXF without requiring the user to deal with it;</para> + <para>allowing using standard webservices APIs (including JAX-WS) on WildFly; this is performed internally leveraging Apache CXF without requiring the user to deal with it;</para> </listitem> <listitem> - <para>allowing using Apache CXF advanced features (including WS-*) on top of JBoss Application server without requiring the user to deal with / setup / care about the required integration steps for running in such a container.</para> + <para>allowing using Apache CXF advanced features (including WS-*) on top of WildFly without requiring the user to deal with / setup / care about the required integration steps for running in such a container.</para> </listitem> </itemizedlist> <para>In order for achieving the goals above, the JBossWS-CXF integration supports the JBoss ws endpoint deployment mechanism and comes with many internal customizations on top of Apache CXF.</para> @@ -911,17 +1064,17 @@ <code>cxf.xml</code> descriptors; those may contain any basic bean plus specific ws client and endpoint beans which CXF has custom parsers for. Apache CXF can be used to deploy webservice endpoints on any servlet container by including its libraries in the deployment; in such a scenario Spring basically serves as a convenient configuration option, given direct Apache CXF API usage won't be very handy. Similar reasoning applies on client side, where a Spring based descriptor offers a shortcut for setting up Apache CXF internals. </para> - <para>This said, nowadays almost any Apache CXF functionality can be configured and used through direct API usage, without Spring.</para> + <para>This said, nowadays almost any Apache CXF functionality can be configured and used through direct API usage, without Spring. As a consequence of that and given the considerations in the sections below, the JBossWS integration with Apache CXF does not rely on Spring descriptors.</para> <section id="sid-3866786_ApacheCXFintegration-Portableapplications"> <title>Portable applications</title> - <para>The JBoss Application Server is much more then a servlet container; it actually provides users with a fully compliant target platform for Java EE applications.</para> + <para>WildFly is much more then a servlet container; it actually provides users with a fully compliant target platform for Java EE applications.</para> <para> Generally speaking, <emphasis role="italics">users are encouraged to write portable applications</emphasis> by relying only on <emphasis role="italics">JAX-WS specification</emphasis> - whenever possible. That would by the way ensure easy migrations to and from other compliant platforms. Being a Java EE container, JBoss Application Server already comes with a JAX-WS compliant implementation, which is basically Apache CXF plus the JBossWS-CXF integration layer. So users just need to write their JAX-WS application; + whenever possible. That would by the way ensure easy migrations to and from other compliant platforms. Being a Java EE container, WildFlt already comes with a JAX-WS compliant implementation, which is basically Apache CXF plus the JBossWS-CXF integration layer. So users just need to write their JAX-WS application; <emphasis role="italics">no need for embedding any Apache CXF or any ws related dependency library in user deployments</emphasis> . Please refer to the <xref linkend="sid-3866716"/> @@ -937,9 +1090,6 @@ <emphasis role="italics">without Spring descriptors</emphasis> . </para> - <para> - <emphasis role="strong">The following two paragraphs provide few directions on how to deploy or use applications explicitly relying on Apache CXF, users should however prefer the portable application approach whenever possible.</emphasis> - </para> </section> <section id="sid-3866786_ApacheCXFintegration-DirectApacheCXFAPIusage"> @@ -948,177 +1098,15 @@ <para> On server side, direct Apache CXF API usage might not be always possible or end up being not very easy. For this reason, the JBossWS integration comes with a convenient alternative through customization options in the <code>jboss-webservices.xml</code> - descriptor described below on this page. + descriptor described below on this page. Properties can be declared in + <code>jboss-webservices.xml</code> + to control Apache CXF internals like + <emphasis role="italics">interceptors</emphasis> + , + <emphasis role="italics">features</emphasis> + , etc. </para> </section> - <section id="sid-3866786_ApacheCXFintegration-Springdescriptorsusage"> - - <title>Spring descriptors usage</title> - <para> - Finally, in some cases, users might still want to consume Spring descriptors ( - <emphasis role="strong">discouraged approach</emphasis> - ); that's possibly the case of applications developed on and being migrated from different environments. For such scenarios, the installation of Spring Framework libraries on application server is the suggested approach. That can be performed using the JBossWS-CXF installation script or by manually populating a - <emphasis role="italics">org.springframework.spring</emphasis> - JBoss AS module with the required Spring jars. For writing the - <code>module.xml</code> - descriptor for such a module please refer the relevant JBoss AS documentation on creating modules; in any case it would look similar to: - </para> - <informalexample> - <programlisting>&lt;module xmlns="urn:jboss:module:1.1" name="org.springframework.spring"&gt; - &lt;resources&gt; - &lt;!-- List references to jar resources here --&gt; - &lt;/resources&gt; - &lt;dependencies&gt; - &lt;module name="javax.api" /&gt; - &lt;module name="javax.jms.api" /&gt; - &lt;module name="javax.annotation.api" /&gt; - &lt;module name="org.apache.commons.logging" /&gt; - &lt;module name="org.jboss.vfs" /&gt; - &lt;/dependencies&gt; -&lt;/module&gt;</programlisting> - </informalexample> - <para> - The other webservices modules on JBoss AS already have an optional dependency on - <emphasis role="italics">org.springframework.spring</emphasis> - module and will hence automatically consume it. - </para> - <para>Once the Spring module is available on target application server, Spring based Apache CXF buses can be built up.</para> - <section id="sid-3866786_ApacheCXFintegration-Clientside"> - - <title>Client side</title> - <para> - Whenever Spring is available in the current thread classloader (possibly as a consequence of having set a dependency to the above mentioned - <code>org.springframework.spring</code> - module) and the classloader can successfully locate a valid Spring descriptor resource, a Spring based - <code>Bus</code> - will be created if required. So user can either: - </para> - <itemizedlist> - <listitem> - <para> - programmatically use a - <code>SpringBusFactory</code> - (or the - <code>JBossWSBusFactory</code> - if the JBossWS additions are available) to load a Spring Bus from a given - <emphasis role="italics">cxf.xml</emphasis> - descriptor; that can include any CXF customization or client bean; - </para> - </listitem> - <listitem> - <para> - build a JAX-WS client and let the JAX-WS Provider implementation internally build a Spring based - <code>Bus</code> - using the available - <emphasis role="italics">cxf.xml</emphasis> - resource retrieved from the current classloader (usually found in - <emphasis role="italics">META-INF/cxf.xml</emphasis> - ). - </para> - </listitem> - </itemizedlist> - <para> - Consider having a look at - <link linkend="sid-4784150">this page</link> - for directions on setting module dependencies, especially if willing to create a ws client within a Spring Bus and running in-container. - </para> - <para> - Finally please be sure to check the section below on - <code>Bus</code> - usage any time you're building a - <code>Bus</code> - on client side. - </para> - </section> - <section id="sid-3866786_ApacheCXFintegration-Serverside"> - - <title>Server side</title> - <para>It is possible to customize the JBossWS integration with Apache CXF by incorporating a CXF configuration file into the endpoint deployment archive. The convention is the following:</para> - <itemizedlist> - <listitem> - <para> - the descriptor file name must be - <emphasis role="strong">jbossws-cxf.xml</emphasis> - </para> - </listitem> - <listitem> - <para> - for POJO deployments it is located in - <emphasis role="strong">WEB-INF</emphasis> - directory - </para> - </listitem> - <listitem> - <para> - for EJB3 deployments it is located in - <emphasis role="strong">META-INF</emphasis> - directory - </para> - </listitem> - </itemizedlist> - <para> - The - <emphasis role="italics">jbossws-cxf.xml</emphasis> - is parsed similarly to a common - <emphasis role="italics">cxf.xml</emphasis> - in order for building up a - <code>Bus</code> - for the WS deployment; the endpoint beans included in the deployment are to be specified using the - <code>&lt;jaxws:endpoint&gt;</code> - tag the same they would be specified in a - <emphasis role="italics">cxf.xml</emphasis> - descriptor (a example from the testsuite can be seen - <ulink url="http://anonsvn.jboss.org/repos/jbossws/stack/cxf/tags/jbossws-c... - ). The application server HTTP engine will be serving the endpoints. - </para> - <para> - If there is no - <code>&lt;jaxws:endpoint&gt;</code> - defined in - <emphasis role="italics">jbossws-cxf.xml</emphasis> - , the endpoint classes mentioned in - <emphasis role="italics">WEB-INF/web.xml</emphasis> - will be automatically transformed to - <code>&lt;jaxws:endpoint&gt;</code> - entries in the Spring configuration and loaded by JBossWS-CXF. This allows using the jbossws-cxf.xml to customize the bus without having to manually duplicate the endpoint information in the descriptor. The following is an example of configuring an endpoint through - <emphasis role="italics">web.xml</emphasis> - with Aegis databinding setup from - <emphasis role="italics">jbossws-cxf.xml</emphasis> - : - </para> - <informalexample> - <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"&gt; - &lt;servlet&gt; - &lt;servlet-name&gt;AegisGroupQueryService&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.jboss.test.ws.jaxws.cxf.aegis.AegisGroupQueryImpl&lt;/servlet-class&gt; - &lt;/servlet&gt; - &lt;servlet-mapping&gt; - &lt;servlet-name&gt;AegisGroupQueryService&lt;/servlet-name&gt; - &lt;url-pattern&gt;/*&lt;/url-pattern&gt; - &lt;/servlet-mapping&gt; -&lt;/web-app&gt;</programlisting> - </informalexample> - <informalexample> - <programlisting>&lt;beans xmlns='http://www.springframework.org/schema/beans' - xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:beans='http://www.springframework.org/schema/beans' - xmlns:jaxws='http://cxf.apache.org/jaxws' - xsi:schemaLocation='http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd - http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd - http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd'&gt; - &lt;bean id="aegisBean" class="org.apache.cxf.aegis.databinding.AegisDatabinding" scope="prototype" /&gt; - &lt;bean name="{http://aegis.cxf.jaxws.ws.test.jboss.org/}AegisGroupQueryImpl... abstract="true"&gt; - &lt;property name="dataBinding" ref="aegisBean" /&gt; - &lt;/bean&gt; -&lt;/beans&gt; </programlisting> - </informalexample> - <para> - The - <emphasis role="italics">jbossws-cxf.xml</emphasis> - approach can be used for the very few scenarios Apache CXF can be configured for only using Spring descriptor, e.g. for some advanced WS-RM customizations. - </para> - </section> - </section> </section> <section id="sid-3866786_ApacheCXFintegration-Bususage"> @@ -1150,9 +1138,7 @@ <code>BusFactory</code> , <code>org.jboss.wsf.stack.cxf.client.configuration.JBossWSBusFactory</code> - , that allows for automatic detection of - <emphasis role="italics">Spring</emphasis> - availability as well as seamless setup of JBossWS customizations on top of Apache CXF. So, assuming the JBossWS-CXF libraries are available in the current thread context classloader, the + , that allows for seamless setup of JBossWS customizations on top of Apache CXF. So, assuming the JBossWS-CXF libraries are available in the current thread context classloader, the <code>JBossWSBusFactory</code> is <emphasis role="italics">automatically</emphasis> @@ -1161,9 +1147,7 @@ call above. </para> <para> - JBossWS users willing to explicitely use functionalities of - <code>org.apache.cxf.bus.spring.SpringBusFactory</code> - or + JBossWS users willing to explicitly use functionalities of <code>org.apache.cxf.bus.CXFBusFactory</code> <emphasis role="italics">,</emphasis> get the same API with JBossWS additions through @@ -1171,10 +1155,6 @@ : </para> <informalexample> - <programlisting>String myConfigFile = ... -Bus bus = new JBossWSBusFactory().createBus(myConfigFile);</programlisting> - </informalexample> - <informalexample> <programlisting>Map&lt;Class, Object&gt; myExtensions = new HashMap&lt;Class, Object&gt;(); myExtensions.put(...); Bus bus = new JBossWSBusFactory().createBus(myExtensions);</programlisting> @@ -1216,7 +1196,7 @@ <emphasis role="italics">getThreadDefaultBus(true)</emphasis> first fallback to retrieving the configured global default bus before actually trying creating a new instance (and the created new instance is set as global default bus if that was not set there yet). </para> - <para>The drawback of this mechanism (which is basically fine in JSE environment) is that when running in a JBoss AS container you need to be careful in order not to (mis)use a bus over multiple applications (assuming the Apache CXF classes are loaded by the same classloader, which is currently the case with JBoss AS6, JBoss AS7 and WildFly).</para> + <para>The drawback of this mechanism (which is basically fine in JSE environment) is that when running in WildFly container you need to be careful in order not to (mis)use a bus over multiple applications (assuming the Apache CXF classes are loaded by the same classloader, which is currently the case with WildFly).</para> <para>Here is a list of general suggestions to avoid problems when running in-container:</para> <itemizedlist> <listitem> @@ -1299,7 +1279,7 @@ <section id="sid-3866786_ApacheCXFintegration-Threadcontextclassloaderbusstrategy%28TCCLBUS%29"> <title>Thread context classloader bus strategy (TCCL_BUS)</title> - <para>The last strategy is to have the bus created for serving the client be associated to the current thread context classloader (TCCL). That basically means the same Bus instance is shared by JAXWS clients running when the same TCCL is set. This is particularly interesting as each web application deployment usually has its own context classloader, so this strategy is possibly a way to keep the number of created Bus instances bound to the application number in a JBoss AS container.</para> + <para>The last strategy is to have the bus created for serving the client be associated to the current thread context classloader (TCCL). That basically means the same Bus instance is shared by JAXWS clients running when the same TCCL is set. This is particularly interesting as each web application deployment usually has its own context classloader, so this strategy is possibly a way to keep the number of created Bus instances bound to the application number in a WildFly container.</para> <para>If there's a bus already associated to the current thread before the JAXWS client creation, that is automatically restored when returning control to the user; in other words, the bus corresponding to the current thread context classloader will be used only for the created JAXWS client but won't stay associated to the current thread at the end of the process. If the thread was not associated to any bus before the client creation, a new bus will be created (and later user for any other client built with this strategy and the same TCCL in place); no bus will be associated to the thread at the end of the client creation.</para> </section> <section id="sid-3866786_ApacheCXFintegration-Strategyconfiguration"> @@ -1439,7 +1419,7 @@ ... &lt;/webservices&gt;</programlisting> </informalexample> - <para>JBossWS-CXF integration comes with a set of allowed property names to control Apache CXF internals. The main advantage of the property based approach is that it does not require Spring libraries.</para> + <para>JBossWS-CXF integration comes with a set of allowed property names to control Apache CXF internals.</para> <section id="sid-3866786_ApacheCXFintegration-WorkQueueconfiguration"> <title>WorkQueue configuration</title> @@ -1449,9 +1429,7 @@ is installed in the Bus as an extension and allows for adding / removing queues as well as controlling the existing ones. </para> <para> - On server side, queues can be provided through - <emphasis role="italics">Spring</emphasis> - based Bus declaration or by using the + On server side, queues can be provided by using the <code>cxf.queue.&lt;queue-name&gt;.*</code> properties in <code>jboss-webservices.xml</code> @@ -1553,7 +1531,7 @@ <title>MBean management</title> <para> - Apache CXF allows managing its MBean objects that are installed into the JBoss AS MBean server. The feature is enabled on a deployment basis through the + Apache CXF allows managing its MBean objects that are installed into the WildFly MBean server. The feature is enabled on a deployment basis through the <code>cxf.management.enabled</code> property in <code>jboss-webservices.xml</code> @@ -1585,6 +1563,62 @@ . </para> </section> + <section id="sid-3866786_ApacheCXFintegration-Interceptors"> + + <title>Interceptors</title> + <para> + The + <code>jboss-webservices.xml</code> + descriptor also allows specifying the + <code>cxf.interceptors.in</code> + and + <code>cxf.interceptors.out</code> + properties; those allows declaring interceptors to be attached to the Bus instance that's created for serving the deployment. + </para> + <informalexample> + <programlisting>&lt;?xml version="1.1" encoding="UTF-8"?&gt; +&lt;webservices + xmlns="http://www.jboss.com/xml/ns/javaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + version="1.2" + xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee"&gt; + + &lt;property&gt; + &lt;name&gt;cxf.interceptors.in&lt;/name&gt; + &lt;value&gt;org.jboss.test.ws.jaxws.cxf.interceptors.BusInterceptor&lt;/value&gt; + &lt;/property&gt; + &lt;property&gt; + &lt;name&gt;cxf.interceptors.out&lt;/name&gt; + &lt;value&gt;org.jboss.test.ws.jaxws.cxf.interceptors.BusCounterInterceptor&lt;/value&gt; + &lt;/property&gt; +&lt;/webservices&gt;</programlisting> + </informalexample> + </section> + <section id="sid-3866786_ApacheCXFintegration-Features"> + + <title>Features</title> + <para> + The + <code>jboss-webservices.xml</code> + descriptor also allows specifying the + <code>cxf.features</code> + property; that allows declaring features to be attached to any endpoint belonging to the Bus instance that's created for serving the deployment. + </para> + <informalexample> + <programlisting>&lt;?xml version="1.1" encoding="UTF-8"?&gt; +&lt;webservices + xmlns="http://www.jboss.com/xml/ns/javaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + version="1.2" + xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee"&gt; + + &lt;property&gt; + &lt;name&gt;cxf.features&lt;/name&gt; + &lt;value&gt;org.apache.cxf.feature.FastInfosetFeature&lt;/value&gt; + &lt;/property&gt; +&lt;/webservices&gt;</programlisting> + </informalexample> + </section> <section id="sid-3866786_ApacheCXFintegration-WSDiscoveryenablement"> <title>Discovery enablement</title> @@ -1598,10 +1632,350 @@ </section> </section> </section> + <section id="sid-3866786_ApacheCXFintegration-ApacheCXFinterceptors"> + + <title>Apache CXF interceptors</title> + <para>Apache CXF supports declaring interceptors using one of the following approaches:</para> + <itemizedlist> + <listitem> + <para> + Annotation usage on endpoint classes ( + <code&gt;(a)org.apache.cxf.interceptor.InInterceptor&lt;/code&gt; + , + <code&gt;(a)org.apache.cxf.interceptor.OutInterceptor&lt;/code&gt; + ) + </para> + </listitem> + <listitem> + <para> + Direct API usage on client side (through the + <code>org.apache.cxf.interceptor.InterceptorProvider</code> + interface) + </para> + </listitem> + <listitem> + <para> + Spring descriptor usage ( + <emphasis role="italics">cxf.xml</emphasis> + ) + </para> + </listitem> + </itemizedlist> + <para> + As the Spring descriptor usage is not supported, the JBossWS integration adds an additional descriptor based approach to avoid requiring modifications to the actual client/endpoint code. Users can declare interceptors within + <link linkend="sid-41713670">predefined client and endpoint configurations</link> + by specifying a list of interceptor class names for the + <code>cxf.interceptors.in</code> + and + <code>cxf.interceptors.out</code> + properties. + </para> + <informalexample> + <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" + xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"&gt; + &lt;endpoint-config&gt; + &lt;config-name&gt;org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl&lt;/config-name&gt; + &lt;property&gt; + &lt;property-name&gt;cxf.interceptors.in&lt;/property-name&gt; + &lt;property-value&gt;org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor&lt;/property-value&gt; + &lt;/property&gt; + &lt;property&gt; + &lt;property-name&gt;cxf.interceptors.out&lt;/property-name&gt; + &lt;property-value&gt;org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor&lt;/property-value&gt; + &lt;/property&gt; + &lt;/endpoint-config&gt; +&lt;/jaxws-config&gt;</programlisting> + </informalexample> + <para>A new instance of each specified interceptor class will be added to the client or endpoint the configuration is assigned to. The interceptor classes must have a no-argument constructor.</para> + </section> + <section id="sid-3866786_ApacheCXFintegration-ApacheCXFfeatures"> + + <title>Apache CXF features</title> + <para>Apache CXF supports declaring features using one of the following approaches:</para> + <itemizedlist> + <listitem> + <para> + Annotation usage on endpoint classes ( + <code&gt;(a)org.apache.cxf.feature.Features&lt;/code&gt; + ) + </para> + </listitem> + <listitem> + <para> + Direct API usage on client side (through extensions of the + <code>org.apache.cxf.feature.AbstractFeature</code> + class) + </para> + </listitem> + <listitem> + <para> + Spring descriptor usage ( + <emphasis role="italics">cxf.xml</emphasis> + ) + </para> + </listitem> + </itemizedlist> + <para> + As the Spring descriptor usage is not supported, the JBossWS integration adds an additional descriptor based approach to avoid requiring modifications to the actual client/endpoint code. Users can declare features within + <link linkend="sid-41713670">predefined client and endpoint configurations</link> + by specifying a list of feature class names for the + <code>cxf.features</code> + property. + </para> + <informalexample> + <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" + xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"&gt; + &lt;endpoint-config&gt; + &lt;config-name&gt;Custom FI Config&lt;/config-name&gt; + &lt;property&gt; + &lt;property-name&gt;cxf.features&lt;/property-name&gt; + &lt;property-value&gt;org.apache.cxf.feature.FastInfosetFeature&lt;/property-value&gt; + &lt;/property&gt; + &lt;/endpoint-config&gt; +&lt;/jaxws-config&gt;</programlisting> + </informalexample> + <para>A new instance of each specified feature class will be added to the client or endpoint the configuration is assigned to. The feature classes must have a no-argument constructor.</para> + </section> + <section id="sid-3866786_ApacheCXFintegration-Propertiesdrivenbeancreation"> + + <title>Properties driven bean creation</title> + <para> + Sections above explain how to declare CXF interceptors and features through properties either in a client/endpoint predefined configuration or in a + <code>jboss-webservices.xml</code> + descriptor. By getting the feature/interceptor class name only specified, the container simply tries to create a bean instance using the class default constructor. This sets a limitation on the feature/interceptor configuration, unless custom extensions of vanilla CXF classes are provided, with the default constructor setting properties before eventually using the super constructor. + </para> + <para> + To cope with this issue, JBossWS integration comes with a mechanism for configuring simple bean hierarchies when building them up from properties. Properties can have bean reference values, that is strings starting with + <code>##</code> + . Property reference keys are used to specify the bean class name and the value for for each attribute. So for instance the following properties: + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Key + + </para> + </entry> + <entry> + <para> + Value + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + cxf.features + + </para> + </entry> + <entry> + <para> + ##foo, ##bar + + </para> + </entry> + </row> + <row> + <entry> + <para> + ##foo + + </para> + </entry> + <entry> + <para> + org.jboss.Foo + + </para> + </entry> + </row> + <row> + <entry> + <para> + ##foo.par + + </para> + </entry> + <entry> + <para> + 34 + + </para> + </entry> + </row> + <row> + <entry> + <para> + ##bar + + </para> + </entry> + <entry> + <para> + org.jboss.Bar + + </para> + </entry> + </row> + <row> + <entry> + <para> + ##bar.color + + </para> + </entry> + <entry> + <para> + blue + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>would result into the stack installing two feature instances, the same that would have been created by</para> + <informalexample> + <programlisting>import org.Bar; +import org.Foo; + +... + +Foo foo = new Foo(); +foo.setPar(34); +Bar bar = new Bar(); +bar.setColor("blue");</programlisting> + </informalexample> + <para>The mechanism assumes that the classes are valid beans with proper getter and setter methods; value objects are cast to the correct primitive type by inspecting the class definition. Nested beans can of course be configured.</para> + </section> + <section id="sid-3866786_ApacheCXFintegration-HTTPConduitconfiguration"> + + <title>HTTPConduit configuration</title> + <para> + HTTP transport setup in Apache CXF is achieved through + <code>org.apache.cxf.transport.http.HTTPConduit</code> + <ulink url="http://cxf.apache.org/docs/client-http-transport-including-ssl-... + . When running on top of the JBossWS integration, conduits can be programmatically modified using the Apache CXF API as follows: + </para> + <informalexample> + <programlisting>import org.apache.cxf.frontend.ClientProxy; +import org.apache.cxf.transport.http.HTTPConduit; +import org.apache.cxf.transports.http.configuration.HTTPClientPolicy; + +//set chunking threshold before using a JAX-WS port client +... +HTTPConduit conduit = (HTTPConduit)ClientProxy.getClient(port).getConduit(); +HTTPClientPolicy client = conduit.getClient(); + +client.setChunkingThreshold(8192); +... +</programlisting> + </informalexample> + <para>Users can also control the default values for the most common HTTPConduit parameters by setting specific system properties; the provided values will override Apache CXF defaut values.</para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para> + Property + + </para> + </entry> + <entry> + <para> + Description + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>cxf.client.allowChunking</para> + </entry> + <entry> + <para> + A boolean to tell Apache CXF whether to allow send messages using chunking. + + </para> + </entry> + </row> + <row> + <entry> + <para>cxf.client.chunkingThreshold</para> + </entry> + <entry> + <para> + An integer value to tell Apache CXF the threshold at which switching from non-chunking to chunking mode. + + </para> + </entry> + </row> + <row> + <entry> + <para>cxf.client.connectionTimeout</para> + </entry> + <entry> + <para> + A long value to tell Apache CXF how many milliseconds to set the connection timeout to + + </para> + </entry> + </row> + <row> + <entry> + <para>cxf.client.receiveTimeout</para> + </entry> + <entry> + <para>A long value to tell Apache CXF how many milliseconds to set the receive timeout to</para> + </entry> + </row> + <row> + <entry> + <para>cxf.client.connection</para> + </entry> + <entry> + <para> + A string to tell Apache CXF to use + <code>Keep-Alive</code> + or + <code>close</code> + connection type + + </para> + </entry> + </row> + <row> + <entry> + <para>cxf.tls-client.disableCNCheck</para> + </entry> + <entry> + <para> + A boolean to tell Apache CXF whether disabling CN host name check or not + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>The vanilla Apache CXF defaults apply when the system properties above are not set.</para> + </section> </section> <section id="sid-3866793"> - <title>WS-Addressing</title> + <title>Addressing</title> <para> JBoss Web Services inherits full WS-Addressing capabilities from the underlying Apache CXF implementation. Apache CXF provides support for 2004-08 and <ulink url="http://www.w3.org/TR/ws-addr-core/">1.0</ulink> @@ -1645,7 +2019,7 @@ <para> specifying the  <emphasis role="italics">[http://cxf.apache.org/ws/addressing]addressi... - feature for a given client/endpoint in an optional CXF Spring XML descriptor + feature for a given client/endpoint </para> </listitem> <listitem> @@ -1682,7 +2056,7 @@ </section> <section id="sid-3866793_WS-Addressing-WSAddressingPolicy"> - <title>WS-Addressing Policy</title> + <title>Addressing Policy</title> <para>The WS-Addressing support is also perfectly integrated with the Apache CXF WS-Policy engine.</para> <para> This basically means that the WSDL contract generation for code-first endpoint deployment is policy-aware: users can annotate endpoints with the @@ -1973,6 +2347,19 @@ </para> </entry> </row> + <row> + <entry> + <para>ws-security.enable.streaming</para> + </entry> + <entry> + <para> + Enable + <ulink url="http://ws.apache.org/wss4j/streaming.html">streaming<... + (StAX based) processing of WS-Security messages + + </para> + </entry> + </row> </tbody> </tgroup> </informaltable> @@ -2380,7 +2767,7 @@ </informalexample> <important> <para> - If you're deploying the endpoint archive to JBoss Application Server 7, remember to add a dependency to + If you're deploying the endpoint archive to WildFly, remember to add a dependency to <emphasis role="italics">org.apache.ws.security</emphasis> module in the MANIFEST.MF file. </para> @@ -2462,7 +2849,7 @@ <emphasis role="italics">ws-security.username</emphasis> and <emphasis role="italics">ws-security.callback-handler</emphasis> - properties can be used similarly as shown in the signature and encryption example. Things become more interesting when requiring a given user to be authenticated (and authorized) against a security domain on the target JBoss Application Server. + properties can be used similarly as shown in the signature and encryption example. Things become more interesting when requiring a given user to be authenticated (and authorized) against a security domain on the target WildFly server. </para> <para>On server side, you need to install two additional interceptors that act as bridges towards the application server authentication layer:</para> <itemizedlist> @@ -2481,7 +2868,7 @@ </para> </listitem> </itemizedlist> - <para>So, here follows an example of WS-SecurityPolicy endpoint using Username Token Profile for authenticating through the JBoss Application Server security domain system.</para> + <para>So, here follows an example of WS-SecurityPolicy endpoint using Username Token Profile for authenticating through the WildFly security domain system.</para> <section id="sid-3866795_WS-Security-Endpointx"> <title>Endpoint</title> @@ -2749,7 +3136,7 @@ </informalexample> <important> <para> - If you're deploying the endpoint archive to JBoss Application Server 7, remember to add a dependency to + If you're deploying the endpoint archive to WildFly, remember to add a dependency to <emphasis role="italics">org.apache.ws.security</emphasis> and <emphasis role="italics">org.apache.cxf</emphasis> @@ -3009,7 +3396,7 @@ <section id="sid-47972359_WS-TrustandSTS-ApacheCXFsupport"> <title>Apache CXF support</title> - <para>Apache CXF is an open-source, fully featured Web services framework. The JBossWS open source project integrates the JBoss Web Services (JBossWS) stack with the Apache CXF project modules thus providing WS-Trust and other JAX-WS functionality in the JBoss Application Server. This integration makes it easy to deploy CXF STS implementations, however JBoss Application Server can run any WS-Trust compliant STS. In addition the Apache CXF API provides a STSClient utility to facilitate web service requester communication with its STS.</para> + <para>Apache CXF is an open-source, fully featured Web services framework. The JBossWS open source project integrates the JBoss Web Services (JBossWS) stack with the Apache CXF project modules thus providing WS-Trust and other JAX-WS functionality in WildFly. This integration makes it easy to deploy CXF STS implementations, however WildFly can run any WS-Trust compliant STS. In addition the Apache CXF API provides a STSClient utility to facilitate web service requester communication with its STS.</para> <para> Detailed information about the Apache CXF's WS-Trust implementation can be found <ulink url="http://coheigea.blogspot.it/2011/10/apache-cxf-sts-documentation-part-i.html">here</ulink> @@ -3338,7 +3725,7 @@ <para> The web service provider implementation class, ServiceImpl, is a simple POJO. It uses the standard WebService annotation to define the service endpoint. In addition there are two Apache CXF annotations, EndpointProperties and EndpointProperty used for configuring the endpoint for the CXF runtime. These annotations come from the <ulink url="https://ws.apache.org/wss4j/">Apache WSS4J project</ulink> - , which provides a Java implementation of the primary WS-Security standards for Web Services. These annotations are programmatically adding properties to the endpoint. Traditionally, these properties would be set via the &lt;jaxws:properties&gt; element on the &lt;jaxws:endpoint&gt; element in the spring config, but these annotations allow the properties to be configured in the code. + , which provides a Java implementation of the primary WS-Security standards for Web Services. These annotations are programmatically adding properties to the endpoint. With plain Apache CXF, these properties are often set via the &lt;jaxws:properties&gt; element on the &lt;jaxws:endpoint&gt; element in the Spring config; these annotations allow the properties to be configured in the code. </para> <para>WSS4J uses the Crypto interface to get keys and certificates for encryption/decryption and for signature creation/verification. As is asserted by the WSDL, X509 keys and certificates are required for this service. The WSS4J configuration information being provided by ServiceImpl is for Crypto's Merlin implementation. More information will be provided about this in the keystore section.</para> <para>The first EndpointProperty statement in the listing is declaring the user's name to use for the message signature. It is used as the alias name in the keystore to get the user's cert and private key for signature. The next two EndpointProperty statements declares the Java properties file that contains the (Merlin) crypto configuration information. In this case both for signing and encrypting the messages. WSS4J reads this file and extra required information for message handling. The last EndpointProperty statement declares the ServerCallbackHandler implementation class. It is used to obtain the user's password for the certificates in the keystore file.</para> @@ -3427,7 +3814,7 @@ <section id="sid-47972359_WS-TrustandSTS-MANIFEST.MF"> <title>MANIFEST.MF</title> - <para>When deployed on JBoss Application Server this application requires access to the JBossWs and CXF APIs provided in module org.jboss.ws.cxf.jbossws-cxf-client. The dependency statement directs the server to provide them at deployment.</para> + <para>When deployed on WildFly this application requires access to the JBossWs and CXF APIs provided in module org.jboss.ws.cxf.jbossws-cxf-client. The dependency statement directs the server to provide them at deployment.</para> <informalexample> <programlisting> Manifest-Version: 1.0   @@ -4001,7 +4388,7 @@ <title>MANIFEST.MF</title> <para> - When deployed on JBoss Application Server, this application requires access to the JBossWs and CXF APIs provided in modules org.jboss.ws.cxf.jbossws-cxf-client and org.apache.cxf. The Apache CXF internals, org.apache.cxf.impl, are needed to build the STS configuration in the + When deployed on WildFly, this application requires access to the JBossWs and CXF APIs provided in modules org.jboss.ws.cxf.jbossws-cxf-client and org.apache.cxf. The Apache CXF internals, org.apache.cxf.impl, are needed to build the STS configuration in the <code>SampleSTS</code> constructor. The dependency statement directs the server to provide them at deployment. </para> @@ -4017,19 +4404,31 @@ <section id="sid-47972359_WS-TrustandSTS-SecurityDomain"> <title>Security Domain</title> + <para>The STS requires a JBoss security domain be configured. The jboss-web.xml descriptor declares a named security domain,"JBossWS-trust-sts" to be used by this service for authentication. This security domain requires two properties files and the addition of a security-domain declaration in the JBoss server configuration file.</para> <para> - The - <emphasis role="italics">jboss-web.xml</emphasis> - descriptor is used to set the security domain to be used for authentication. For this scenario the domain will need to contain user - <emphasis role="italics">alice,</emphasis> - password - <emphasis role="italics">clarinet,</emphasis> - and role + For this scenario the domain needs to contain user + <emphasis role="italics">alice</emphasis> + , password + <emphasis role="italics">clarinet</emphasis> + , and role <emphasis role="italics">friend</emphasis> - . See the listings for jbossws-users.properties and jbossws-roles.properties. In addition the JBoss Application Server needs to be configured with the domain name, "JBossWS-trust-sts", and with the users and roles properties files. See the directions in this - <ulink url="http://middlewaremagic.com/jboss/?p=2049">article</u... - about configuring the security domain using the CLI. + . See the listings below for jbossws-users.properties and jbossws-roles.properties. In addition the following XML must be added to the JBoss security subsystem in the server configuration file. Replace " + <emphasis role="strong">SOME_PATH</emphasis> + " with appropriate information. </para> + <informalexample> + <programlisting> + &lt;security-domain name="JBossWS-trust-sts"&gt; +  &lt;authentication&gt; +    &lt;login-module code="UsersRoles" flag="required"&gt; +      &lt;module-option name="usersProperties" value="/SOME_PATH/jbossws-users.properties"/&gt; +      &lt;module-option name="unauthenticatedIdentity" value="anonymous"/&gt; +      &lt;module-option name="rolesProperties" value="/SOME_PATH/jbossws-roles.properties"/&gt; +    &lt;/login-module&gt; +  &lt;/authentication&gt; +&lt;/security-domain&gt; +</programlisting> + </informalexample> <para>jboss-web.xml</para> <informalexample> <programlisting> @@ -4176,7 +4575,7 @@ <section id="sid-47972359_WS-TrustandSTS-ClientCallbackHandler"> <title>ClientCallbackHandler</title> - <para>ClientCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature. Note that "alice" and her password have been provided here. This information is not in the (JKS) keystore but provided in the JBoss Application Server security domain. It was declared in file jbossws-users.properties.</para> + <para>ClientCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature. Note that "alice" and her password have been provided here. This information is not in the (JKS) keystore but provided in the WildFly security domain. It was declared in file jbossws-users.properties.</para> <informalexample> <programlisting> package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared;   @@ -4208,9 +4607,9 @@ </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-Cryptopropertiesandkeystorefilesxx"> + <section id="sid-47972359_WS-TrustandSTS-RequesterCryptopropertiesandkeystorefiles"> - <title>Crypto properties and keystore files</title> + <title>Requester Crypto properties and keystore files</title> <para> WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data. The file contains implementation-specific properties such as a keystore location, password, default alias and the like. This application is using the Merlin implementation. File clientKeystore.properties contains this information. @@ -4506,7 +4905,7 @@ &lt;/PicketLinkSTS&gt; </programlisting> </informalexample> - <para>Finally, the PicketLink alternative approach of course requires different JBoss AS module dependencies to be declared in the MANIFEST.MF:</para> + <para>Finally, the PicketLink alternative approach of course requires different WildFly module dependencies to be declared in the MANIFEST.MF:</para> <informalexample> <programlisting> Manifest-Version: 1.0 @@ -4543,134 +4942,134 @@ </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-ActAsWSTrustScenario"> + </section> + <section id="sid-78711224"> + + <title>ActAs WS-Trust Scenario</title> + <para> + The ActAs feature is used in scenarios that require composite delegation. It is commonly used in multi-tiered systems where an application calls a service on behalf of a logged in user or a service calls another service on behalf of the original caller. - <title>ActAs WS-Trust Scenario</title> - <para> - The ActAs feature is used in scenarios that require composite delegation. It is commonly used in multi-tiered systems where an application calls a service on behalf of a logged in user or a service calls another service on behalf of the original caller. + </para> + <para> + ActAs is nothing more than a new sub-element in the RequestSecurityToken (RST). It provides additional information about the original caller when a token is negotiated with the STS. The ActAs element usually takes the form of a token with identity claims such as name, role, and authorization code, for the client to access the service. + + </para> + <para> + The ActAs scenario is an extension of + <link linkend="sid-78711224">the basic WS-Trust scenario</link> + . In this example the ActAs service calls the ws-service on behalf of a user. There are only a couple of additions to the basic scenario's code. An ActAs web service provider and callback handler have been added. The ActAs web services' WSDL imposes the same security policies as the ws-provider. UsernameTokenCallbackHandler is new. It is a utility that generates the content for the ActAs element. And lastly there are a couple of code additions in the STS to support the ActAs request. + </para> + <section id="sid-78711224_ActAsWS-TrustScenario-Webserviceprovider"> + + <title>Web service provider</title> + <para>This section examines the web service elements from the basic WS-Trust scenario that have been changed to address the needs of the ActAs example. The components are</para> + <itemizedlist> + <listitem> + <para>ActAs web service provider's WSDL</para> + </listitem> + <listitem> + <para>ActAs web service provider's Interface and Implementation classes.</para> + </listitem> + <listitem> + <para>ActAsCallbackHandler class</para> + </listitem> + <listitem> + <para>UsernameTokenCallbackHandler</para> + </listitem> + <listitem> + <para>Crypto properties and keystore files</para> + </listitem> + <listitem> + <para>MANIFEST.MF</para> + </listitem> + </itemizedlist> + <section id="sid-78711224_ActAsWS-TrustScenario-WebserviceproviderWSDL"> - </para> - <para> - ActAs is nothing more than a new sub-element in the RequestSecurityToken (RST). It provides additional information about the original caller when a token is negotiated with the STS. The ActAs element usually takes the form of a token with identity claims such as name, role, and authorization code, for the client to access the service. - - </para> - <para> - The ActAs scenario is an extension of - <link linkend="sid-47972359_WS-TrustandSTS-ABasicWSTrustScenario">the basic WS-Trust scenario</link> - . In this example the ActAs service calls the ws-service on behalf of a user. There are only a couple of additions to the basic scenario's code. An ActAs web service provider and callback handler have been added. The ActAs web services' WSDL imposes the same security policies as the ws-provider. UsernameTokenCallbackHandler is new. It is a utility that generates the content for the ActAs element. And lastly there are a couple of code additions in the STS to support the ActAs request. - </para> - <section id="sid-47972359_WS-TrustandSTS-ActAsWebserviceprovider"> - - <title>ActAs Web service provider</title> - <para>This section examines the web service elements from the basic WS-Trust scenario that have been changed to address the needs of the ActAs example. The components are</para> - <itemizedlist> - <listitem> - <para>ActAs web service provider's WSDL</para> - </listitem> - <listitem> - <para>ActAs web service provider's Interface and Implementation classes.</para> - </listitem> - <listitem> - <para>ActAsCallbackHandler class</para> - </listitem> - <listitem> - <para>UsernameTokenCallbackHandler</para> - </listitem> - <listitem> - <para>Crypto properties and keystore files</para> - </listitem> - <listitem> - <para>MANIFEST.MF</para> - </listitem> - </itemizedlist> - </section> - <section id="sid-47972359_WS-TrustandSTS-ActAsWebserviceproviderWSDL"> - - <title>ActAs Web service provider WSDL</title> + <title>Web service provider WSDL</title> <para>The ActAs web service provider's WSDL is a clone of the ws-provider's WSDL. The wsp:Policy section is the same. There are changes to the service endpoint, targetNamespace, portType, binding name, and service.</para> <informalexample> <programlisting> &lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&gt; &lt;definitions targetNamespace="http://www.jboss.org/jbossws/ws-extensions/actaswss... name="ActAsService" -             xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/actaswssecurit... -             xmlns:xsd="http://www.w3.org/2001/XMLSchema" -             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" -             xmlns="http://schemas.xmlsoap.org/wsdl/" -             xmlns:wsp="http://www.w3.org/ns/ws-policy" -             xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" -             xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... -             xmlns:wsaws="http://www.w3.org/2005/08/addressing" -             xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... -             xmlns:t="http://docs.oasis-open.org/ws-sx/ws-trust/200512"&gt; -    &lt;types&gt; -        &lt;xsd:schema&gt; -            &lt;xsd:import namespace="http://www.jboss.org/jbossws/ws-extensions/actaswssecurit... -                    schemaLocation="ActAsService_schema1.xsd"/&gt; -        &lt;/xsd:schema&gt; -    &lt;/types&gt; -    &lt;message name="sayHello"&gt; -        &lt;part name="parameters" element="tns:sayHello"/&gt; -    &lt;/message&gt; -    &lt;message name="sayHelloResponse"&gt; -        &lt;part name="parameters" element="tns:sayHelloResponse"/&gt; -    &lt;/message&gt; -    &lt;portType name="ActAsServiceIface"&gt; -        &lt;operation name="sayHello"&gt; -            &lt;input message="tns:sayHello"/&gt; -            &lt;output message="tns:sayHelloResponse"/&gt; -        &lt;/operation&gt; -    &lt;/portType&gt; -    &lt;binding name="ActAsServicePortBinding" type="tns:ActAsServiceIface"&gt; -        &lt;wsp:PolicyReference URI="#AsymmetricSAML2Policy" /&gt; -        &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt; -        &lt;operation name="sayHello"&gt; -            &lt;soap:operation soapAction=""/&gt; -            &lt;input&gt; -                &lt;soap:body use="literal"/&gt; -                &lt;wsp:PolicyReference URI="#Input_Policy" /&gt; -            &lt;/input&gt; -            &lt;output&gt; -                &lt;soap:body use="literal"/&gt; -                &lt;wsp:PolicyReference URI="#Output_Policy" /&gt; -            &lt;/output&gt; -        &lt;/operation&gt; -    &lt;/binding&gt; -    &lt;service name="ActAsService"&gt; -        &lt;port name="ActAsServicePort" binding="tns:ActAsServicePortBinding"&gt; -            &lt;soap:address location="http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-actas/ActAsService"/&gt; -        &lt;/port&gt; -    &lt;/service&gt; + xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/actaswssecurit... + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns="http://schemas.xmlsoap.org/wsdl/" + xmlns:wsp="http://www.w3.org/ns/ws-policy" + xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" + xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... + xmlns:wsaws="http://www.w3.org/2005/08/addressing" + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + xmlns:t="http://docs.oasis-open.org/ws-sx/ws-trust/200512"&gt; + &lt;types&gt; + &lt;xsd:schema&gt; + &lt;xsd:import namespace="http://www.jboss.org/jbossws/ws-extensions/actaswssecurit... + schemaLocation="ActAsService_schema1.xsd"/&gt; + &lt;/xsd:schema&gt; + &lt;/types&gt; + &lt;message name="sayHello"&gt; + &lt;part name="parameters" element="tns:sayHello"/&gt; + &lt;/message&gt; + &lt;message name="sayHelloResponse"&gt; + &lt;part name="parameters" element="tns:sayHelloResponse"/&gt; + &lt;/message&gt; + &lt;portType name="ActAsServiceIface"&gt; + &lt;operation name="sayHello"&gt; + &lt;input message="tns:sayHello"/&gt; + &lt;output message="tns:sayHelloResponse"/&gt; + &lt;/operation&gt; + &lt;/portType&gt; + &lt;binding name="ActAsServicePortBinding" type="tns:ActAsServiceIface"&gt; + &lt;wsp:PolicyReference URI="#AsymmetricSAML2Policy" /&gt; + &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt; + &lt;operation name="sayHello"&gt; + &lt;soap:operation soapAction=""/&gt; + &lt;input&gt; + &lt;soap:body use="literal"/&gt; + &lt;wsp:PolicyReference URI="#Input_Policy" /&gt; + &lt;/input&gt; + &lt;output&gt; + &lt;soap:body use="literal"/&gt; + &lt;wsp:PolicyReference URI="#Output_Policy" /&gt; + &lt;/output&gt; + &lt;/operation&gt; + &lt;/binding&gt; + &lt;service name="ActAsService"&gt; + &lt;port name="ActAsServicePort" binding="tns:ActAsServicePortBinding"&gt; + &lt;soap:address location="http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-actas/ActAsService"/&gt; + &lt;/port&gt; + &lt;/service&gt; &lt;/definitions&gt; </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-ActAsWebServiceInterface"> + <section id="sid-78711224_ActAsWS-TrustScenario-WebServiceInterface"> - <title>ActAs Web Service Interface</title> + <title>Web Service Interface</title> <para>The web service provider interface class, ActAsServiceIface, is a simple web service definition.</para> <informalexample> <programlisting> -package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas;   -  -import javax.jws.WebMethod;   -import javax.jws.WebService;   -  -@WebService   -(   -   targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/actaswssecuritypolicy"   -)   -public interface ActAsServiceIface   -{   -   @WebMethod   -   String sayHello();   +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas; + +import javax.jws.WebMethod; +import javax.jws.WebService; + +@WebService +( + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/actaswssecuritypolicy" +) +public interface ActAsServiceIface +{ + @WebMethod + String sayHello(); } </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-ActAsWebServiceImplementation"> + <section id="sid-78711224_ActAsWS-TrustScenario-WebServiceImplementation"> - <title>ActAs Web Service Implementation</title> + <title>Web Service Implementation</title> <para> The web service provider implementation class, ActAsServiceImpl, is a simple POJO. It uses the standard WebService annotation to define the service endpoint and two Apache WSS4J annotations, EndpointProperties and EndpointProperty used for configuring the endpoint for the CXF runtime. The WSS4J configuration information provided is for WSS4J's Crypto Merlin implementation. @@ -4678,129 +5077,129 @@ <para>ActAsServiceImpl is calling ServiceImpl acting on behalf of the user. Method setupService performs the requisite configuration setup.</para> <informalexample> <programlisting> -package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas;   -  -import org.apache.cxf.Bus;   -import org.apache.cxf.BusFactory;   -import org.apache.cxf.annotations.EndpointProperties;   -import org.apache.cxf.annotations.EndpointProperty;   -import org.apache.cxf.ws.security.SecurityConstants;   -import org.apache.cxf.ws.security.trust.STSClient;   -import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.service.ServiceIface;   -import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared.WSTrustAppUtils;   -  -import javax.jws.WebService;   -import javax.xml.namespace.QName;   -import javax.xml.ws.BindingProvider;   -import javax.xml.ws.Service;   -import java.net.MalformedURLException;   -import java.net.URL;   -import java.util.Map;   -  -@WebService   -(   -   portName = "ActAsServicePort",   -   serviceName = "ActAsService",   -   wsdlLocation = "WEB-INF/wsdl/ActAsService.wsdl",   -   targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/actaswssecuritypolicy",   -   endpointInterface = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas.ActAsServiceIface"   -)   -  -@EndpointProperties(value = {   -      @EndpointProperty(key = "ws-security.signature.username", value = "myactaskey"),   -      @EndpointProperty(key = "ws-security.signature.properties", value =  "actasKeystore.properties"),   -      @EndpointProperty(key = "ws-security.encryption.properties", value = "actasKeystore.properties"),   -      @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas.ActAsCallbackHandler")   -})   -  -public class ActAsServiceImpl implements ActAsServiceIface   -{   -   public String sayHello() {   -      try {   -         ServiceIface proxy = setupService();   -         return "ActAs " + proxy.sayHello();   -      } catch (MalformedURLException e) {   -         e.printStackTrace();   -      }   -      return null;   -   }   -  -   private  ServiceIface setupService()throws MalformedURLException {   -      ServiceIface proxy = null;   -      Bus bus = BusFactory.newInstance().createBus();   -  -      try {   -         BusFactory.setThreadDefaultBus(bus);   -  -         final String serviceURL = "http://" + WSTrustAppUtils.getServerHost() + ":8080/jaxws-samples-wsse-policy-trust/SecurityService";   -         final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy";, "SecurityService");   -         final URL wsdlURL = new URL(serviceURL + "?wsdl");   -         Service service = Service.create(wsdlURL, serviceName);   -         proxy = (ServiceIface) service.getPort(ServiceIface.class);   -  -         Map&lt;String, Object&gt; ctx = ((BindingProvider) proxy).getRequestContext();   -         ctx.put(SecurityConstants.CALLBACK_HANDLER, new ActAsCallbackHandler());   -  -         ctx.put(SecurityConstants.SIGNATURE_PROPERTIES,   -            Thread.currentThread().getContextClassLoader().getResource("actasKeystore.properties" ));   -         ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myactaskey" );   -         ctx.put(SecurityConstants.ENCRYPT_PROPERTIES,   -            Thread.currentThread().getContextClassLoader().getResource("../../META-INF/clientKeystore.properties" ));   -         ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myservicekey");   -  -         STSClient stsClient = new STSClient(bus);   -         Map&lt;String, Object&gt; props = stsClient.getProperties();   -         props.put(SecurityConstants.USERNAME, "alice");   -         props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey");   -         props.put(SecurityConstants.STS_TOKEN_USERNAME, "myactaskey" );   -         props.put(SecurityConstants.STS_TOKEN_PROPERTIES,   -            Thread.currentThread().getContextClassLoader().getResource("actasKeystore.properties" ));   -         props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true");   -  -         ctx.put(SecurityConstants.STS_CLIENT, stsClient);   -  -      } finally {   -         bus.shutdown(true);   -      }   -  -      return proxy;   -   }   -  +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas; + +import org.apache.cxf.Bus; +import org.apache.cxf.BusFactory; +import org.apache.cxf.annotations.EndpointProperties; +import org.apache.cxf.annotations.EndpointProperty; +import org.apache.cxf.ws.security.SecurityConstants; +import org.apache.cxf.ws.security.trust.STSClient; +import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.service.ServiceIface; +import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared.WSTrustAppUtils; + +import javax.jws.WebService; +import javax.xml.namespace.QName; +import javax.xml.ws.BindingProvider; +import javax.xml.ws.Service; +import java.net.MalformedURLException; +import java.net.URL; +import java.util.Map; + +@WebService +( + portName = "ActAsServicePort", + serviceName = "ActAsService", + wsdlLocation = "WEB-INF/wsdl/ActAsService.wsdl", + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/actaswssecuritypolicy", + endpointInterface = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas.ActAsServiceIface" +) + +@EndpointProperties(value = { + @EndpointProperty(key = "ws-security.signature.username", value = "myactaskey"), + @EndpointProperty(key = "ws-security.signature.properties", value = "actasKeystore.properties"), + @EndpointProperty(key = "ws-security.encryption.properties", value = "actasKeystore.properties"), + @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas.ActAsCallbackHandler") +}) + +public class ActAsServiceImpl implements ActAsServiceIface +{ + public String sayHello() { + try { + ServiceIface proxy = setupService(); + return "ActAs " + proxy.sayHello(); + } catch (MalformedURLException e) { + e.printStackTrace(); + } + return null; + } + + private ServiceIface setupService()throws MalformedURLException { + ServiceIface proxy = null; + Bus bus = BusFactory.newInstance().createBus(); + + try { + BusFactory.setThreadDefaultBus(bus); + + final String serviceURL = "http://" + WSTrustAppUtils.getServerHost() + ":8080/jaxws-samples-wsse-policy-trust/SecurityService"; + final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy";, "SecurityService"); + final URL wsdlURL = new URL(serviceURL + "?wsdl"); + Service service = Service.create(wsdlURL, serviceName); + proxy = (ServiceIface) service.getPort(ServiceIface.class); + + Map&lt;String, Object&gt; ctx = ((BindingProvider) proxy).getRequestContext(); + ctx.put(SecurityConstants.CALLBACK_HANDLER, new ActAsCallbackHandler()); + + ctx.put(SecurityConstants.SIGNATURE_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource("actasKeystore.properties" )); + ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myactaskey" ); + ctx.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource("../../META-INF/clientKeystore.properties" )); + ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myservicekey"); + + STSClient stsClient = new STSClient(bus); + Map&lt;String, Object&gt; props = stsClient.getProperties(); + props.put(SecurityConstants.USERNAME, "alice"); + props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey"); + props.put(SecurityConstants.STS_TOKEN_USERNAME, "myactaskey" ); + props.put(SecurityConstants.STS_TOKEN_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource("actasKeystore.properties" )); + props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true"); + + ctx.put(SecurityConstants.STS_CLIENT, stsClient); + + } finally { + bus.shutdown(true); + } + + return proxy; + } + } </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-ActAsCallbackHandler"> + <section id="sid-78711224_ActAsWS-TrustScenario-ActAsCallbackHandler"> <title>ActAsCallbackHandler</title> <para>ActAsCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature. This class has been revised to return the passwords for this service, myactaskey and the "actas" user, alice.</para> <informalexample> <programlisting> -package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas;   -  -import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler;   -import java.util.HashMap;   -import java.util.Map;   -  -public class ActAsCallbackHandler extends PasswordCallbackHandler {   -  -   public ActAsCallbackHandler()   -   {   -      super(getInitMap());   -   }   -  -   private static Map&lt;String, String&gt; getInitMap()   -   {   -      Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;();   -      passwords.put("myactaskey", "aspass");   -      passwords.put("alice", "clarinet");   -      return passwords;   -   }   +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.actas; + +import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler; +import java.util.HashMap; +import java.util.Map; + +public class ActAsCallbackHandler extends PasswordCallbackHandler { + + public ActAsCallbackHandler() + { + super(getInitMap()); + } + + private static Map&lt;String, String&gt; getInitMap() + { + Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;(); + passwords.put("myactaskey", "aspass"); + passwords.put("alice", "clarinet"); + return passwords; + } } </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-UsernameTokenCallbackHandler"> + <section id="sid-78711224_ActAsWS-TrustScenario-UsernameTokenCallbackHandler"> <title>UsernameTokenCallbackHandler</title> <para> @@ -4808,168 +5207,168 @@ </para> <informalexample> <programlisting> -package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared;   -  -import org.apache.cxf.helpers.DOMUtils;   -import org.apache.cxf.message.Message;   -import org.apache.cxf.ws.security.SecurityConstants;   -import org.apache.cxf.ws.security.trust.delegation.DelegationCallback;   -import org.apache.ws.security.WSConstants;   -import org.apache.ws.security.message.token.UsernameToken;   -import org.w3c.dom.Document;   -import org.w3c.dom.Node;   -import org.w3c.dom.Element;   -import org.w3c.dom.ls.DOMImplementationLS;   -import org.w3c.dom.ls.LSSerializer;   -  -import javax.security.auth.callback.Callback;   -import javax.security.auth.callback.CallbackHandler;   -import javax.security.auth.callback.UnsupportedCallbackException;   -import java.io.IOException;   -import java.util.Map;   -  +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared; + +import org.apache.cxf.helpers.DOMUtils; +import org.apache.cxf.message.Message; +import org.apache.cxf.ws.security.SecurityConstants; +import org.apache.cxf.ws.security.trust.delegation.DelegationCallback; +import org.apache.ws.security.WSConstants; +import org.apache.ws.security.message.token.UsernameToken; +import org.w3c.dom.Document; +import org.w3c.dom.Node; +import org.w3c.dom.Element; +import org.w3c.dom.ls.DOMImplementationLS; +import org.w3c.dom.ls.LSSerializer; + +import javax.security.auth.callback.Callback; +import javax.security.auth.callback.CallbackHandler; +import javax.security.auth.callback.UnsupportedCallbackException; +import java.io.IOException; +import java.util.Map; + /** * A utility to provide the 3 different input parameter types for jaxws property * "ws-security.sts.token.act-as" and "ws-security.sts.token.on-behalf-of". * This implementation obtains a username and password via the jaxws property * "ws-security.username" and "ws-security.password" respectively, as defined -* in SecurityConstants.  It creates a wss UsernameToken to be used as the +* in SecurityConstants. It creates a wss UsernameToken to be used as the * delegation token. -*/   -  -public class UsernameTokenCallbackHandler implements CallbackHandler {   -  -   public void handle(Callback[] callbacks)   -      throws IOException, UnsupportedCallbackException {   -      for (int i = 0; i &lt; callbacks.length; i++) {   -         if (callbacks[i] instanceof DelegationCallback) {   -            DelegationCallback callback = (DelegationCallback) callbacks[i];   -            Message message = callback.getCurrentMessage();   -  -            String username =   -               (String)message.getContextualProperty(SecurityConstants.USERNAME);   -            String password =   -               (String)message.getContextualProperty(SecurityConstants.PASSWORD);   -            if (username != null) {   -               Node contentNode = message.getContent(Node.class);   -               Document doc = null;   -               if (contentNode != null) {   -                  doc = contentNode.getOwnerDocument();   -               } else {   -                  doc = DOMUtils.createDocument();   -               }   -               UsernameToken usernameToken = createWSSEUsernameToken(username,password, doc);   -               callback.setToken(usernameToken.getElement());   -            }   -         } else {   -            throw new UnsupportedCallbackException(callbacks[i], "Unrecognized Callback");   -         }   -      }   -   }   -  -   /** -    * Provide UsernameToken as a string. -    * @param ctx -    * @return -    */   -   public String getUsernameTokenString(Map&lt;String, Object&gt; ctx){   -      Document doc = DOMUtils.createDocument();   -      String result = null;   -      String username = (String)ctx.get(SecurityConstants.USERNAME);   -      String password = (String)ctx.get(SecurityConstants.PASSWORD);   -      if (username != null) {   -         UsernameToken usernameToken = createWSSEUsernameToken(username,password, doc);   -         result = toString(usernameToken.getElement().getFirstChild().getParentNode());   -      }   -      return result;   -   }   -  -   /** -    * -    * @param username -    * @param password -    * @return -    */   -   public String getUsernameTokenString(String username, String password){   -      Document doc = DOMUtils.createDocument();   -      String result = null;   -      if (username != null) {   -         UsernameToken usernameToken = createWSSEUsernameToken(username,password, doc);   -         result = toString(usernameToken.getElement().getFirstChild().getParentNode());   -      }   -      return result;   -   }   -  -   /** -    * Provide UsernameToken as a DOM Element. -    * @param ctx -    * @return -    */   -   public Element getUsernameTokenElement(Map&lt;String, Object&gt; ctx){   -      Document doc = DOMUtils.createDocument();   -      Element result = null;   -      UsernameToken usernameToken = null;   -         String username = (String)ctx.get(SecurityConstants.USERNAME);   -      String password = (String)ctx.get(SecurityConstants.PASSWORD);   -      if (username != null) {   -         usernameToken = createWSSEUsernameToken(username,password, doc);   -         result = usernameToken.getElement();   -      }   -      return result;   -   }   -  -   /** -    * -    * @param username -    * @param password -    * @return -    */   -   public Element getUsernameTokenElement(String username, String password){   -      Document doc = DOMUtils.createDocument();   -      Element result = null;   -      UsernameToken usernameToken = null;   -      if (username != null) {   -         usernameToken = createWSSEUsernameToken(username,password, doc);   -         result = usernameToken.getElement();   -      }   -      return result;   -   }   -  -   private UsernameToken createWSSEUsernameToken(String username, String password, Document doc) {   -  -      UsernameToken usernameToken = new UsernameToken(true, doc,   -         (password == null)? null: WSConstants.PASSWORD_TEXT);   -      usernameToken.setName(username);   -      usernameToken.addWSUNamespace();   -      usernameToken.addWSSENamespace();   -      usernameToken.setID("id-" + username);   -  -      if (password != null){   -         usernameToken.setPassword(password);   -      }   -  -      return usernameToken;   -   }   -  -  -   private String toString(Node node) {   -      String str = null;   -  -      if (node != null) {   -         DOMImplementationLS lsImpl = (DOMImplementationLS)   -            node.getOwnerDocument().getImplementation().getFeature("LS", "3.0");   -         LSSerializer serializer = lsImpl.createLSSerializer();   -         serializer.getDomConfig().setParameter("xml-declaration", false); //by default its true, so set it to false to get String without xml-declaration   -         str = serializer.writeToString(node);   -      }   -      return str;   -   }   -  +*/ + +public class UsernameTokenCallbackHandler implements CallbackHandler { + + public void handle(Callback[] callbacks) + throws IOException, UnsupportedCallbackException { + for (int i = 0; i &lt; callbacks.length; i++) { + if (callbacks[i] instanceof DelegationCallback) { + DelegationCallback callback = (DelegationCallback) callbacks[i]; + Message message = callback.getCurrentMessage(); + + String username = + (String)message.getContextualProperty(SecurityConstants.USERNAME); + String password = + (String)message.getContextualProperty(SecurityConstants.PASSWORD); + if (username != null) { + Node contentNode = message.getContent(Node.class); + Document doc = null; + if (contentNode != null) { + doc = contentNode.getOwnerDocument(); + } else { + doc = DOMUtils.createDocument(); + } + UsernameToken usernameToken = createWSSEUsernameToken(username,password, doc); + callback.setToken(usernameToken.getElement()); + } + } else { + throw new UnsupportedCallbackException(callbacks[i], "Unrecognized Callback"); + } + } + } + + /** + * Provide UsernameToken as a string. + * @param ctx + * @return + */ + public String getUsernameTokenString(Map&lt;String, Object&gt; ctx){ + Document doc = DOMUtils.createDocument(); + String result = null; + String username = (String)ctx.get(SecurityConstants.USERNAME); + String password = (String)ctx.get(SecurityConstants.PASSWORD); + if (username != null) { + UsernameToken usernameToken = createWSSEUsernameToken(username,password, doc); + result = toString(usernameToken.getElement().getFirstChild().getParentNode()); + } + return result; + } + + /** + * + * @param username + * @param password + * @return + */ + public String getUsernameTokenString(String username, String password){ + Document doc = DOMUtils.createDocument(); + String result = null; + if (username != null) { + UsernameToken usernameToken = createWSSEUsernameToken(username,password, doc); + result = toString(usernameToken.getElement().getFirstChild().getParentNode()); + } + return result; + } + + /** + * Provide UsernameToken as a DOM Element. + * @param ctx + * @return + */ + public Element getUsernameTokenElement(Map&lt;String, Object&gt; ctx){ + Document doc = DOMUtils.createDocument(); + Element result = null; + UsernameToken usernameToken = null; + String username = (String)ctx.get(SecurityConstants.USERNAME); + String password = (String)ctx.get(SecurityConstants.PASSWORD); + if (username != null) { + usernameToken = createWSSEUsernameToken(username,password, doc); + result = usernameToken.getElement(); + } + return result; + } + + /** + * + * @param username + * @param password + * @return + */ + public Element getUsernameTokenElement(String username, String password){ + Document doc = DOMUtils.createDocument(); + Element result = null; + UsernameToken usernameToken = null; + if (username != null) { + usernameToken = createWSSEUsernameToken(username,password, doc); + result = usernameToken.getElement(); + } + return result; + } + + private UsernameToken createWSSEUsernameToken(String username, String password, Document doc) { + + UsernameToken usernameToken = new UsernameToken(true, doc, + (password == null)? null: WSConstants.PASSWORD_TEXT); + usernameToken.setName(username); + usernameToken.addWSUNamespace(); + usernameToken.addWSSENamespace(); + usernameToken.setID("id-" + username); + + if (password != null){ + usernameToken.setPassword(password); + } + + return usernameToken; + } + + + private String toString(Node node) { + String str = null; + + if (node != null) { + DOMImplementationLS lsImpl = (DOMImplementationLS) + node.getOwnerDocument().getImplementation().getFeature("LS", "3.0"); + LSSerializer serializer = lsImpl.createLSSerializer(); + serializer.getDomConfig().setParameter("xml-declaration", false); //by default its true, so set it to false to get String without xml-declaration + str = serializer.writeToString(node); + } + return str; + } + } </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-Cryptopropertiesandkeystorefilesxxx"> + <section id="sid-78711224_ActAsWS-TrustScenario-Cryptopropertiesandkeystorefiles"> <title>Crypto properties and keystore files</title> <para> @@ -4977,33 +5376,33 @@ </para> <informalexample> <programlisting> -org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin   -org.apache.ws.security.crypto.merlin.keystore.type=jks   -org.apache.ws.security.crypto.merlin.keystore.password=aapass   -org.apache.ws.security.crypto.merlin.keystore.alias=myactaskey   +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=aapass +org.apache.ws.security.crypto.merlin.keystore.alias=myactaskey org.apache.ws.security.crypto.merlin.keystore.file=actasstore.jks </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-MANIFEST.MFxx"> + <section id="sid-78711224_ActAsWS-TrustScenario-MANIFEST.MF"> <title>MANIFEST.MF</title> <para> - <emphasis role="color:#000000">When deployed on JBoss Application Server this application requires access to the JBossWs and CXF APIs provided in modules org.jboss.ws.cxf.jbossws-cxf-client and org.apache.cxf. The Apache CXF internals, org.apache.cxf.impl, are needed in handling the ActAs and OnBehalfOf extensions. The dependency statement directs the server to provide them at deployment.</emphasis> + <emphasis role="color:#000000">When deployed on WildFly this application requires access to the JBossWs and CXF APIs provided in modules org.jboss.ws.cxf.jbossws-cxf-client and org.apache.cxf. The Apache CXF internals, org.apache.cxf.impl, are needed in handling the ActAs and OnBehalfOf extensions. The dependency statement directs the server to provide them at deployment.</emphasis> </para> <informalexample> <programlisting> -Manifest-Version: 1.0   -Ant-Version: Apache Ant 1.8.2   -Created-By: 1.7.0_25-b15 (Oracle Corporation)   +Manifest-Version: 1.0 +Ant-Version: Apache Ant 1.8.2 +Created-By: 1.7.0_25-b15 (Oracle Corporation) Dependencies: org.jboss.ws.cxf.jbossws-cxf-client, org.apache.cxf.impl </programlisting> </informalexample> </section> </section> - <section id="sid-47972359_WS-TrustandSTS-ActAsSecurityTokenService"> + <section id="sid-78711224_ActAsWS-TrustScenario-SecurityTokenService"> - <title>ActAs Security Token Service</title> + <title>Security Token Service</title> <para>This section examines the STS elements from the basic WS-Trust scenario that have been changed to address the needs of the ActAs example. The components are.</para> <itemizedlist> <listitem> @@ -5013,12 +5412,12 @@ <para>STSCallbackHandler class</para> </listitem> </itemizedlist> - <section id="sid-47972359_WS-TrustandSTS-STSImplementationclass"> + <section id="sid-78711224_ActAsWS-TrustScenario-STSImplementationclass"> <title>STS Implementation class</title> <para> The initial description of SampleSTS can be found - <link linkend="sid-47972359_WS-TrustandSTS-STSImplementation">here</link> + <link linkend="sid-78711224">here</link> . </para> @@ -5029,7 +5428,7 @@ <para>The TokenIssueOperation requires class, UsernameTokenValidator be provided in order to validate the contents of the OnBehalfOf claims and class, UsernameTokenDelegationHandler to be provided in order to process the token delegation request of the ActAs on OnBehalfOf user.</para> <informalexample> <programlisting> - package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.sts; + package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.sts; import java.util.Arrays; import java.util.LinkedList; @@ -5052,499 +5451,2723 @@ import org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider; @WebServiceProvider(serviceName = "SecurityTokenService", -      portName = "UT_Port", -      targetNamespace = "http://docs.oasis-open.org/ws-sx/ws-trust/200512/", -      wsdlLocation = "WEB-INF/wsdl/ws-trust-1.4-service.wsdl") + portName = "UT_Port", + targetNamespace = "http://docs.oasis-open.org/ws-sx/ws-trust/200512/", + wsdlLocation = "WEB-INF/wsdl/ws-trust-1.4-service.wsdl") //be sure to have dependency on org.apache.cxf module when on AS7, otherwise Apache CXF annotations are ignored @EndpointProperties(value = { -      @EndpointProperty(key = "ws-security.signature.username", value = "mystskey"), -      @EndpointProperty(key = "ws-security.signature.properties", value = "stsKeystore.properties"), -      @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.sts.STSCallbackHandler"), -      @EndpointProperty(key = "ws-security.validate.token", value = "false") //to let the JAAS integration deal with validation through the interceptor below + @EndpointProperty(key = "ws-security.signature.username", value = "mystskey"), + @EndpointProperty(key = "ws-security.signature.properties", value = "stsKeystore.properties"), + @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.sts.STSCallbackHandler"), + @EndpointProperty(key = "ws-security.validate.token", value = "false") //to let the JAAS integration deal with validation through the interceptor below }) @InInterceptors(interceptors = {"org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingPolicyInterceptor"}) public class SampleSTS extends SecurityTokenServiceProvider { -   public SampleSTS() throws Exception -   { -      super(); -       -      StaticSTSProperties props = new StaticSTSProperties(); -      props.setSignatureCryptoProperties("stsKeystore.properties"); -      props.setSignatureUsername("mystskey"); -      props.setCallbackHandlerClass(STSCallbackHandler.class.getName()); -      props.setIssuer("DoubleItSTSIssuer"); -       -      List&lt;ServiceMBean&gt; services = new LinkedList&lt;ServiceMBean&gt;(); -      StaticService service = new StaticService(); -      service.setEndpoints(Arrays.asList( -         "http://localhost:(\\d)*/jaxws-samples-wsse-policy-trust/SecurityService", -         "http://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust/SecurityService", -         "http://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust/SecurityService", + public SampleSTS() throws Exception + { + super(); -         "http://localhost:(\\d)*/jaxws-samples-wsse-policy-trust-actas/ActAsService", -         "http://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-actas/ActAsService", -         "http://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-actas/ActAsService", + StaticSTSProperties props = new StaticSTSProperties(); + props.setSignatureCryptoProperties("stsKeystore.properties"); + props.setSignatureUsername("mystskey"); + props.setCallbackHandlerClass(STSCallbackHandler.class.getName()); + props.setIssuer("DoubleItSTSIssuer"); -         "http://localhost:(\\d)*/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService", -         "http://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService", -         "http://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService" -      )); -      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); -   } + List&lt;ServiceMBean&gt; services = new LinkedList&lt;ServiceMBean&gt;(); + StaticService service = new StaticService(); + service.setEndpoints(Arrays.asList( + "http://localhost:(\\d)*/jaxws-samples-wsse-policy-trust/SecurityService", + "http://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust/SecurityService", + "http://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust/SecurityService", + + "http://localhost:(\\d)*/jaxws-samples-wsse-policy-trust-actas/ActAsService", + "http://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-actas/ActAsService", + "http://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-actas/ActAsService", + + "http://localhost:(\\d)*/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService", + "http://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService", + "http://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService" + )); + 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); + } } </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-STSCallbackHandlerx"> + <section id="sid-78711224_ActAsWS-TrustScenario-STSCallbackHandler"> <title>STSCallbackHandler</title> <para>The user, alice, and corresponding password was required to be added for the ActAs example.</para> <informalexample> <programlisting> -package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.sts;   -  -import java.util.HashMap;   -import java.util.Map;   -  -import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler;   -  -public class STSCallbackHandler extends PasswordCallbackHandler   -{   -   public STSCallbackHandler()   -   {   -      super(getInitMap());   -   }   -  -   private static Map&lt;String, String&gt; getInitMap()   -   {   -      Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;();   -      passwords.put("mystskey", "stskpass");   -      passwords.put("alice", "clarinet");   -      return passwords;   -   }   +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.sts; + +import java.util.HashMap; +import java.util.Map; + +import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler; + +public class STSCallbackHandler extends PasswordCallbackHandler +{ + public STSCallbackHandler() + { + super(getInitMap()); + } + + private static Map&lt;String, String&gt; getInitMap() + { + Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;(); + passwords.put("mystskey", "stskpass"); + passwords.put("alice", "clarinet"); + return passwords; + } } </programlisting> </informalexample> </section> </section> - <section id="sid-47972359_WS-TrustandSTS-ActAsWebservicerequester"> + <section id="sid-78711224_ActAsWS-TrustScenario-Webservicerequester"> - <title>ActAs Web service requester</title> + <title>Web service requester</title> <para>This section examines the ws-requester elements from the basic WS-Trust scenario that have been changed to address the needs of the ActAs example. The component is</para> <itemizedlist> <listitem> <para>ActAs web service requester implementation class</para> </listitem> </itemizedlist> - <section id="sid-47972359_WS-TrustandSTS-ActAsWebservicerequesterImplementation"> + <section id="sid-78711224_ActAsWS-TrustScenario-WebservicerequesterImplementation"> - <title>ActAs Web service requester Implementation</title> - <para>The ActAs ws-requester, the client, uses standard procedures for creating a reference to the web service in the first four lines. To address the endpoint security requirements, the web service's "Request Context" is configured via the BindingProvider. Information needed in the message generation is provided through it. The ActAs user, myactaskey, is declared in this section and UsernameTokenCallbackHandler is used to provide the contents of the ActAs element to the STSClient. In this example a STSClient object is created and provided to the proxy's request context. The alternative is to provide keys tagged with the ".it" suffix as was done in [the Basic Scenario client|../../../../../../../../../../../#WS-TrustandSTS-WebservicerequesterImplementation||||\||]. The use of ActAs is configured through the props map using the SecurityConstants.STS_TOKEN_ACT_AS key. The alternative is to use the STSClient.setActAs method.</para> + <title>Web service requester Implementation</title> + <para> + The ActAs ws-requester, the client, uses standard procedures for creating a reference to the web service in the first four lines. To address the endpoint security requirements, the web service's "Request Context" is configured via the BindingProvider. Information needed in the message generation is provided through it. The ActAs user, myactaskey, is declared in this section and UsernameTokenCallbackHandler is used to provide the contents of the ActAs element to the STSClient. In this example a STSClient object is created and provided to the proxy's request context. The alternative is to provide keys tagged with the ".it" suffix as was done in + <ulink url="https://docs.jboss.org/author/display/JBWS/WS-Trust+and+STS#WS-... Basic Scenario client</ulink> + . The use of ActAs is configured through the props map using the SecurityConstants.STS_TOKEN_ACT_AS key. The alternative is to use the STSClient.setActAs method. + </para> <informalexample> <programlisting> - final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/actaswssecuritypol...;, "ActAsService");   -final URL wsdlURL = new URL(serviceURL + "?wsdl");   -Service service = Service.create(wsdlURL, serviceName);   -ActAsServiceIface proxy = (ActAsServiceIface) service.getPort(ActAsServiceIface.class);   -  -Bus bus = BusFactory.newInstance().createBus();   -try {   -    BusFactory.setThreadDefaultBus(bus);   -  -    Map&lt;String, Object&gt; ctx = proxy.getRequestContext();   -  -    ctx.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler());   -    ctx.put(SecurityConstants.ENCRYPT_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myactaskey");   -    ctx.put(SecurityConstants.SIGNATURE_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myclientkey");   -  + final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/actaswssecuritypol...;, "ActAsService"); +final URL wsdlURL = new URL(serviceURL + "?wsdl"); +Service service = Service.create(wsdlURL, serviceName); +ActAsServiceIface proxy = (ActAsServiceIface) service.getPort(ActAsServiceIface.class); + +Bus bus = BusFactory.newInstance().createBus(); +try { + BusFactory.setThreadDefaultBus(bus); + + Map&lt;String, Object&gt; ctx = proxy.getRequestContext(); + + ctx.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler()); + ctx.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myactaskey"); + ctx.put(SecurityConstants.SIGNATURE_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myclientkey"); + // Generate the ActAs element contents and pass to the STSClient as a string -    UsernameTokenCallbackHandler ch = new UsernameTokenCallbackHandler();   -    String str = ch.getUsernameTokenString("myactaskey", null);   -    ctx.put(SecurityConstants.STS_TOKEN_ACT_AS, str);   -  -    STSClient stsClient = new STSClient(bus);   -    Map&lt;String, Object&gt; props = stsClient.getProperties();   -    props.put(SecurityConstants.USERNAME, "bob");   -    props.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler());   -    props.put(SecurityConstants.ENCRYPT_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey");   -    props.put(SecurityConstants.STS_TOKEN_USERNAME, "myclientkey");   -    props.put(SecurityConstants.STS_TOKEN_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true");   -  -    ctx.put(SecurityConstants.STS_CLIENT, stsClient);   -} finally {   -    bus.shutdown(true);   -}   + UsernameTokenCallbackHandler ch = new UsernameTokenCallbackHandler(); + String str = ch.getUsernameTokenString("alice","clarinet"); + ctx.put(SecurityConstants.STS_TOKEN_ACT_AS, str); + + STSClient stsClient = new STSClient(bus); + Map&lt;String, Object&gt; props = stsClient.getProperties(); + props.put(SecurityConstants.USERNAME, "bob"); + props.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler()); + props.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey"); + props.put(SecurityConstants.STS_TOKEN_USERNAME, "myclientkey"); + props.put(SecurityConstants.STS_TOKEN_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true"); + + ctx.put(SecurityConstants.STS_CLIENT, stsClient); +} finally { + bus.shutdown(true); +} proxy.sayHello(); </programlisting> </informalexample> </section> </section> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfWSTrustScenario"> + </section> + <section id="sid-78906783"> + + <title>OnBehalfOf WS-Trust Scenario</title> + <para> + The OnBehalfOf feature is used in scenarios that use the proxy pattern. In such scenarios, the client cannot access the STS directly, instead it communicates through a proxy gateway. The proxy gateway authenticates the caller and puts information about the caller into the OnBehalfOf element of the RequestSecurityToken (RST) sent to the real STS for processing. The resulting token contains only claims related to the client of the proxy, making the proxy completely transparent to the receiver of the issued token. - <title>OnBehalfOf WS-Trust Scenario</title> - <para> - The OnBehalfOf feature is used in scenarios that use the proxy pattern. In such scenarios, the client cannot access the STS directly, instead it communicates through a proxy gateway. The proxy gateway authenticates the caller and puts information about the caller into the OnBehalfOf element of the RequestSecurityToken (RST) sent to the real STS for processing. The resulting token contains only claims related to the client of the proxy, making the proxy completely transparent to the receiver of the issued token. + </para> + <para> + OnBehalfOf is nothing more than a new sub-element in the RST. It provides additional information about the original caller when a token is negotiated with the STS. The OnBehalfOf element usually takes the form of a token with identity claims such as name, role, and authorization code, for the client to access the service. + + </para> + <para> + The OnBehalfOf scenario is an extension of + <link linkend="sid-78906783">the basic WS-Trust scenario</link> + . In this example the OnBehalfOf service calls the ws-service on behalf of a user. There are only a couple of additions to the basic scenario's code. An OnBehalfOf web service provider and callback handler have been added. The OnBehalfOf web services' WSDL imposes the same security policies as the ws-provider. UsernameTokenCallbackHandler is a utility shared with ActAs. It generates the content for the OnBehalfOf element. And lastly there are code additions in the STS that both OnBehalfOf and ActAs share in common. + + </para> + <para> + Infor here [ + <ulink url="http://coheigea.blogspot.it/2012/01/apache-cxf-251-sts-updates.html">Open Source Security: Apache CXF 2.5.1 STS updates</ulink> + ] + </para> + <section id="sid-78906783_OnBehalfOfWS-TrustScenario-Webserviceprovider"> + + <title>Web service provider</title> + <para>This section examines the web service elements from the basic WS-Trust scenario that have been changed to address the needs of the OnBehalfOf example. The components are.</para> + <itemizedlist> + <listitem> + <para>web service provider's WSDL</para> + </listitem> + <listitem> + <para>web service provider's Interface and Implementation classes.</para> + </listitem> + <listitem> + <para>OnBehalfOfCallbackHandler class</para> + </listitem> + </itemizedlist> + <section id="sid-78906783_OnBehalfOfWS-TrustScenario-WebserviceproviderWSDL"> - </para> - <para> - OnBehalfOf is nothing more than a new sub-element in the RST. It provides additional information about the original caller when a token is negotiated with the STS. The OnBehalfOf element usually takes the form of a token with identity claims such as name, role, and authorization code, for the client to access the service. - - </para> - <para> - The OnBehalfOf scenario is an extension of - <link linkend="sid-47972359_WS-TrustandSTS-ABasicWSTrustScenario">the basic WS-Trust scenario</link> - . In this example the OnBehalfOf service calls the ws-service on behalf of a user. There are only a couple of additions to the basic scenario's code. An OnBehalfOf web service provider and callback handler have been added. The OnBehalfOf web services' WSDL imposes the same security policies as the ws-provider. UsernameTokenCallbackHandler is a utility shared with ActAs. It generates the content for the OnBehalfOf element. And lastly there are code additions in the STS that both OnBehalfOf and ActAs share in common. - - </para> - <para> - Infor here [ - <ulink url="http://coheigea.blogspot.it/2012/01/apache-cxf-251-sts-updates.html">Open Source Security: Apache CXF 2.5.1 STS updates</ulink> - ] - </para> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfWebserviceprovider"> - - <title>OnBehalfOf Web service provider</title> - <para>This section examines the web service elements from the basic WS-Trust scenario that have been changed to address the needs of the OnBehalfOf example. The components are.</para> - <itemizedlist> - <listitem> - <para>OnBehalfOf web service provider's WSDL</para> - </listitem> - <listitem> - <para>OnBehalfOf web service provider's Interface and Implementation classes.</para> - </listitem> - <listitem> - <para>OnBehalfOfCallbackHandler class</para> - </listitem> - </itemizedlist> - </section> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfWebserviceproviderWSDL"> - - <title>OnBehalfOf Web service provider WSDL</title> + <title>Web service provider WSDL</title> <para>The OnBehalfOf web service provider's WSDL is a clone of the ws-provider's WSDL. The wsp:Policy section is the same. There are changes to the service endpoint, targetNamespace, portType, binding name, and service.</para> <informalexample> <programlisting> &lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&gt; &lt;definitions targetNamespace="http://www.jboss.org/jbossws/ws-extensions/onbehalf... name="OnBehalfOfService" -             xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/onbehalfofwsse... -             xmlns:xsd="http://www.w3.org/2001/XMLSchema" -             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" -             xmlns="http://schemas.xmlsoap.org/wsdl/" -             xmlns:wsp="http://www.w3.org/ns/ws-policy" -             xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" -             xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... -             xmlns:wsaws="http://www.w3.org/2005/08/addressing" -             xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... -             xmlns:t="http://docs.oasis-open.org/ws-sx/ws-trust/200512"&gt; -    &lt;types&gt; -        &lt;xsd:schema&gt; -            &lt;xsd:import namespace="http://www.jboss.org/jbossws/ws-extensions/onbehalfofwsse... -                  schemaLocation="OnBehalfOfService_schema1.xsd"/&gt; -        &lt;/xsd:schema&gt; -    &lt;/types&gt; -    &lt;message name="sayHello"&gt; -        &lt;part name="parameters" element="tns:sayHello"/&gt; -    &lt;/message&gt; -    &lt;message name="sayHelloResponse"&gt; -        &lt;part name="parameters" element="tns:sayHelloResponse"/&gt; -    &lt;/message&gt; -    &lt;portType name="OnBehalfOfServiceIface"&gt; -        &lt;operation name="sayHello"&gt; -            &lt;input message="tns:sayHello"/&gt; -            &lt;output message="tns:sayHelloResponse"/&gt; -        &lt;/operation&gt; -    &lt;/portType&gt; -    &lt;binding name="OnBehalfOfServicePortBinding" type="tns:OnBehalfOfServiceIface"&gt; -        &lt;wsp:PolicyReference URI="#AsymmetricSAML2Policy" /&gt; -        &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt; -        &lt;operation name="sayHello"&gt; -            &lt;soap:operation soapAction=""/&gt; -            &lt;input&gt; -                &lt;soap:body use="literal"/&gt; -                &lt;wsp:PolicyReference URI="#Input_Policy" /&gt; -            &lt;/input&gt; -            &lt;output&gt; -                &lt;soap:body use="literal"/&gt; -                &lt;wsp:PolicyReference URI="#Output_Policy" /&gt; -            &lt;/output&gt; -        &lt;/operation&gt; -    &lt;/binding&gt; -    &lt;service name="OnBehalfOfService"&gt; -        &lt;port name="OnBehalfOfServicePort" binding="tns:OnBehalfOfServicePortBinding"&gt; -            &lt;soap:address location="http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService"/&gt; -        &lt;/port&gt; -    &lt;/service&gt; -&lt;/definitions&gt;  + xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/onbehalfofwsse... + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns="http://schemas.xmlsoap.org/wsdl/" + xmlns:wsp="http://www.w3.org/ns/ws-policy" + xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" + xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... + xmlns:wsaws="http://www.w3.org/2005/08/addressing" + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + xmlns:t="http://docs.oasis-open.org/ws-sx/ws-trust/200512"&gt; + &lt;types&gt; + &lt;xsd:schema&gt; + &lt;xsd:import namespace="http://www.jboss.org/jbossws/ws-extensions/onbehalfofwsse... + schemaLocation="OnBehalfOfService_schema1.xsd"/&gt; + &lt;/xsd:schema&gt; + &lt;/types&gt; + &lt;message name="sayHello"&gt; + &lt;part name="parameters" element="tns:sayHello"/&gt; + &lt;/message&gt; + &lt;message name="sayHelloResponse"&gt; + &lt;part name="parameters" element="tns:sayHelloResponse"/&gt; + &lt;/message&gt; + &lt;portType name="OnBehalfOfServiceIface"&gt; + &lt;operation name="sayHello"&gt; + &lt;input message="tns:sayHello"/&gt; + &lt;output message="tns:sayHelloResponse"/&gt; + &lt;/operation&gt; + &lt;/portType&gt; + &lt;binding name="OnBehalfOfServicePortBinding" type="tns:OnBehalfOfServiceIface"&gt; + &lt;wsp:PolicyReference URI="#AsymmetricSAML2Policy" /&gt; + &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt; + &lt;operation name="sayHello"&gt; + &lt;soap:operation soapAction=""/&gt; + &lt;input&gt; + &lt;soap:body use="literal"/&gt; + &lt;wsp:PolicyReference URI="#Input_Policy" /&gt; + &lt;/input&gt; + &lt;output&gt; + &lt;soap:body use="literal"/&gt; + &lt;wsp:PolicyReference URI="#Output_Policy" /&gt; + &lt;/output&gt; + &lt;/operation&gt; + &lt;/binding&gt; + &lt;service name="OnBehalfOfService"&gt; + &lt;port name="OnBehalfOfServicePort" binding="tns:OnBehalfOfServicePortBinding"&gt; + &lt;soap:address location="http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-onbehalfof/OnBehalfOfService"/&gt; + &lt;/port&gt; + &lt;/service&gt; +&lt;/definitions&gt; </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfWebServiceInterface"> + <section id="sid-78906783_OnBehalfOfWS-TrustScenario-WebServiceInterface"> - <title>OnBehalfOf Web Service Interface</title> + <title>Web Service Interface</title> <para>The web service provider interface class, OnBehalfOfServiceIface, is a simple web service definition.</para> <informalexample> <programlisting> -package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof;   -  -import javax.jws.WebMethod;   -import javax.jws.WebService;   -  -@WebService   -(   -   targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/onbehalfofwssecuritypolicy"   -)   -public interface OnBehalfOfServiceIface   -{   -   @WebMethod   -   String sayHello();   +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof; + +import javax.jws.WebMethod; +import javax.jws.WebService; + +@WebService +( + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/onbehalfofwssecuritypolicy" +) +public interface OnBehalfOfServiceIface +{ + @WebMethod + String sayHello(); } </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfWebServiceImplementation"> + <section id="sid-78906783_OnBehalfOfWS-TrustScenario-WebServiceImplementation"> - <title>OnBehalfOf Web Service Implementation</title> + <title>Web Service Implementation</title> <para>The web service provider implementation class, OnBehalfOfServiceImpl, is a simple POJO. It uses the standard WebService annotation to define the service endpoint and two Apache WSS4J annotations, EndpointProperties and EndpointProperty used for configuring the endpoint for the CXF runtime. The WSS4J configuration information provided is for WSS4J's Crypto Merlin implementation.</para> <para>OnBehalfOfServiceImpl is calling the ServiceImpl acting on behalf of the user. Method setupService performs the requisite configuration setup.</para> <informalexample> <programlisting> -package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof;   -  -import org.apache.cxf.Bus;   -import org.apache.cxf.BusFactory;   -import org.apache.cxf.annotations.EndpointProperties;   -import org.apache.cxf.annotations.EndpointProperty;   -import org.apache.cxf.ws.security.SecurityConstants;   -import org.apache.cxf.ws.security.trust.STSClient;   -import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.service.ServiceIface;   -import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared.WSTrustAppUtils;   -  -import javax.jws.WebService;   -import javax.xml.namespace.QName;   -import javax.xml.ws.BindingProvider;   -import javax.xml.ws.Service;   -import java.net.*;   -import java.util.Map;   -  -@WebService   -(   -   portName = "OnBehalfOfServicePort",   -   serviceName = "OnBehalfOfService",   -   wsdlLocation = "WEB-INF/wsdl/OnBehalfOfService.wsdl",   -   targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/onbehalfofwssecuritypolicy",   -   endpointInterface = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof.OnBehalfOfServiceIface"   -)   -  -@EndpointProperties(value = {   -      @EndpointProperty(key = "ws-security.signature.username", value = "myactaskey"),   -      @EndpointProperty(key = "ws-security.signature.properties", value =  "actasKeystore.properties"),   -      @EndpointProperty(key = "ws-security.encryption.properties", value = "actasKeystore.properties"),   -      @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof.OnBehalfOfCallbackHandler")   -})   -  -public class OnBehalfOfServiceImpl implements OnBehalfOfServiceIface   -{   -   public String sayHello() {   -      try {   -  -         ServiceIface proxy = setupService();   -         return "OnBehalfOf " + proxy.sayHello();   -  -      } catch (MalformedURLException e) {   -         e.printStackTrace();   -      }   -      return null;   -   }   -  -   /** -    * -    * @return -    * @throws MalformedURLException -    */   -   private  ServiceIface setupService()throws MalformedURLException {   -      ServiceIface proxy = null;   -      Bus bus = BusFactory.newInstance().createBus();   -  -      try {   -         BusFactory.setThreadDefaultBus(bus);   -  -         final String serviceURL = "http://" + WSTrustAppUtils.getServerHost() + ":8080/jaxws-samples-wsse-policy-trust/SecurityService";   -         final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy";, "SecurityService");   -         final URL wsdlURL = new URL(serviceURL + "?wsdl");   -         Service service = Service.create(wsdlURL, serviceName);   -         proxy = (ServiceIface) service.getPort(ServiceIface.class);   -  -         Map&lt;String, Object&gt; ctx = ((BindingProvider) proxy).getRequestContext();   -         ctx.put(SecurityConstants.CALLBACK_HANDLER, new OnBehalfOfCallbackHandler());   -  -         ctx.put(SecurityConstants.SIGNATURE_PROPERTIES,   -            Thread.currentThread().getContextClassLoader().getResource( - "actasKeystore.properties" ));   -         ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myactaskey" );   -         ctx.put(SecurityConstants.ENCRYPT_PROPERTIES,   -            Thread.currentThread().getContextClassLoader().getResource( - "../../META-INF/clientKeystore.properties" ));   -         ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myservicekey");   -  -         STSClient stsClient = new STSClient(bus);   -         Map&lt;String, Object&gt; props = stsClient.getProperties();   -         props.put(SecurityConstants.USERNAME, "bob");   -         props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey");   -         props.put(SecurityConstants.STS_TOKEN_USERNAME, "myactaskey" );   -         props.put(SecurityConstants.STS_TOKEN_PROPERTIES,   -            Thread.currentThread().getContextClassLoader().getResource( - "actasKeystore.properties" ));   -         props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true");   -  -         ctx.put(SecurityConstants.STS_CLIENT, stsClient);   -  -      } finally {   -         bus.shutdown(true);   -      }   -  -      return proxy;   -   }   -  +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof; + +import org.apache.cxf.Bus; +import org.apache.cxf.BusFactory; +import org.apache.cxf.annotations.EndpointProperties; +import org.apache.cxf.annotations.EndpointProperty; +import org.apache.cxf.ws.security.SecurityConstants; +import org.apache.cxf.ws.security.trust.STSClient; +import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.service.ServiceIface; +import org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared.WSTrustAppUtils; + +import javax.jws.WebService; +import javax.xml.namespace.QName; +import javax.xml.ws.BindingProvider; +import javax.xml.ws.Service; +import java.net.*; +import java.util.Map; + +@WebService +( + portName = "OnBehalfOfServicePort", + serviceName = "OnBehalfOfService", + wsdlLocation = "WEB-INF/wsdl/OnBehalfOfService.wsdl", + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/onbehalfofwssecuritypolicy", + endpointInterface = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof.OnBehalfOfServiceIface" +) + +@EndpointProperties(value = { + @EndpointProperty(key = "ws-security.signature.username", value = "myactaskey"), + @EndpointProperty(key = "ws-security.signature.properties", value = "actasKeystore.properties"), + @EndpointProperty(key = "ws-security.encryption.properties", value = "actasKeystore.properties"), + @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof.OnBehalfOfCallbackHandler") +}) + +public class OnBehalfOfServiceImpl implements OnBehalfOfServiceIface +{ + public String sayHello() { + try { + + ServiceIface proxy = setupService(); + return "OnBehalfOf " + proxy.sayHello(); + + } catch (MalformedURLException e) { + e.printStackTrace(); + } + return null; + } + + /** + * + * @return + * @throws MalformedURLException + */ + private ServiceIface setupService()throws MalformedURLException { + ServiceIface proxy = null; + Bus bus = BusFactory.newInstance().createBus(); + + try { + BusFactory.setThreadDefaultBus(bus); + + final String serviceURL = "http://" + WSTrustAppUtils.getServerHost() + ":8080/jaxws-samples-wsse-policy-trust/SecurityService"; + final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy";, "SecurityService"); + final URL wsdlURL = new URL(serviceURL + "?wsdl"); + Service service = Service.create(wsdlURL, serviceName); + proxy = (ServiceIface) service.getPort(ServiceIface.class); + + Map&lt;String, Object&gt; ctx = ((BindingProvider) proxy).getRequestContext(); + ctx.put(SecurityConstants.CALLBACK_HANDLER, new OnBehalfOfCallbackHandler()); + + ctx.put(SecurityConstants.SIGNATURE_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "actasKeystore.properties" )); + ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myactaskey" ); + ctx.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "../../META-INF/clientKeystore.properties" )); + ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myservicekey"); + + STSClient stsClient = new STSClient(bus); + Map&lt;String, Object&gt; props = stsClient.getProperties(); + props.put(SecurityConstants.USERNAME, "bob"); + props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey"); + props.put(SecurityConstants.STS_TOKEN_USERNAME, "myactaskey" ); + props.put(SecurityConstants.STS_TOKEN_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "actasKeystore.properties" )); + props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true"); + + ctx.put(SecurityConstants.STS_CLIENT, stsClient); + + } finally { + bus.shutdown(true); + } + + return proxy; + } + } </programlisting> </informalexample> </section> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfCallbackHandler"> + <section id="sid-78906783_OnBehalfOfWS-TrustScenario-OnBehalfOfCallbackHandler"> <title>OnBehalfOfCallbackHandler</title> <para>OnBehalfOfCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature. This class has been revised to return the passwords for this service, myactaskey and the "OnBehalfOf" user, alice.</para> <informalexample> <programlisting> - package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof;   -  -import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler;   -import java.util.HashMap;   -import java.util.Map;   -  -public class OnBehalfOfCallbackHandler extends PasswordCallbackHandler {   -  -   public OnBehalfOfCallbackHandler()   -   {   -      super(getInitMap());   -   }   -  -   private static Map&lt;String, String&gt; getInitMap()   -   {   -      Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;();   -      passwords.put("myactaskey", "aspass");   -      passwords.put("alice", "clarinet");   -      passwords.put("bob", "trombone");   -      return passwords;   -   }   -  + package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.onbehalfof; + +import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler; +import java.util.HashMap; +import java.util.Map; + +public class OnBehalfOfCallbackHandler extends PasswordCallbackHandler { + + public OnBehalfOfCallbackHandler() + { + super(getInitMap()); + } + + private static Map&lt;String, String&gt; getInitMap() + { + Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;(); + passwords.put("myactaskey", "aspass"); + passwords.put("alice", "clarinet"); + passwords.put("bob", "trombone"); + return passwords; + } + } </programlisting> </informalexample> </section> </section> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfWebservicerequester"> + <section id="sid-78906783_OnBehalfOfWS-TrustScenario-Webservicerequester"> - <title>OnBehalfOf Web service requester</title> + <title>Web service requester</title> <para>This section examines the ws-requester elements from the basic WS-Trust scenario that have been changed to address the needs of the OnBehalfOf example. The component is</para> <itemizedlist> <listitem> <para>OnBehalfOf web service requester implementation class</para> </listitem> </itemizedlist> - <section id="sid-47972359_WS-TrustandSTS-OnBehalfOfWebservicerequesterImplementation"> + <section id="sid-78906783_OnBehalfOfWS-TrustScenario-WebservicerequesterImplementation"> - <title>OnBehalfOf Web service requester Implementation</title> + <title>Web service requester Implementation</title> <para> The OnBehalfOf ws-requester, the client, uses standard procedures for creating a reference to the web service in the first four lines. To address the endpoint security requirements, the web service's "Request Context" is configured via the BindingProvider. Information needed in the message generation is provided through it. The OnBehalfOf user, alice, is declared in this section and the callbackHandler, UsernameTokenCallbackHandler is provided to the STSClient for generation of the contents for the OnBehalfOf message element. In this example a STSClient object is created and provided to the proxy's request context. The alternative is to provide keys tagged with the ".it" suffix as was done in - <link linkend="sid-47972359_WS-TrustandSTS-WebservicerequesterImplementation">the Basic Scenario client</link> + <link linkend="sid-78906783_OnBehalfOfWS-TrustScenario-WebservicerequesterImplementation">the Basic Scenario client</link> . The use of OnBehalfOf is configured by the method call stsClient.setOnBehalfOf. The alternative is to use the key SecurityConstants.STS_TOKEN_ON_BEHALF_OF and a value in the props map. </para> <informalexample> <programlisting> -final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/onbehalfofwssecuri...;, "OnBehalfOfService");   -final URL wsdlURL = new URL(serviceURL + "?wsdl");   -Service service = Service.create(wsdlURL, serviceName);   -OnBehalfOfServiceIface proxy = (OnBehalfOfServiceIface) service.getPort(OnBehalfOfServiceIface.class);   -        -  -Bus bus = BusFactory.newInstance().createBus();   -try {   -     -    BusFactory.setThreadDefaultBus(bus);   -  -    Map&lt;String, Object&gt; ctx = proxy.getRequestContext();   -  -    ctx.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler());   -    ctx.put(SecurityConstants.ENCRYPT_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myactaskey");   -    ctx.put(SecurityConstants.SIGNATURE_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myclientkey"); +final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/onbehalfofwssecuri...;, "OnBehalfOfService"); +final URL wsdlURL = new URL(serviceURL + "?wsdl"); +Service service = Service.create(wsdlURL, serviceName); +OnBehalfOfServiceIface proxy = (OnBehalfOfServiceIface) service.getPort(OnBehalfOfServiceIface.class); + +Bus bus = BusFactory.newInstance().createBus(); +try { + + BusFactory.setThreadDefaultBus(bus); + + Map&lt;String, Object&gt; ctx = proxy.getRequestContext(); + + ctx.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler()); + ctx.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myactaskey"); + ctx.put(SecurityConstants.SIGNATURE_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myclientkey"); + // user and password OnBehalfOf user // UsernameTokenCallbackHandler will extract this information when called -    ctx.put(SecurityConstants.USERNAME,"alice");   -    ctx.put(SecurityConstants.PASSWORD, "clarinet");   -  -    STSClient stsClient = new STSClient(bus); + ctx.put(SecurityConstants.USERNAME,"alice"); + ctx.put(SecurityConstants.PASSWORD, "clarinet"); - // Providing the STSClient the mechanism to create the claims contents for OnBehalfOf  -    stsClient.setOnBehalfOf(new UsernameTokenCallbackHandler());   -  -    Map&lt;String, Object&gt; props = stsClient.getProperties();   -    props.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler());   -    props.put(SecurityConstants.ENCRYPT_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey");   -    props.put(SecurityConstants.STS_TOKEN_USERNAME, "myclientkey");   -    props.put(SecurityConstants.STS_TOKEN_PROPERTIES,   -        Thread.currentThread().getContextClassLoader().getResource( - "META-INF/clientKeystore.properties"));   -    props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true");   -  -    ctx.put(SecurityConstants.STS_CLIENT, stsClient);   -     -} finally {   -    bus.shutdown(true);   -}   + STSClient stsClient = new STSClient(bus); + + // Providing the STSClient the mechanism to create the claims contents for OnBehalfOf + stsClient.setOnBehalfOf(new UsernameTokenCallbackHandler()); + + Map&lt;String, Object&gt; props = stsClient.getProperties(); + props.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler()); + props.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + props.put(SecurityConstants.ENCRYPT_USERNAME, "mystskey"); + props.put(SecurityConstants.STS_TOKEN_USERNAME, "myclientkey"); + props.put(SecurityConstants.STS_TOKEN_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true"); + + ctx.put(SecurityConstants.STS_CLIENT, stsClient); + +} finally { + bus.shutdown(true); +} proxy.sayHello(); </programlisting> </informalexample> </section> </section> </section> + <section id="sid-78906786"> + + <title>SAML Bearer Assertion Scenario</title> + <para> + WS-Trust deals with managing software security tokens. A SAML assertion is a type of security token. In the SAML Bearer scenario, the service provider automatically trusts that the incoming SOAP request came from the subject defined in the SAML token after the service verifies the tokens signature. + + </para> + <para>Implementation of this scenario has the following requirements.</para> + <itemizedlist> + <listitem> + <para>SAML tokens with a Bearer subject confirmation method must be protected so the token can not be snooped. In most cases, a bearer token combined with HTTPS is sufficient to prevent "a man in the middle" getting possession of the token. This means a security policy that uses a sp:TransportBinding and sp:HttpsToken.</para> + </listitem> + <listitem> + <para> + A bearer token has no encryption or signing keys associated with it, therefore a sp:IssuedToken of bearer keyType should be used with a sp:SupportingToken or a sp:SignedSupportingTokens. + + </para> + </listitem> + </itemizedlist> + <section id="sid-78906786_SAMLBearerAssertionScenario-WebserviceProvider"> + + <title>Web service Provider</title> + <para>This section examines the web service elements for the SAML Bearer scenario. The components are</para> + <itemizedlist> + <listitem> + <para>Bearer web service provider's WSDL</para> + </listitem> + <listitem> + <para>SSL configuration</para> + </listitem> + <listitem> + <para>Bearer web service provider's Interface and Implementation classes.</para> + </listitem> + <listitem> + <para>Crypto properties and keystore files</para> + </listitem> + <listitem> + <para>MANIFEST.MF</para> + </listitem> + </itemizedlist> + <section id="sid-78906786_SAMLBearerAssertionScenario-WebserviceproviderWSDL"> + + <title>Web service provider WSDL</title> + <para>The web service provider is a contract-first endpoint. All the WS-trust and security policies for it are declared in WSDL, BearerService.wsdl. For this scenario a ws-requester is required to present a SAML 2.0 Bearer token issued from a designed STS. The address of the STS is provided in the WSDL. HTTPS, a TransportBinding and HttpsToken policy are used to protect the SOAP body of messages that pass back and forth between ws-requester and ws-provider. A detailed explanation of the security settings are provided in the comments in the listing below.</para> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&gt; +&lt;definitions targetNamespace="http://www.jboss.org/jbossws/ws-extensions/bearerws... + name="BearerService" + xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/bearerwssecuri... + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns="http://schemas.xmlsoap.org/wsdl/" + xmlns:wsp="http://www.w3.org/ns/ws-policy" + xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" + xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... + xmlns:wsaws="http://www.w3.org/2005/08/addressing" + xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex" + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + xmlns:t="http://docs.oasis-open.org/ws-sx/ws-trust/200512"&gt; + + &lt;types&gt; + &lt;xsd:schema&gt; + &lt;xsd:import namespace="http://www.jboss.org/jbossws/ws-extensions/bearerwssecuri... + schemaLocation="BearerService_schema1.xsd"/&gt; + &lt;/xsd:schema&gt; + &lt;/types&gt; + &lt;message name="sayHello"&gt; + &lt;part name="parameters" element="tns:sayHello"/&gt; + &lt;/message&gt; + &lt;message name="sayHelloResponse"&gt; + &lt;part name="parameters" element="tns:sayHelloResponse"/&gt; + &lt;/message&gt; + &lt;portType name="BearerIface"&gt; + &lt;operation name="sayHello"&gt; + &lt;input message="tns:sayHello"/&gt; + &lt;output message="tns:sayHelloResponse"/&gt; + &lt;/operation&gt; + &lt;/portType&gt; + +&lt;!-- + The wsp:PolicyReference binds the security requirments on all the endpoints. + The wsp:Policy wsu:Id="#TransportSAML2BearerPolicy" element is defined later in this file. +--&gt; + &lt;binding name="BearerServicePortBinding" type="tns:BearerIface"&gt; + &lt;wsp:PolicyReference URI="#TransportSAML2BearerPolicy" /&gt; + &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt; + &lt;operation name="sayHello"&gt; + &lt;soap:operation soapAction=""/&gt; + &lt;input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/input&gt; + &lt;output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/output&gt; + &lt;/operation&gt; + &lt;/binding&gt; + +&lt;!-- + The soap:address has been defined to use JBoss's https port, 8443. This is + set in conjunction with the sp:TransportBinding policy for https. +--&gt; + &lt;service name="BearerService"&gt; + &lt;port name="BearerServicePort" binding="tns:BearerServicePortBinding"&gt; + &lt;soap:address location="https://@jboss.bind.address@:8443/jaxws-samples-wsse-policy-trust-bearer/BearerService"/&gt; + &lt;/port&gt; + &lt;/service&gt; + + + &lt;wsp:Policy wsu:Id="TransportSAML2BearerPolicy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;!-- + The wsam:Addressing element, indicates that the endpoints of this + web service MUST conform to the WS-Addressing specification. The + attribute wsp:Optional="false" enforces this assertion. + --&gt; + &lt;wsam:Addressing wsp:Optional="false"&gt; + &lt;wsp:Policy /&gt; + &lt;/wsam:Addressing&gt; + +&lt;!-- + The sp:TransportBinding element indicates that security is provided by the + message exchange transport medium, https. WS-Security policy specification + defines the sp:HttpsToken for use in exchanging messages transmitted over HTTPS. +--&gt; + &lt;sp:TransportBinding + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:TransportToken&gt; + &lt;wsp:Policy&gt; + &lt;sp:HttpsToken&gt; + &lt;wsp:Policy/&gt; + &lt;/sp:HttpsToken&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:TransportToken&gt; +&lt;!-- + The sp:AlgorithmSuite element, requires the TripleDes algorithm suite + be used in performing cryptographic operations. +--&gt; + &lt;sp:AlgorithmSuite&gt; + &lt;wsp:Policy&gt; + &lt;sp:TripleDes /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:AlgorithmSuite&gt; +&lt;!-- + The sp:Layout element, indicates the layout rules to apply when adding + items to the security header. The sp:Lax sub-element indicates items + are added to the security header in any order that conforms to + WSS: SOAP Message Security. +--&gt; + &lt;sp:Layout&gt; + &lt;wsp:Policy&gt; + &lt;sp:Lax /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Layout&gt; + &lt;sp:IncludeTimestamp /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:TransportBinding&gt; + +&lt;!-- + The sp:SignedSupportingTokens element causes the supporting tokens + to be signed using the primary token that is used to sign the message. +--&gt; + &lt;sp:SignedSupportingTokens + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; +&lt;!-- + The sp:IssuedToken element asserts that a SAML 2.0 security token of type + Bearer is expected from the STS. The + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + attribute instructs the runtime to include the initiator's public key + with every message sent to the recipient. + + The sp:RequestSecurityTokenTemplate element directs that all of the + children of this element will be copied directly into the body of the + RequestSecurityToken (RST) message that is sent to the STS when the + initiator asks the STS to issue a token. +--&gt; + &lt;sp:IssuedToken + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + &lt;sp:RequestSecurityTokenTemplate&gt; + &lt;t:TokenType&gt;http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0&lt;/t:TokenType&gt; + &lt;t:KeyType&gt;http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer&lt;/t:KeyType&gt; + &lt;/sp:RequestSecurityTokenTemplate&gt; + &lt;wsp:Policy&gt; + &lt;sp:RequireInternalReference /&gt; + &lt;/wsp:Policy&gt; +&lt;!-- + The sp:Issuer element defines the STS's address and endpoint information + This information is used by the STSClient. +--&gt; + &lt;sp:Issuer&gt; + &lt;wsaws:Address&gt;http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-sts-bearer/SecurityTokenService&lt;/wsaws:Address&gt; + &lt;wsaws:Metadata + xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance" + wsdli:wsdlLocation="http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-sts-bearer/SecurityTokenService?wsdl"&gt; + &lt;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"&gt;stsns:SecurityTokenService&lt;/wsaw:ServiceName&gt; + &lt;/wsaws:Metadata&gt; + &lt;/sp:Issuer&gt; + + &lt;/sp:IssuedToken&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:SignedSupportingTokens&gt; +&lt;!-- + The sp:Wss11 element declares WSS: SOAP Message Security 1.1 options + to be supported by the STS. These particular elements generally refer + to how keys are referenced within the SOAP envelope. These are normally + handled by CXF. +--&gt; + &lt;sp:Wss11&gt; + &lt;wsp:Policy&gt; + &lt;sp:MustSupportRefIssuerSerial /&gt; + &lt;sp:MustSupportRefThumbprint /&gt; + &lt;sp:MustSupportRefEncryptedKey /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Wss11&gt; +&lt;!-- + The sp:Trust13 element declares controls for WS-Trust 1.3 options. + They are policy assertions related to exchanges specifically with + client and server challenges and entropy behaviors. Again these are + normally handled by CXF. +--&gt; + &lt;sp:Trust13&gt; + &lt;wsp:Policy&gt; + &lt;sp:MustSupportIssuedTokens /&gt; + &lt;sp:RequireClientEntropy /&gt; + &lt;sp:RequireServerEntropy /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Trust13&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + +&lt;/definitions&gt; +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-SSLconfiguration"> + + <title>SSL configuration</title> + <para>This web service is using https, therefore the JBoss server must be configured to provide SSL support in the Web subsystem. There are 2 components to SSL configuration.</para> + <itemizedlist> + <listitem> + <para>create a certificate keystore</para> + </listitem> + <listitem> + <para>declare an SSL connector in the Web subsystem of the JBoss server configuration file.</para> + </listitem> + </itemizedlist> + <para> + Follow the directions in the, " + <emphasis role="italics">Using the pure Java implementation supplied by JSSE</emphasis> + " section in the + <ulink url="https://docs.jboss.org/author/display/WFLY8/SSL+setup+guide&quo... Setup Guide</ulink> + . + </para> + <para>Here is an example of an SSL connector declaration.</para> + <informalexample> + <programlisting> +&lt;subsystem xmlns="urn:jboss:domain:web:1.4" default-virtual-server="default-host" native="false"&gt; + ..... + &lt;connector name="jbws-https-connector" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true" enabled="true"&gt; + &lt;ssl key-alias="tomcat" password="changeit" certificate-key-file="/myJbossHome/security/test.keystore" verify-client="false"/&gt; + &lt;/connector&gt; + ... +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-WebserviceInterface"> + + <title>Web service Interface</title> + <para>The web service provider interface class, BearerIface, is a simple straight forward web service definition.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.bearer; + +import javax.jws.WebMethod; +import javax.jws.WebService; + +@WebService +( + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/bearerwssecuritypolicy" +) +public interface BearerIface +{ + @WebMethod + String sayHello(); +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-WebserviceImplementation"> + + <title>Web service Implementation</title> + <para> + The web service provider implementation class, BearerImpl, is a simple POJO. It uses the standard WebService annotation to define the service endpoint. In addition there are two Apache CXF annotations, EndpointProperties and EndpointProperty used for configuring the endpoint for the CXF runtime. These annotations come from the + <ulink url="https://ws.apache.org/wss4j/">Apache WSS4J project</ulink> + , which provides a Java implementation of the primary WS-Security standards for Web Services. These annotations are programmatically adding properties to the endpoint. With plain Apache CXF, these properties are often set via the &lt;jaxws:properties&gt; element on the &lt;jaxws:endpoint&gt; element in the Spring config; these annotations allow the properties to be configured in the code. + </para> + <para>WSS4J uses the Crypto interface to get keys and certificates for signature creation/verification, as is asserted by the WSDL for this service. The WSS4J configuration information being provided by BearerImpl is for Crypto's Merlin implementation. More information will be provided about this in the keystore section.</para> + <para>Because the web service provider automatically trusts that the incoming SOAP request came from the subject defined in the SAML token there is no need for a Crypto callbackHandler class or a signature username, unlike in prior examples, however in order to verify the message signature, the Java properties file that contains the (Merlin) crypto configuration information is still required.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.bearer; + +import org.apache.cxf.annotations.EndpointProperties; +import org.apache.cxf.annotations.EndpointProperty; + +import javax.jws.WebService; + +@WebService +( + portName = "BearerServicePort", + serviceName = "BearerService", + wsdlLocation = "WEB-INF/wsdl/BearerService.wsdl", + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/bearerwssecuritypolicy", + endpointInterface = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.bearer.BearerIface" +) +@EndpointProperties(value = { + @EndpointProperty(key = "ws-security.signature.properties", value = "serviceKeystore.properties") +}) +public class BearerImpl implements BearerIface +{ + public String sayHello() + { + return "Bearer WS-Trust Hello World!"; + } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-Cryptopropertiesandkeystorefiles"> + + <title>Crypto properties and keystore files</title> + <para>WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data. The file contains implementation-specific properties such as a keystore location, password, default alias and the like. This application is using the Merlin implementation. File serviceKeystore.properties contains this information.</para> + <para> + File servicestore.jks, is a Java KeyStore (JKS) repository. It contains self signed certificates for myservicekey and mystskey. + <emphasis role="italics">Self signed certificates are not appropriate for production use.</emphasis> + </para> + <informalexample> + <programlisting> +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=sspass +org.apache.ws.security.crypto.merlin.keystore.alias=myservicekey +org.apache.ws.security.crypto.merlin.keystore.file=servicestore.jks +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-MANIFEST.MF"> + + <title>MANIFEST.MF</title> + <para>When deployed on WildFly this application requires access to the JBossWs and CXF APIs provided in module org.jboss.ws.cxf.jbossws-cxf-client. The dependency statement directs the server to provide them at deployment.</para> + <informalexample> + <programlisting> +Manifest-Version: 1.0   +Ant-Version: Apache Ant 1.8.2   +Created-By: 1.7.0_25-b15 (Oracle Corporation)   +Dependencies: org.jboss.ws.cxf.jbossws-cxf-client +</programlisting> + </informalexample> + </section> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-BearerSecurityTokenService"> + + <title>Bearer Security Token Service</title> + <para>This section examines the crucial elements in providing the Security Token Service functionality for providing a SAML Bearer token. The components that will be discussed are.</para> + <itemizedlist> + <listitem> + <para>Security Domain</para> + </listitem> + <listitem> + <para>STS's WSDL</para> + </listitem> + <listitem> + <para>STS's implementation class</para> + </listitem> + <listitem> + <para>STSBearerCallbackHandler</para> + </listitem> + <listitem> + <para>Crypto properties and keystore files</para> + </listitem> + <listitem> + <para> + MANIFEST.MF + + </para> + </listitem> + </itemizedlist> + <section id="sid-78906786_SAMLBearerAssertionScenario-SecurityDomain"> + + <title>Security Domain</title> + <para>The STS requires a JBoss security domain be configured. The jboss-web.xml descriptor declares a named security domain,"JBossWS-trust-sts" to be used by this service for authentication. This security domain requires two properties files and the addition of a security-domain declaration in the JBoss server configuration file.</para> + <para> + For this scenario the domain needs to contain user + <emphasis role="italics">alice</emphasis> + , password + <emphasis role="italics">clarinet</emphasis> + , and role + <emphasis role="italics">friend</emphasis> + . See the listings below for jbossws-users.properties and jbossws-roles.properties. In addition the following XML must be added to the JBoss security subsystem in the server configuration file. Replace " + <emphasis role="strong">SOME_PATH</emphasis> + " with appropriate information. + </para> + <informalexample> + <programlisting> +&lt;security-domain name="JBossWS-trust-sts"&gt; +  &lt;authentication&gt; +    &lt;login-module code="UsersRoles" flag="required"&gt; +      &lt;module-option name="usersProperties" value="/SOME_PATH/jbossws-users.properties"/&gt; +      &lt;module-option name="unauthenticatedIdentity" value="anonymous"/&gt; +      &lt;module-option name="rolesProperties" value="/SOME_PATH/jbossws-roles.properties"/&gt; +    &lt;/login-module&gt; +  &lt;/authentication&gt; +&lt;/security-domain&gt; +</programlisting> + </informalexample> + <para>jboss-web.xml</para> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8"?&gt;   +&lt;!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.4//EN" "&gt;   +&lt;jboss-web&gt;   +  &lt;security-domain&gt;java:/jaas/JBossWS-trust-sts&lt;/security-domain&gt;   +&lt;/jboss-web&gt; +</programlisting> + </informalexample> + <para>jbossws-users.properties</para> + <informalexample> + <programlisting> +# A sample users.properties file for use with the UsersRolesLoginModule   +alice=clarinet +</programlisting> + </informalexample> + <para>jbossws-roles.properties</para> + <informalexample> + <programlisting> +# A sample roles.properties file for use with the UsersRolesLoginModule   +alice=friend +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-STS%27sWSDL"> + + <title>STS's WSDL</title> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;wsdl:definitions + targetNamespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512/&q... + xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/" + xmlns:wstrust="http://docs.oasis-open.org/ws-sx/ws-trust/200512/" + xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl" + xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... + xmlns:wsp="http://www.w3.org/ns/ws-policy" + xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"&gt; + + &lt;wsdl:types&gt; + &lt;xs:schema elementFormDefault="qualified" + targetNamespace='http://docs.oasis-open.org/ws-sx/ws-trust/200512'... + + &lt;xs:element name='RequestSecurityToken' + type='wst:AbstractRequestSecurityTokenType'/&gt; + &lt;xs:element name='RequestSecurityTokenResponse' + type='wst:AbstractRequestSecurityTokenType'/&gt; + + &lt;xs:complexType name='AbstractRequestSecurityTokenType'&gt; + &lt;xs:sequence&gt; + &lt;xs:any namespace='##any' processContents='lax' minOccurs='0' + maxOccurs='unbounded'/&gt; + &lt;/xs:sequence&gt; + &lt;xs:attribute name='Context' type='xs:anyURI' use='optional'/&gt; + &lt;xs:anyAttribute namespace='##other' processContents='lax'/&gt; + &lt;/xs:complexType&gt; + &lt;xs:element name='RequestSecurityTokenCollection' + type='wst:RequestSecurityTokenCollectionType'/&gt; + &lt;xs:complexType name='RequestSecurityTokenCollectionType'&gt; + &lt;xs:sequence&gt; + &lt;xs:element name='RequestSecurityToken' + type='wst:AbstractRequestSecurityTokenType' minOccurs='2' + maxOccurs='unbounded'/&gt; + &lt;/xs:sequence&gt; + &lt;/xs:complexType&gt; + + &lt;xs:element name='RequestSecurityTokenResponseCollection' + type='wst:RequestSecurityTokenResponseCollectionType'/&gt; + &lt;xs:complexType name='RequestSecurityTokenResponseCollectionType'&gt; + &lt;xs:sequence&gt; + &lt;xs:element ref='wst:RequestSecurityTokenResponse' minOccurs='1' + maxOccurs='unbounded'/&gt; + &lt;/xs:sequence&gt; + &lt;xs:anyAttribute namespace='##other' processContents='lax'/&gt; + &lt;/xs:complexType&gt; + + &lt;/xs:schema&gt; + &lt;/wsdl:types&gt; + + &lt;!-- WS-Trust defines the following GEDs --&gt; + &lt;wsdl:message name="RequestSecurityTokenMsg"&gt; + &lt;wsdl:part name="request" element="wst:RequestSecurityToken"/&gt; + &lt;/wsdl:message&gt; + &lt;wsdl:message name="RequestSecurityTokenResponseMsg"&gt; + &lt;wsdl:part name="response" + element="wst:RequestSecurityTokenResponse"/&gt; + &lt;/wsdl:message&gt; + &lt;wsdl:message name="RequestSecurityTokenCollectionMsg"&gt; + &lt;wsdl:part name="requestCollection" + element="wst:RequestSecurityTokenCollection"/&gt; + &lt;/wsdl:message&gt; + &lt;wsdl:message name="RequestSecurityTokenResponseCollectionMsg"&gt; + &lt;wsdl:part name="responseCollection" + element="wst:RequestSecurityTokenResponseCollection"/&gt; + &lt;/wsdl:message&gt; + + &lt;!-- This portType an example of a Requestor (or other) endpoint that + Accepts SOAP-based challenges from a Security Token Service --&gt; + &lt;wsdl:portType name="WSSecurityRequestor"&gt; + &lt;wsdl:operation name="Challenge"&gt; + &lt;wsdl:input message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;wsdl:output message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:portType&gt; + + &lt;!-- This portType is an example of an STS supporting full protocol --&gt; + &lt;!-- + The wsdl:portType and data types are XML elements defined by the + WS_Trust specification. The wsdl:portType defines the endpoints + supported in the STS implementation. This WSDL defines all operations + that an STS implementation can support. + --&gt; + &lt;wsdl:portType name="STS"&gt; + &lt;wsdl:operation name="Cancel"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Ca... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/C... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Issue"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Is... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/... + message="tns:RequestSecurityTokenResponseCollectionMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Renew"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Re... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/R... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Validate"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Va... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/V... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="KeyExchangeToken"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/KE... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/K... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="RequestCollection"&gt; + &lt;wsdl:input message="tns:RequestSecurityTokenCollectionMsg"/&gt; + &lt;wsdl:output message="tns:RequestSecurityTokenResponseCollectionMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:portType&gt; + + &lt;!-- This portType is an example of an endpoint that accepts + Unsolicited RequestSecurityTokenResponse messages --&gt; + &lt;wsdl:portType name="SecurityTokenResponseService"&gt; + &lt;wsdl:operation name="RequestSecurityTokenResponse"&gt; + &lt;wsdl:input message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:portType&gt; + + &lt;!-- + The wsp:PolicyReference binds the security requirments on all the STS endpoints. + The wsp:Policy wsu:Id="UT_policy" element is later in this file. + --&gt; + &lt;wsdl:binding name="UT_Binding" type="wstrust:STS"&gt; + &lt;wsp:PolicyReference URI="#UT_policy"/&gt; + &lt;soap:binding style="document" + transport="http://schemas.xmlsoap.org/soap/http"/&gt; + &lt;wsdl:operation name="Issue"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Iss... + &lt;wsdl:input&gt; + &lt;wsp:PolicyReference + URI="#Input_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;wsp:PolicyReference + URI="#Output_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Validate"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Val... + &lt;wsdl:input&gt; + &lt;wsp:PolicyReference + URI="#Input_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;wsp:PolicyReference + URI="#Output_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Cancel"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Can... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Renew"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Ren... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="KeyExchangeToken"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Key... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="RequestCollection"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Req... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:binding&gt; + + &lt;wsdl:service name="SecurityTokenService"&gt; + &lt;wsdl:port name="UT_Port" binding="tns:UT_Binding"&gt; + &lt;soap:address location="http://localhost:8080/SecurityTokenService/UT"/&gt; + &lt;/wsdl:port&gt; + &lt;/wsdl:service&gt; + + + &lt;wsp:Policy wsu:Id="UT_policy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;!-- + The sp:UsingAddressing element, indicates that the endpoints of this + web service conforms to the WS-Addressing specification. More detail + can be found here: [http://www.w3.org/TR/2006/CR-ws-addr-wsdl-20060529] + --&gt; + &lt;wsap10:UsingAddressing/&gt; + &lt;!-- + The sp:SymmetricBinding element indicates that security is provided + at the SOAP layer and any initiator must authenticate itself by providing + WSS UsernameToken credentials. + --&gt; + &lt;sp:SymmetricBinding + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;!-- + In a symmetric binding, the keys used for encrypting and signing in both + directions are derived from a single key, the one specified by the + sp:ProtectionToken element. The sp:X509Token sub-element declares this + key to be a X.509 certificate and the + IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200... + attribute adds the requirement that the token MUST NOT be included in + any messages sent between the initiator and the recipient; rather, an + external reference to the token should be used. Lastly the WssX509V3Token10 + sub-element declares that the Username token presented by the initiator + should be compliant with Web Services Security UsernameToken Profile + 1.0 specification. [ http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-pr... ] + --&gt; + &lt;sp:ProtectionToken&gt; + &lt;wsp:Policy&gt; + &lt;sp:X509Token + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + &lt;wsp:Policy&gt; + &lt;sp:RequireDerivedKeys/&gt; + &lt;sp:RequireThumbprintReference/&gt; + &lt;sp:WssX509V3Token10/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:X509Token&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:ProtectionToken&gt; + &lt;!-- + The sp:AlgorithmSuite element, requires the Basic256 algorithm suite + be used in performing cryptographic operations. + --&gt; + &lt;sp:AlgorithmSuite&gt; + &lt;wsp:Policy&gt; + &lt;sp:Basic256/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:AlgorithmSuite&gt; + &lt;!-- + The sp:Layout element, indicates the layout rules to apply when adding + items to the security header. The sp:Lax sub-element indicates items + are added to the security header in any order that conforms to + WSS: SOAP Message Security. + --&gt; + &lt;sp:Layout&gt; + &lt;wsp:Policy&gt; + &lt;sp:Lax/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Layout&gt; + &lt;sp:IncludeTimestamp/&gt; + &lt;sp:EncryptSignature/&gt; + &lt;sp:OnlySignEntireHeadersAndBody/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:SymmetricBinding&gt; + + &lt;!-- + The sp:SignedSupportingTokens element declares that the security header + of messages must contain a sp:UsernameToken and the token must be signed. + The attribute IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200... + on sp:UsernameToken indicates that the token MUST be included in all + messages sent from initiator to the recipient and that the token MUST + NOT be included in messages sent from the recipient to the initiator. + And finally the element sp:WssUsernameToken10 is a policy assertion + indicating the Username token should be as defined in Web Services + Security UsernameToken Profile 1.0 + --&gt; + &lt;sp:SignedSupportingTokens + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:UsernameToken + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + &lt;wsp:Policy&gt; + &lt;sp:WssUsernameToken10/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:UsernameToken&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:SignedSupportingTokens&gt; + &lt;!-- + The sp:Wss11 element declares WSS: SOAP Message Security 1.1 options + to be supported by the STS. These particular elements generally refer + to how keys are referenced within the SOAP envelope. These are normally + handled by CXF. + --&gt; + &lt;sp:Wss11 + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:MustSupportRefKeyIdentifier/&gt; + &lt;sp:MustSupportRefIssuerSerial/&gt; + &lt;sp:MustSupportRefThumbprint/&gt; + &lt;sp:MustSupportRefEncryptedKey/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Wss11&gt; + &lt;!-- + The sp:Trust13 element declares controls for WS-Trust 1.3 options. + They are policy assertions related to exchanges specifically with + client and server challenges and entropy behaviors. Again these are + normally handled by CXF. + --&gt; + &lt;sp:Trust13 + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:MustSupportIssuedTokens/&gt; + &lt;sp:RequireClientEntropy/&gt; + &lt;sp:RequireServerEntropy/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Trust13&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + + &lt;wsp:Policy wsu:Id="Input_policy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;sp:SignedParts + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;sp:Body/&gt; + &lt;sp:Header Name="To" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="From" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="FaultTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="ReplyTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="MessageID" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="RelatesTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="Action" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;/sp:SignedParts&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + + &lt;wsp:Policy wsu:Id="Output_policy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;sp:SignedParts + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;sp:Body/&gt; + &lt;sp:Header Name="To" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="From" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="FaultTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="ReplyTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="MessageID" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="RelatesTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="Action" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;/sp:SignedParts&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + +&lt;/wsdl:definitions&gt; +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-STS%27simplementationclass"> + + <title>STS's implementation class</title> + <para> + The Apache CXF's STS, SecurityTokenServiceProvider, is a web service provider that is compliant with the protocols and functionality defined by the WS-Trust specification. It has a modular architecture. Many of its components are configurable or replaceable and there are many optional features that are enabled by implementing and configuring plug-ins. Users can customize their own STS by extending from SecurityTokenServiceProvider and overriding the default settings. Extensive information about the CXF's STS configurable and pluggable components can be found + <ulink url="http://coheigea.blogspot.com/2011/11/apache-cxf-sts-documentati... + . + </para> + <para>This STS implementation class, SampleSTSBearer, is a POJO that extends from SecurityTokenServiceProvider. Note that the class is defined with a WebServiceProvider annotation and not a WebService annotation. This annotation defines the service as a Provider-based endpoint, meaning it supports a more messaging-oriented approach to Web services. In particular, it signals that the exchanged messages will be XML documents of some type. SecurityTokenServiceProvider is an implementation of the javax.xml.ws.Provider interface. In comparison the WebService annotation defines a (service endpoint interface) SEI-based endpoint which supports message exchange via SOAP envelopes.</para> + <para>As was done in the BearerImpl class, the WSS4J annotations EndpointProperties and EndpointProperty are providing endpoint configuration for the CXF runtime. The first EndpointProperty statement in the listing is declaring the user's name to use for the message signature. It is used as the alias name in the keystore to get the user's cert and private key for signature. The next two EndpointProperty statements declares the Java properties file that contains the (Merlin) crypto configuration information. In this case both for signing and encrypting the messages. WSS4J reads this file and extra required information for message handling. The last EndpointProperty statement declares the STSBearerCallbackHandler implementation class. It is used to obtain the user's password for the certificates in the keystore file.</para> + <para>In this implementation we are customizing the operations of token issuance, token validation and their static properties.</para> + <para>StaticSTSProperties is used to set select properties for configuring resources in the STS. You may think this is a duplication of the settings made with the WSS4J annotations. The values are the same but the underlaying structures being set are different, thus this information must be declared in both places.</para> + <para>The setIssuer setting is important because it uniquely identifies the issuing STS. The issuer string is embedded in issued tokens and, when validating tokens, the STS checks the issuer string value. Consequently, it is important to use the issuer string in a consistent way, so that the STS can recognize the tokens that it has issued.</para> + <para>The setEndpoints call allows the declaration of a set of allowed token recipients by address. The addresses are specified as reg-ex patterns.</para> + <para>TokenIssueOperation has a modular structure. This allows custom behaviors to be injected into the processing of messages. In this case we are overriding the SecurityTokenServiceProvider's default behavior and performing SAML token processing. CXF provides an implementation of a SAMLTokenProvider which we are using rather than writing our own.</para> + <para> + Learn more about the SAMLTokenProvider + <ulink url="http://coheigea.blogspot.it/2011/10/apache-cxf-sts-documentation-part-iv.html">here</ulink> + . + </para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.stsbearer; + +import org.apache.cxf.annotations.EndpointProperties; +import org.apache.cxf.annotations.EndpointProperty; +import org.apache.cxf.sts.StaticSTSProperties; +import org.apache.cxf.sts.operation.TokenIssueOperation; +import org.apache.cxf.sts.service.ServiceMBean; +import org.apache.cxf.sts.service.StaticService; +import org.apache.cxf.sts.token.provider.SAMLTokenProvider; +import org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider; + +import javax.xml.ws.WebServiceProvider; +import java.util.Arrays; +import java.util.LinkedList; +import java.util.List; + +@WebServiceProvider(serviceName = "SecurityTokenService", + portName = "UT_Port", + targetNamespace = "http://docs.oasis-open.org/ws-sx/ws-trust/200512/", + wsdlLocation = "WEB-INF/wsdl/bearer-ws-trust-1.4-service.wsdl") +//be sure to have dependency on org.apache.cxf module when on AS7, otherwise Apache CXF annotations are ignored +@EndpointProperties(value = { + @EndpointProperty(key = "ws-security.signature.username", value = "mystskey"), + @EndpointProperty(key = "ws-security.signature.properties", value = "stsKeystore.properties"), + @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.stsbearer.STSBearerCallbackHandler") +}) +public class SampleSTSBearer extends SecurityTokenServiceProvider +{ + + public SampleSTSBearer() throws Exception + { + super(); + + StaticSTSProperties props = new StaticSTSProperties(); + props.setSignatureCryptoProperties("stsKeystore.properties"); + props.setSignatureUsername("mystskey"); + props.setCallbackHandlerClass(STSBearerCallbackHandler.class.getName()); + props.setEncryptionCryptoProperties("stsKeystore.properties"); + props.setEncryptionUsername("myservicekey"); + props.setIssuer("DoubleItSTSIssuer"); + + List&lt;ServiceMBean&gt; services = new LinkedList&lt;ServiceMBean&gt;(); + StaticService service = new StaticService(); + service.setEndpoints(Arrays.asList( + "https://localhost:(\\d)*/jaxws-samples-wsse-policy-trust-bearer/BearerService", + "https://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-bearer/BearerService", + "https://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-bearer/BearerService" + )); + services.add(service); + + TokenIssueOperation issueOperation = new TokenIssueOperation(); + issueOperation.getTokenProviders().add(new SAMLTokenProvider()); + issueOperation.setServices(services); + issueOperation.setStsProperties(props); + this.setIssueOperation(issueOperation); + } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-STSBearerCallbackHandler"> + + <title>STSBearerCallbackHandler</title> + <para>STSBearerCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.stsbearer; + +import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler; + +import java.util.HashMap; +import java.util.Map; + +public class STSBearerCallbackHandler extends PasswordCallbackHandler +{ + public STSBearerCallbackHandler() + { + super(getInitMap()); + } + + private static Map&lt;String, String&gt; getInitMap() + { + Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;(); + passwords.put("mystskey", "stskpass"); + passwords.put("alice", "clarinet"); + return passwords; + } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-Cryptopropertiesandkeystorefilesx"> + + <title>Crypto properties and keystore files</title> + <para>WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data. The file contains implementation-specific properties such as a keystore location, password, default alias and the like. This application is using the Merlin implementation. File stsKeystore.properties contains this information.</para> + <para> + File servicestore.jks, is a Java KeyStore (JKS) repository. It contains self signed certificates for myservicekey and mystskey. + <emphasis role="italics">Self signed certificates are not appropriate for production use.</emphasis> + </para> + <informalexample> + <programlisting> +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin   +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=stsspass +org.apache.ws.security.crypto.merlin.keystore.file=stsstore.jks +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-MANIFEST.MFx"> + + <title>MANIFEST.MF</title> + <para> + When deployed on WildFly, this application requires access to the JBossWs and CXF APIs provided in modules org.jboss.ws.cxf.jbossws-cxf-client and org.apache.cxf. The Apache CXF internals, org.apache.cxf.impl, are needed to build the STS configuration in the + <code>SampleSTS</code> + constructor. The dependency statement directs the server to provide them at deployment. + </para> + <informalexample> + <programlisting> +Manifest-Version: 1.0   +Ant-Version: Apache Ant 1.8.2   +Created-By: 1.7.0_25-b15 (Oracle Corporation)   +Dependencies: org.jboss.ws.cxf.jbossws-cxf-client,org.apache.cxf.impl +</programlisting> + </informalexample> + </section> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-Webservicerequester"> + + <title>Web service requester</title> + <para>This section examines the crucial elements in calling a web service that implements endpoint security as described in the SAML Bearer scenario. The components that will be discussed are.</para> + <itemizedlist> + <listitem> + <para>Web service requester's implementation</para> + </listitem> + <listitem> + <para>ClientCallbackHandler</para> + </listitem> + <listitem> + <para>Crypto properties and keystore files</para> + </listitem> + </itemizedlist> + <section id="sid-78906786_SAMLBearerAssertionScenario-WebservicerequesterImplementation"> + + <title>Web service requester Implementation</title> + <para>The ws-requester, the client, uses standard procedures for creating a reference to the web service. To address the endpoint security requirements, the web service's "Request Context" is configured with the information needed in message generation. In addition, the STSClient that communicates with the STS is configured with similar values. Note the key strings ending with a ".it" suffix. This suffix flags these settings as belonging to the STSClient. The internal CXF code assigns this information to the STSClient that is auto-generated for this service call.</para> + <para>There is an alternate method of setting up the STSCLient. The user may provide their own instance of the STSClient. The CXF code will use this object and not auto-generate one. When providing the STSClient in this way, the user must provide a org.apache.cxf.Bus for it and the configuration keys must not have the ".it" suffix. This is used in the ActAs and OnBehalfOf examples.</para> + <informalexample> + <programlisting> + String serviceURL = "https://" + getServerHost() + ":8443/jaxws-samples-wsse-policy-trust-bearer/BearerService"; + + final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/bearerwssecuritypo...;, "BearerService"); + Service service = Service.create(new URL(serviceURL + "?wsdl"), serviceName); + BearerIface proxy = (BearerIface) service.getPort(BearerIface.class); + + Map&lt;String, Object&gt; ctx = ((BindingProvider)proxy).getRequestContext(); + + // set the security related configuration information for the service "request" + ctx.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler()); + ctx.put(SecurityConstants.SIGNATURE_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myclientkey"); + ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myservicekey"); + + //-- Configuration settings that will be transfered to the STSClient + // "alice" is the name provided for the WSS Username. Her password will + // be retreived from the ClientCallbackHander by the STSClient. + ctx.put(SecurityConstants.USERNAME + ".it", "alice"); + ctx.put(SecurityConstants.CALLBACK_HANDLER + ".it", new ClientCallbackHandler()); + ctx.put(SecurityConstants.ENCRYPT_PROPERTIES + ".it", + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.ENCRYPT_USERNAME + ".it", "mystskey"); + ctx.put(SecurityConstants.STS_TOKEN_USERNAME + ".it", "myclientkey"); + ctx.put(SecurityConstants.STS_TOKEN_PROPERTIES + ".it", + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); + ctx.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO + ".it", "true"); + + proxy.sayHello(); + +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-ClientCallbackHandler"> + + <title>ClientCallbackHandler</title> + <para> + <ulink url="https://docs.jboss.org/author/display/JBWS/WS-Trust+and+STS#WS-... + </para> + <para>ClientCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature. Note that "alice" and her password have been provided here. This information is not in the (JKS) keystore but provided in the WildFly security domain. It was declared in file jbossws-users.properties.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared; + +import java.io.IOException; +import javax.security.auth.callback.Callback; +import javax.security.auth.callback.CallbackHandler; +import javax.security.auth.callback.UnsupportedCallbackException; +import org.apache.ws.security.WSPasswordCallback; + +public class ClientCallbackHandler implements CallbackHandler { + +    public void handle(Callback[] callbacks) throws IOException, +            UnsupportedCallbackException { +        for (int i = 0; i &lt; callbacks.length; i++) { +            if (callbacks[i] instanceof WSPasswordCallback) { +                WSPasswordCallback pc = (WSPasswordCallback) callbacks[i]; +                if ("myclientkey".equals(pc.getIdentifier())) { +                    pc.setPassword("ckpass"); +                    break; +                } else if ("alice".equals(pc.getIdentifier())) { +                    pc.setPassword("clarinet"); +                    break; +                } else if ("bob".equals(pc.getIdentifier())) { +                    pc.setPassword("trombone"); +                    break; +                } else if ("myservicekey".equals(pc.getIdentifier())) {  // rls test  added for bearer test +                   pc.setPassword("skpass"); +                   break; +                } +            } +        } +    } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906786_SAMLBearerAssertionScenario-Cryptopropertiesandkeystorefilesxx"> + + <title>Crypto properties and keystore files</title> + <para> + <ulink url="https://docs.jboss.org/author/display/JBWS/WS-Trust+and+STS#WS-... + </para> + <para>WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data. The file contains implementation-specific properties such as a keystore location, password, default alias and the like. This application is using the Merlin implementation. File clientKeystore.properties contains this information.</para> + <para> + File clientstore.jks, is a Java KeyStore (JKS) repository. It contains self signed certificates for myservicekey and mystskey. + <emphasis role="italics">Self signed certificates are not appropriate for production use.</emphasis> + </para> + <informalexample> + <programlisting> +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=cspass +org.apache.ws.security.crypto.merlin.keystore.alias=myclientkey +org.apache.ws.security.crypto.merlin.keystore.file=META-INF/clientstore.jks +</programlisting> + </informalexample> + </section> + </section> + </section> + <section id="sid-78906915"> + + <title>SAML Holder-Of-Key Assertion Scenario</title> + <para> + WS-Trust deals with managing software security tokens. A SAML assertion is a type of security token. In the Holder-Of-Key method, the STS creates a SAML token containing the client's public key and signs the SAML token with its private key. The client includes the SAML token and signs the outgoing soap envelope to the web service with its private key. The web service validates the SOAP message and the SAML token. + + </para> + <para>Implementation of this scenario has the following requirements.</para> + <itemizedlist> + <listitem> + <para>SAML tokens with a Holder-Of-Key subject confirmation method must be protected so the token can not be snooped. In most cases, a Holder-Of-Key token combined with HTTPS is sufficient to prevent "a man in the middle" getting possession of the token. This means a security policy that uses a sp:TransportBinding and sp:HttpsToken.</para> + </listitem> + <listitem> + <para>A Holder-Of-Key token has no encryption or signing keys associated with it, therefore a sp:IssuedToken of SymmetricKey or PublicKey keyType should be used with a sp:SignedEndorsingSupportingTokens.</para> + </listitem> + </itemizedlist> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-WebserviceProvider"> + + <title>Web service Provider</title> + <para>This section examines the web service elements for the SAML Holder-Of-Key scenario. The components are</para> + <itemizedlist> + <listitem> + <para>Web service provider's WSDL</para> + </listitem> + <listitem> + <para>SSL configuration</para> + </listitem> + <listitem> + <para>Web service provider's Interface and Implementation classes.</para> + </listitem> + <listitem> + <para>Crypto properties and keystore files</para> + </listitem> + <listitem> + <para>MANIFEST.MF</para> + </listitem> + </itemizedlist> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-WebserviceproviderWSDL"> + + <title>Web service provider WSDL</title> + <para>The web service provider is a contract-first endpoint. All the WS-trust and security policies for it are declared in the WSDL, HolderOfKeyService.wsdl. For this scenario a ws-requester is required to present a SAML 2.0 token of SymmetricKey keyType, issued from a designed STS. The address of the STS is provided in the WSDL. A transport binding policy is used. The token is declared to be signed and endorsed, sp:SignedEndorsingSupportingTokens. A detailed explanation of the security settings are provided in the comments in the listing below.</para> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&gt; +&lt;definitions targetNamespace="http://www.jboss.org/jbossws/ws-extensions/holderof... + name="HolderOfKeyService" + xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/holderofkeywss... + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns="http://schemas.xmlsoap.org/wsdl/" + xmlns:wsp="http://www.w3.org/ns/ws-policy" + xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" + xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... + xmlns:wsaws="http://www.w3.org/2005/08/addressing" + xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex" + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + xmlns:t="http://docs.oasis-open.org/ws-sx/ws-trust/200512"&gt; + + &lt;types&gt; + &lt;xsd:schema&gt; + &lt;xsd:import namespace="http://www.jboss.org/jbossws/ws-extensions/holderofkeywss... + schemaLocation="HolderOfKeyService_schema1.xsd"/&gt; + &lt;/xsd:schema&gt; + &lt;/types&gt; + &lt;message name="sayHello"&gt; + &lt;part name="parameters" element="tns:sayHello"/&gt; + &lt;/message&gt; + &lt;message name="sayHelloResponse"&gt; + &lt;part name="parameters" element="tns:sayHelloResponse"/&gt; + &lt;/message&gt; + &lt;portType name="HolderOfKeyIface"&gt; + &lt;operation name="sayHello"&gt; + &lt;input message="tns:sayHello"/&gt; + &lt;output message="tns:sayHelloResponse"/&gt; + &lt;/operation&gt; + &lt;/portType&gt; +&lt;!-- + The wsp:PolicyReference binds the security requirments on all the endpoints. + The wsp:Policy wsu:Id="#TransportSAML2HolderOfKeyPolicy" element is defined later in this file. +--&gt; + &lt;binding name="HolderOfKeyServicePortBinding" type="tns:HolderOfKeyIface"&gt; + &lt;wsp:PolicyReference URI="#TransportSAML2HolderOfKeyPolicy" /&gt; + &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt; + &lt;operation name="sayHello"&gt; + &lt;soap:operation soapAction=""/&gt; + &lt;input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/input&gt; + &lt;output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/output&gt; + &lt;/operation&gt; + &lt;/binding&gt; +&lt;!-- + The soap:address has been defined to use JBoss's https port, 8443. This is + set in conjunction with the sp:TransportBinding policy for https. +--&gt; + &lt;service name="HolderOfKeyService"&gt; + &lt;port name="HolderOfKeyServicePort" binding="tns:HolderOfKeyServicePortBinding"&gt; + &lt;soap:address location="https://@jboss.bind.address@:8443/jaxws-samples-wsse-policy-trust-holderofkey/HolderOfKeyService"/&gt; + &lt;/port&gt; + &lt;/service&gt; + + + &lt;wsp:Policy wsu:Id="TransportSAML2HolderOfKeyPolicy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;!-- + The wsam:Addressing element, indicates that the endpoints of this + web service MUST conform to the WS-Addressing specification. The + attribute wsp:Optional="false" enforces this assertion. + --&gt; + &lt;wsam:Addressing wsp:Optional="false"&gt; + &lt;wsp:Policy /&gt; + &lt;/wsam:Addressing&gt; +&lt;!-- + The sp:TransportBinding element indicates that security is provided by the + message exchange transport medium, https. WS-Security policy specification + defines the sp:HttpsToken for use in exchanging messages transmitted over HTTPS. +--&gt; + &lt;sp:TransportBinding + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:TransportToken&gt; + &lt;wsp:Policy&gt; + &lt;sp:HttpsToken&gt; + &lt;wsp:Policy/&gt; + &lt;/sp:HttpsToken&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:TransportToken&gt; +&lt;!-- + The sp:AlgorithmSuite element, requires the TripleDes algorithm suite + be used in performing cryptographic operations. +--&gt; + &lt;sp:AlgorithmSuite&gt; + &lt;wsp:Policy&gt; + &lt;sp:TripleDes /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:AlgorithmSuite&gt; +&lt;!-- + The sp:Layout element, indicates the layout rules to apply when adding + items to the security header. The sp:Lax sub-element indicates items + are added to the security header in any order that conforms to + WSS: SOAP Message Security. +--&gt; + &lt;sp:Layout&gt; + &lt;wsp:Policy&gt; + &lt;sp:Lax /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Layout&gt; + &lt;sp:IncludeTimestamp /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:TransportBinding&gt; + +&lt;!-- + The sp:SignedEndorsingSupportingTokens, when transport level security level is + used there will be no message signature and the signature generated by the + supporting token will sign the Timestamp. +--&gt; + &lt;sp:SignedEndorsingSupportingTokens + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; +&lt;!-- + The sp:IssuedToken element asserts that a SAML 2.0 security token of type + Bearer is expected from the STS. The + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + attribute instructs the runtime to include the initiator's public key + with every message sent to the recipient. + + The sp:RequestSecurityTokenTemplate element directs that all of the + children of this element will be copied directly into the body of the + RequestSecurityToken (RST) message that is sent to the STS when the + initiator asks the STS to issue a token. +--&gt; + &lt;sp:IssuedToken + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + &lt;sp:RequestSecurityTokenTemplate&gt; + &lt;t:TokenType&gt;http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0&lt;/t:TokenType&gt; + &lt;!-- + KeyType of "SymmetricKey", the client must prove to the WS service that it + possesses a particular symmetric session key. + --&gt; + &lt;t:KeyType&gt;http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey&lt;/t:KeyType&gt; + &lt;/sp:RequestSecurityTokenTemplate&gt; + &lt;wsp:Policy&gt; + &lt;sp:RequireInternalReference /&gt; + &lt;/wsp:Policy&gt; +&lt;!-- + The sp:Issuer element defines the STS's address and endpoint information + This information is used by the STSClient. +--&gt; + &lt;sp:Issuer&gt; + &lt;wsaws:Address&gt;http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-sts-holderofkey/SecurityTokenService&lt;/wsaws:Address&gt; + &lt;wsaws:Metadata + xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance" + wsdli:wsdlLocation="http://@jboss.bind.address@:8080/jaxws-samples-wsse-policy-trust-sts-holderofkey/SecurityTokenService?wsdl"&gt; + &lt;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"&gt;stsns:SecurityTokenService&lt;/wsaw:ServiceName&gt; + &lt;/wsaws:Metadata&gt; + &lt;/sp:Issuer&gt; + + &lt;/sp:IssuedToken&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:SignedEndorsingSupportingTokens&gt; +&lt;!-- + The sp:Wss11 element declares WSS: SOAP Message Security 1.1 options + to be supported by the STS. These particular elements generally refer + to how keys are referenced within the SOAP envelope. These are normally + handled by CXF. +--&gt; + &lt;sp:Wss11&gt; + &lt;wsp:Policy&gt; + &lt;sp:MustSupportRefIssuerSerial /&gt; + &lt;sp:MustSupportRefThumbprint /&gt; + &lt;sp:MustSupportRefEncryptedKey /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Wss11&gt; +&lt;!-- + The sp:Trust13 element declares controls for WS-Trust 1.3 options. + They are policy assertions related to exchanges specifically with + client and server challenges and entropy behaviors. Again these are + normally handled by CXF. +--&gt; + &lt;sp:Trust13&gt; + &lt;wsp:Policy&gt; + &lt;sp:MustSupportIssuedTokens /&gt; + &lt;sp:RequireClientEntropy /&gt; + &lt;sp:RequireServerEntropy /&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Trust13&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + +&lt;/definitions&gt; +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-SSLconfiguration"> + + <title>SSL configuration</title> + <para> + <ulink url="https://docs.jboss.org/author/display/JBWS/WS-Trust+and+STS#WS-... + </para> + <para>This web service is using https, therefore the JBoss server must be configured to provide SSL support in the Web subsystem. There are 2 components to SSL configuration.</para> + <itemizedlist> + <listitem> + <para>create a certificate keystore</para> + </listitem> + <listitem> + <para>declare an SSL connector in the Web subsystem of the JBoss server configuration file.</para> + </listitem> + </itemizedlist> + <para> + Follow the directions in the, " + <emphasis role="italics">Using the pure Java implementation supplied by JSSE</emphasis> + " section in the [SSL Setup Guide|../../../../../../../../../../display/WFLY8/SSL+setup+guide||\||]. + </para> + <para>Here is an example of an SSL connector declaration.</para> + <informalexample> + <programlisting> +&lt;subsystem xmlns="urn:jboss:domain:web:1.4" default-virtual-server="default-host" native="false"&gt; +..... + &lt;connector name="jbws-https-connector" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true" enabled="true"&gt; + &lt;ssl key-alias="tomcat" password="changeit" certificate-key-file="/myJbossHome/security/test.keystore" verify-client="false"/&gt; + &lt;/connector&gt; +... +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-WebserviceInterface"> + + <title>Web service Interface</title> + <para>The web service provider interface class, HolderOfKeyIface, is a simple straight forward web service definition.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.holderofkey; + +import javax.jws.WebMethod; +import javax.jws.WebService; + +@WebService +( + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/holderofkeywssecuritypolicy" +) +public interface HolderOfKeyIface { + @WebMethod + String sayHello(); +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-WebserviceImplementation"> + + <title>Web service Implementation</title> + <para> + The web service provider implementation class, HolderOfKeyImpl, is a simple POJO. It uses the standard WebService annotation to define the service endpoint. In addition there are two Apache CXF annotations, EndpointProperties and EndpointProperty used for configuring the endpoint for the CXF runtime. These annotations come from the + <ulink url="https://ws.apache.org/wss4j/">Apache WSS4J project</ulink> + , which provides a Java implementation of the primary WS-Security standards for Web Services. These annotations are programmatically adding properties to the endpoint. With plain Apache CXF, these properties are often set via the &lt;jaxws:properties&gt; element on the &lt;jaxws:endpoint&gt; element in the Spring config; these annotations allow the properties to be configured in the code. + </para> + <para>WSS4J uses the Crypto interface to get keys and certificates for signature creation/verification, as is asserted by the WSDL for this service. The WSS4J configuration information being provided by HolderOfKeyImpl is for Crypto's Merlin implementation. More information will be provided about this in the keystore section.</para> + <para>The first EndpointProperty statement in the listing disables ensurance of compliance with the Basic Security Profile 1.1. The next EndpointProperty statements declares the Java properties file that contains the (Merlin) crypto configuration information. The last EndpointProperty statement declares the STSHolderOfKeyCallbackHandler implementation class. It is used to obtain the user's password for the certificates in the keystore file.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.holderofkey; + +import org.apache.cxf.annotations.EndpointProperties; +import org.apache.cxf.annotations.EndpointProperty; + +import javax.jws.WebService; + +@WebService + ( + portName = "HolderOfKeyServicePort", + serviceName = "HolderOfKeyService", + wsdlLocation = "WEB-INF/wsdl/HolderOfKeyService.wsdl", + targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/holderofkeywssecuritypolicy", + endpointInterface = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.holderofkey.HolderOfKeyIface" + ) +@EndpointProperties(value = { + @EndpointProperty(key = "ws-security.is-bsp-compliant", value = "false"), + @EndpointProperty(key = "ws-security.signature.properties", value = "serviceKeystore.properties"), + @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.holderofkey.HolderOfKeyCallbackHandler") +}) +public class HolderOfKeyImpl implements HolderOfKeyIface +{ + public String sayHello() + { + return "Holder-Of-Key WS-Trust Hello World!"; + } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-Cryptopropertiesandkeystorefiles"> + + <title>Crypto properties and keystore files</title> + <para>WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data. The file contains implementation-specific properties such as a keystore location, password, default alias and the like. This application is using the Merlin implementation. File serviceKeystore.properties contains this information.</para> + <para> + File servicestore.jks, is a Java KeyStore (JKS) repository. It contains self signed certificates for myservicekey and mystskey. + <emphasis role="italics">Self signed certificates are not appropriate for production use.</emphasis> + </para> + <informalexample> + <programlisting> +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=sspass +org.apache.ws.security.crypto.merlin.keystore.alias=myservicekey +org.apache.ws.security.crypto.merlin.keystore.file=servicestore.jks +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-MANIFEST.MF"> + + <title>MANIFEST.MF</title> + <para> + <ulink url="https://docs.jboss.org/author/display/JBWS/WS-Trust+and+STS#WS-... + </para> + <para>When deployed on WildFly this application requires access to the JBossWs and CXF APIs provided in module org.jboss.ws.cxf.jbossws-cxf-client. The dependency statement directs the server to provide them at deployment.</para> + <informalexample> + <programlisting> +Manifest-Version:1.0 +Ant-Version: Apache Ant1.8.2 +Created-By:1.7.0_25-b15 (Oracle Corporation) +Dependencies: org.jboss.ws.cxf.jbossws-cxf-client +</programlisting> + </informalexample> + </section> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-SecurityTokenService"> + + <title>Security Token Service</title> + <para>This section examines the crucial elements in providing the Security Token Service functionality for providing a SAML Holder-Of-Key token. The components that will be discussed are.</para> + <itemizedlist> + <listitem> + <para>Security Domain</para> + </listitem> + <listitem> + <para>STS's WSDL</para> + </listitem> + <listitem> + <para>STS's implementation class</para> + </listitem> + <listitem> + <para>STSBearerCallbackHandler</para> + </listitem> + <listitem> + <para>Crypto properties and keystore files</para> + </listitem> + <listitem> + <para>MANIFEST.MF</para> + </listitem> + </itemizedlist> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-SecurityDomain"> + + <title>Security Domain</title> + <para>The STS requires a JBoss security domain be configured. The jboss-web.xml descriptor declares a named security domain,"JBossWS-trust-sts" to be used by this service for authentication. This security domain requires two properties files and the addition of a security-domain declaration in the JBoss server configuration file.</para> + <para> + For this scenario the domain needs to contain user + <emphasis role="italics">alice</emphasis> + , password + <emphasis role="italics">clarinet</emphasis> + , and role + <emphasis role="italics">friend</emphasis> + . See the listings below for jbossws-users.properties and jbossws-roles.properties. In addition the following XML must be added to the JBoss security subsystem in the server configuration file. Replace " + <emphasis role="strong">SOME_PATH</emphasis> + " with appropriate information. + </para> + <informalexample> + <programlisting> +&lt;security-domain name="JBossWS-trust-sts"&gt; + &lt;authentication&gt; +  &lt;login-module code="UsersRoles" flag="required"&gt; +  &lt;module-option name="usersProperties" value="/SOME_PATH/jbossws-users.properties"/&gt; +  &lt;module-option name="unauthenticatedIdentity" value="anonymous"/&gt; +  &lt;module-option name="rolesProperties" value="/SOME_PATH/jbossws-roles.properties"/&gt; +  &lt;/login-module&gt; +  &lt;/authentication&gt; +&lt;/security-domain&gt; +</programlisting> + </informalexample> + <para>jboss-web.xml</para> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;!DOCTYPE jboss-web PUBLIC"-//JBoss//DTD Web Application 2.4//EN" "&gt; +&lt;jboss-web&gt; + &lt;security-domain&gt;java:/jaas/JBossWS-trust-sts&lt;/security-domain&gt; +&lt;/jboss-web&gt; +</programlisting> + </informalexample> + <informaltable> + <tgroup cols="1"> + <tbody> + <row> + <entry> + <para> + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>jbossws-users.properties</para> + <informalexample> + <programlisting> +# A sample users.properties filefor use with the UsersRolesLoginModule +alice=clarinet +</programlisting> + </informalexample> + <informaltable> + <tgroup cols="1"> + <tbody> + <row> + <entry> + <para> </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>jbossws-roles.properties</para> + <informalexample> + <programlisting> +# A sample roles.properties filefor use with the UsersRolesLoginModule +alice=friend +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-STS%27sWSDL"> + + <title>STS's WSDL</title> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;wsdl:definitions + targetNamespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512/&q... + xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/" + xmlns:wstrust="http://docs.oasis-open.org/ws-sx/ws-trust/200512/" + xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns:wsap10="http://www.w3.org/2006/05/addressing/wsdl" + xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... + xmlns:wsp="http://www.w3.org/ns/ws-policy" + xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"&gt; + + &lt;wsdl:types&gt; + &lt;xs:schema elementFormDefault="qualified" + targetNamespace='http://docs.oasis-open.org/ws-sx/ws-trust/200512'... + + &lt;xs:element name='RequestSecurityToken' + type='wst:AbstractRequestSecurityTokenType'/&gt; + &lt;xs:element name='RequestSecurityTokenResponse' + type='wst:AbstractRequestSecurityTokenType'/&gt; + + &lt;xs:complexType name='AbstractRequestSecurityTokenType'&gt; + &lt;xs:sequence&gt; + &lt;xs:any namespace='##any' processContents='lax' minOccurs='0' + maxOccurs='unbounded'/&gt; + &lt;/xs:sequence&gt; + &lt;xs:attribute name='Context' type='xs:anyURI' use='optional'/&gt; + &lt;xs:anyAttribute namespace='##other' processContents='lax'/&gt; + &lt;/xs:complexType&gt; + &lt;xs:element name='RequestSecurityTokenCollection' + type='wst:RequestSecurityTokenCollectionType'/&gt; + &lt;xs:complexType name='RequestSecurityTokenCollectionType'&gt; + &lt;xs:sequence&gt; + &lt;xs:element name='RequestSecurityToken' + type='wst:AbstractRequestSecurityTokenType' minOccurs='2' + maxOccurs='unbounded'/&gt; + &lt;/xs:sequence&gt; + &lt;/xs:complexType&gt; + + &lt;xs:element name='RequestSecurityTokenResponseCollection' + type='wst:RequestSecurityTokenResponseCollectionType'/&gt; + &lt;xs:complexType name='RequestSecurityTokenResponseCollectionType'&gt; + &lt;xs:sequence&gt; + &lt;xs:element ref='wst:RequestSecurityTokenResponse' minOccurs='1' + maxOccurs='unbounded'/&gt; + &lt;/xs:sequence&gt; + &lt;xs:anyAttribute namespace='##other' processContents='lax'/&gt; + &lt;/xs:complexType&gt; + + &lt;/xs:schema&gt; + &lt;/wsdl:types&gt; + + &lt;!-- WS-Trust defines the following GEDs --&gt; + &lt;wsdl:message name="RequestSecurityTokenMsg"&gt; + &lt;wsdl:part name="request" element="wst:RequestSecurityToken"/&gt; + &lt;/wsdl:message&gt; + &lt;wsdl:message name="RequestSecurityTokenResponseMsg"&gt; + &lt;wsdl:part name="response" + element="wst:RequestSecurityTokenResponse"/&gt; + &lt;/wsdl:message&gt; + &lt;wsdl:message name="RequestSecurityTokenCollectionMsg"&gt; + &lt;wsdl:part name="requestCollection" + element="wst:RequestSecurityTokenCollection"/&gt; + &lt;/wsdl:message&gt; + &lt;wsdl:message name="RequestSecurityTokenResponseCollectionMsg"&gt; + &lt;wsdl:part name="responseCollection" + element="wst:RequestSecurityTokenResponseCollection"/&gt; + &lt;/wsdl:message&gt; + + &lt;!-- This portType an example of a Requestor (or other) endpoint that + Accepts SOAP-based challenges from a Security Token Service --&gt; + &lt;wsdl:portType name="WSSecurityRequestor"&gt; + &lt;wsdl:operation name="Challenge"&gt; + &lt;wsdl:input message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;wsdl:output message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:portType&gt; + + &lt;!-- This portType is an example of an STS supporting full protocol --&gt; + &lt;wsdl:portType name="STS"&gt; + &lt;wsdl:operation name="Cancel"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Ca... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/C... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Issue"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Is... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/... + message="tns:RequestSecurityTokenResponseCollectionMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Renew"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Re... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/R... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Validate"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Va... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/V... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="KeyExchangeToken"&gt; + &lt;wsdl:input + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/KE... + message="tns:RequestSecurityTokenMsg"/&gt; + &lt;wsdl:output + wsam:Action="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/K... + message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="RequestCollection"&gt; + &lt;wsdl:input message="tns:RequestSecurityTokenCollectionMsg"/&gt; + &lt;wsdl:output message="tns:RequestSecurityTokenResponseCollectionMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:portType&gt; + + &lt;!-- This portType is an example of an endpoint that accepts + Unsolicited RequestSecurityTokenResponse messages --&gt; + &lt;wsdl:portType name="SecurityTokenResponseService"&gt; + &lt;wsdl:operation name="RequestSecurityTokenResponse"&gt; + &lt;wsdl:input message="tns:RequestSecurityTokenResponseMsg"/&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:portType&gt; + + &lt;wsdl:binding name="UT_Binding" type="wstrust:STS"&gt; + &lt;wsp:PolicyReference URI="#UT_policy"/&gt; + &lt;soap:binding style="document" + transport="http://schemas.xmlsoap.org/soap/http"/&gt; + &lt;wsdl:operation name="Issue"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Iss... + &lt;wsdl:input&gt; + &lt;wsp:PolicyReference + URI="#Input_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;wsp:PolicyReference + URI="#Output_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Validate"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Val... + &lt;wsdl:input&gt; + &lt;wsp:PolicyReference + URI="#Input_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;wsp:PolicyReference + URI="#Output_policy"/&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Cancel"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Can... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="Renew"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Ren... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="KeyExchangeToken"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Key... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;wsdl:operation name="RequestCollection"&gt; + &lt;soap:operation + soapAction="http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Req... + &lt;wsdl:input&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:input&gt; + &lt;wsdl:output&gt; + &lt;soap:body use="literal"/&gt; + &lt;/wsdl:output&gt; + &lt;/wsdl:operation&gt; + &lt;/wsdl:binding&gt; + + &lt;wsdl:service name="SecurityTokenService"&gt; + &lt;wsdl:port name="UT_Port" binding="tns:UT_Binding"&gt; + &lt;soap:address location="http://localhost:8080/SecurityTokenService/UT"/&gt; + &lt;/wsdl:port&gt; + &lt;/wsdl:service&gt; + + &lt;wsp:Policy wsu:Id="UT_policy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;wsap10:UsingAddressing/&gt; + &lt;sp:SymmetricBinding + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:ProtectionToken&gt; + &lt;wsp:Policy&gt; + &lt;sp:X509Token + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + &lt;wsp:Policy&gt; + &lt;sp:RequireDerivedKeys/&gt; + &lt;sp:RequireThumbprintReference/&gt; + &lt;sp:WssX509V3Token10/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:X509Token&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:ProtectionToken&gt; + &lt;sp:AlgorithmSuite&gt; + &lt;wsp:Policy&gt; + &lt;sp:Basic256/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:AlgorithmSuite&gt; + &lt;sp:Layout&gt; + &lt;wsp:Policy&gt; + &lt;sp:Lax/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Layout&gt; + &lt;sp:IncludeTimestamp/&gt; + &lt;sp:EncryptSignature/&gt; + &lt;sp:OnlySignEntireHeadersAndBody/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:SymmetricBinding&gt; + &lt;sp:SignedSupportingTokens + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:UsernameToken + sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/... + &lt;wsp:Policy&gt; + &lt;sp:WssUsernameToken10/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:UsernameToken&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:SignedSupportingTokens&gt; + &lt;sp:Wss11 + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:MustSupportRefKeyIdentifier/&gt; + &lt;sp:MustSupportRefIssuerSerial/&gt; + &lt;sp:MustSupportRefThumbprint/&gt; + &lt;sp:MustSupportRefEncryptedKey/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Wss11&gt; + &lt;sp:Trust13 + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;wsp:Policy&gt; + &lt;sp:MustSupportIssuedTokens/&gt; + &lt;sp:RequireClientEntropy/&gt; + &lt;sp:RequireServerEntropy/&gt; + &lt;/wsp:Policy&gt; + &lt;/sp:Trust13&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + + &lt;wsp:Policy wsu:Id="Input_policy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;sp:SignedParts + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;sp:Body/&gt; + &lt;sp:Header Name="To" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="From" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="FaultTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="ReplyTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="MessageID" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="RelatesTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="Action" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;/sp:SignedParts&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + + &lt;wsp:Policy wsu:Id="Output_policy"&gt; + &lt;wsp:ExactlyOne&gt; + &lt;wsp:All&gt; + &lt;sp:SignedParts + xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702&... + &lt;sp:Body/&gt; + &lt;sp:Header Name="To" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="From" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="FaultTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="ReplyTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="MessageID" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="RelatesTo" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;sp:Header Name="Action" + Namespace="http://www.w3.org/2005/08/addressing"/&gt; + &lt;/sp:SignedParts&gt; + &lt;/wsp:All&gt; + &lt;/wsp:ExactlyOne&gt; + &lt;/wsp:Policy&gt; + +&lt;/wsdl:definitions&gt; +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-STS%27simplementationclass"> + + <title>STS's implementation class</title> + <para> + The Apache CXF's STS, SecurityTokenServiceProvider, is a web service provider that is compliant with the protocols and functionality defined by the WS-Trust specification. It has a modular architecture. Many of its components are configurable or replaceable and there are many optional features that are enabled by implementing and configuring plug-ins. Users can customize their own STS by extending from SecurityTokenServiceProvider and overriding the default settings. Extensive information about the CXF's STS configurable and pluggable components can be found + <ulink url="http://coheigea.blogspot.com/2011/11/apache-cxf-sts-documentati... + . + </para> + <para>This STS implementation class, SampleSTSHolderOfKey, is a POJO that extends from SecurityTokenServiceProvider. Note that the class is defined with a WebServiceProvider annotation and not a WebService annotation. This annotation defines the service as a Provider-based endpoint, meaning it supports a more messaging-oriented approach to Web services. In particular, it signals that the exchanged messages will be XML documents of some type. SecurityTokenServiceProvider is an implementation of the javax.xml.ws.Provider interface. In comparison the WebService annotation defines a (service endpoint interface) SEI-based endpoint which supports message exchange via SOAP envelopes.</para> + <para>As was done in the HolderOfKeyImpl class, the WSS4J annotations EndpointProperties and EndpointProperty are providing endpoint configuration for the CXF runtime. The first EndpointProperty statements declares the Java properties file that contains the (Merlin) crypto configuration information. WSS4J reads this file and extra required information for message handling. The last EndpointProperty statement declares the STSHolderOfKeyCallbackHandler implementation class. It is used to obtain the user's password for the certificates in the keystore file.</para> + <para>In this implementation we are customizing the operations of token issuance and their static properties.</para> + <para>StaticSTSProperties is used to set select properties for configuring resources in the STS. You may think this is a duplication of the settings made with the WSS4J annotations. The values are the same but the underlaying structures being set are different, thus this information must be declared in both places.</para> + <para>The setIssuer setting is important because it uniquely identifies the issuing STS. The issuer string is embedded in issued tokens and, when validating tokens, the STS checks the issuer string value. Consequently, it is important to use the issuer string in a consistent way, so that the STS can recognize the tokens that it has issued.</para> + <para>The setEndpoints call allows the declaration of a set of allowed token recipients by address. The addresses are specified as reg-ex patterns.</para> + <para>TokenIssueOperation has a modular structure. This allows custom behaviors to be injected into the processing of messages. In this case we are overriding the SecurityTokenServiceProvider's default behavior and performing SAML token processing. CXF provides an implementation of a SAMLTokenProvider which we are using rather than writing our own.</para> + <para> + Learn more about the SAMLTokenProvider + <ulink url="http://coheigea.blogspot.it/2011/10/apache-cxf-sts-documentation-part-iv.html">here</ulink> + . + </para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.stsholderofkey; + +import org.apache.cxf.annotations.EndpointProperties; +import org.apache.cxf.annotations.EndpointProperty; +import org.apache.cxf.sts.StaticSTSProperties; +import org.apache.cxf.sts.operation.TokenIssueOperation; +import org.apache.cxf.sts.service.ServiceMBean; +import org.apache.cxf.sts.service.StaticService; +import org.apache.cxf.sts.token.provider.SAMLTokenProvider; +import org.apache.cxf.ws.security.sts.provider.SecurityTokenServiceProvider; + +import javax.xml.ws.WebServiceProvider; +import java.util.Arrays; +import java.util.LinkedList; +import java.util.List; + +/** + * User: rsearls + * Date: 3/14/14 + */ +@WebServiceProvider(serviceName = "SecurityTokenService", + portName = "UT_Port", + targetNamespace = "http://docs.oasis-open.org/ws-sx/ws-trust/200512/", + wsdlLocation = "WEB-INF/wsdl/holderofkey-ws-trust-1.4-service.wsdl") +//be sure to have dependency on org.apache.cxf module when on AS7, otherwise Apache CXF annotations are ignored +@EndpointProperties(value = { + @EndpointProperty(key = "ws-security.signature.properties", value = "stsKeystore.properties"), + @EndpointProperty(key = "ws-security.callback-handler", value = "org.jboss.test.ws.jaxws.samples.wsse.policy.trust.stsholderofkey.STSHolderOfKeyCallbackHandler") +}) +public class SampleSTSHolderOfKey extends SecurityTokenServiceProvider +{ + + public SampleSTSHolderOfKey() throws Exception + { + super(); + + StaticSTSProperties props = new StaticSTSProperties(); + props.setSignatureCryptoProperties("stsKeystore.properties"); + props.setSignatureUsername("mystskey"); + props.setCallbackHandlerClass(STSHolderOfKeyCallbackHandler.class.getName()); + props.setEncryptionCryptoProperties("stsKeystore.properties"); + props.setEncryptionUsername("myservicekey"); + props.setIssuer("DoubleItSTSIssuer"); + + List&lt;ServiceMBean&gt; services = new LinkedList&lt;ServiceMBean&gt;(); + StaticService service = new StaticService(); + service.setEndpoints(Arrays.asList( + "https://localhost:(\\d)*/jaxws-samples-wsse-policy-trust-holderofkey/HolderOfKeyService", + "https://\\[::1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-holderofkey/HolderOfKeyService", + "https://\\[0:0:0:0:0:0:0:1\\]:(\\d)*/jaxws-samples-wsse-policy-trust-holderofkey/HolderOfKeyService" + )); + + services.add(service); + + TokenIssueOperation issueOperation = new TokenIssueOperation(); + issueOperation.getTokenProviders().add(new SAMLTokenProvider()); + issueOperation.setServices(services); + issueOperation.setStsProperties(props); + this.setIssueOperation(issueOperation); + + } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-HolderOfKeyCallbackHandler"> + + <title>HolderOfKeyCallbackHandler</title> + <para>STSHolderOfKeyCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.stsholderofkey; + +import org.jboss.wsf.stack.cxf.extensions.security.PasswordCallbackHandler; + +import java.util.HashMap; +import java.util.Map; + +/** + * User: rsearls + * Date: 3/19/14 + */ +public class STSHolderOfKeyCallbackHandler extends PasswordCallbackHandler +{ + public STSHolderOfKeyCallbackHandler() + { + super(getInitMap()); + } + + private static Map&lt;String, String&gt; getInitMap() + { + Map&lt;String, String&gt; passwords = new HashMap&lt;String, String&gt;(); + passwords.put("mystskey", "stskpass"); + passwords.put("alice", "clarinet"); + return passwords; + } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-Cryptopropertiesandkeystorefilesx"> + + <title>Crypto properties and keystore files</title> + <para>WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data. The file contains implementation-specific properties such as a keystore location, password, default alias and the like. This application is using the Merlin implementation. File stsKeystore.properties contains this information.</para> + <para> + File servicestore.jks, is a Java KeyStore (JKS) repository. It contains self signed certificates for myservicekey and mystskey. + <emphasis role="italics">Self signed certificates are not appropriate for production use.</emphasis> + </para> + <informalexample> + <programlisting> +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=stsspass +org.apache.ws.security.crypto.merlin.keystore.file=stsstore.jks +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-MANIFEST.MFx"> + + <title>MANIFEST.MF</title> + <para>When deployed on WildFly, this application requires access to the JBossWs and CXF APIs provided in modules org.jboss.ws.cxf.jbossws-cxf-client and org.apache.cxf. The Apache CXF internals, org.apache.cxf.impl, are needed to build the STS configuration in the SampleSTSHolderOfKey constructor. The dependency statement directs the server to provide them at deployment.</para> + <informalexample> + <programlisting> +Manifest-Version:1.0 +Ant-Version: Apache Ant1.8.2 +Created-By:1.7.0_25-b15 (Oracle Corporation) +Dependencies: org.jboss.ws.cxf.jbossws-cxf-client,org.apache.cxf.impl +</programlisting> + </informalexample> + </section> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-Webservicerequester"> + + <title>Web service requester</title> + <para>This section examines the crucial elements in calling a web service that implements endpoint security as described in the SAML Holder-Of-Key scenario. The components that will be discussed are.</para> + <itemizedlist> + <listitem> + <para>web service requester's implementation</para> + </listitem> + <listitem> + <para>ClientCallbackHandler</para> + </listitem> + <listitem> + <para>Crypto properties and keystore files</para> + </listitem> + </itemizedlist> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-WebservicerequesterImplementation"> + + <title>Web service requester Implementation</title> + <para>The ws-requester, the client, uses standard procedures for creating a reference to the web service. To address the endpoint security requirements, the web service's "Request Context" is configured with the information needed in message generation. In addition, the STSClient that communicates with the STS is configured with similar values. Note the key strings ending with a ".it" suffix. This suffix flags these settings as belonging to the STSClient. The internal CXF code assigns this information to the STSClient that is auto-generated for this service call.</para> + <para>There is an alternate method of setting up the STSCLient. The user may provide their own instance of the STSClient. The CXF code will use this object and not auto-generate one. When providing the STSClient in this way, the user must provide a org.apache.cxf.Bus for it and the configuration keys must not have the ".it" suffix. This is used in the ActAs and OnBehalfOf examples.</para> + <informalexample> + <programlisting> +String serviceURL = "https://" + getServerHost() + ":8443/jaxws-samples-wsse-policy-trust-holderofkey/HolderOfKeyService"; + +final QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/holderofkeywssecur...;, "HolderOfKeyService"); +final URL wsdlURL = new URL(serviceURL + "?wsdl"); +Service service = Service.create(wsdlURL, serviceName); +HolderOfKeyIface proxy = (HolderOfKeyIface) service.getPort(HolderOfKeyIface.class); + +Map&lt;String, Object&gt; ctx = ((BindingProvider)proxy).getRequestContext(); + +// set the security related configuration information for the service "request" +ctx.put(SecurityConstants.CALLBACK_HANDLER, new ClientCallbackHandler()); +ctx.put(SecurityConstants.SIGNATURE_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); +ctx.put(SecurityConstants.ENCRYPT_PROPERTIES, + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); +ctx.put(SecurityConstants.SIGNATURE_USERNAME, "myclientkey"); +ctx.put(SecurityConstants.ENCRYPT_USERNAME, "myservicekey"); + +//-- Configuration settings that will be transfered to the STSClient +// "alice" is the name provided for the WSS Username. Her password will +// be retreived from the ClientCallbackHander by the STSClient. +ctx.put(SecurityConstants.USERNAME + ".it", "alice"); +ctx.put(SecurityConstants.CALLBACK_HANDLER + ".it", new ClientCallbackHandler()); +ctx.put(SecurityConstants.ENCRYPT_PROPERTIES + ".it", + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); +ctx.put(SecurityConstants.ENCRYPT_USERNAME + ".it", "mystskey"); +ctx.put(SecurityConstants.STS_TOKEN_USERNAME + ".it", "myclientkey"); +ctx.put(SecurityConstants.STS_TOKEN_PROPERTIES + ".it", + Thread.currentThread().getContextClassLoader().getResource( + "META-INF/clientKeystore.properties")); +ctx.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO + ".it", "true"); + +proxy.sayHello(); +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-ClientCallbackHandler"> + + <title>ClientCallbackHandler</title> + <para>ClientCallbackHandler is a callback handler for the WSS4J Crypto API. It is used to obtain the password for the private key in the keystore. This class enables CXF to retrieve the password of the user name to use for the message signature. Note that "alice" and her password have been provided here. This information is not in the (JKS) keystore but provided in the WildFly security domain. It was declared in file jbossws-users.properties.</para> + <informalexample> + <programlisting> +package org.jboss.test.ws.jaxws.samples.wsse.policy.trust.shared; + +import java.io.IOException; +import javax.security.auth.callback.Callback; +import javax.security.auth.callback.CallbackHandler; +import javax.security.auth.callback.UnsupportedCallbackException; +import org.apache.ws.security.WSPasswordCallback; + +public class ClientCallbackHandler implements CallbackHandler { + +    public void handle(Callback[] callbacks) throws IOException, +            UnsupportedCallbackException { +        for (int i = 0; i &lt; callbacks.length; i++) { +            if (callbacks[i] instanceof WSPasswordCallback) { +                WSPasswordCallback pc = (WSPasswordCallback) callbacks[i]; +                if ("myclientkey".equals(pc.getIdentifier())) { +                    pc.setPassword("ckpass"); +                    break; +                } else if ("alice".equals(pc.getIdentifier())) { +                    pc.setPassword("clarinet"); +                    break; +                } else if ("bob".equals(pc.getIdentifier())) { +                    pc.setPassword("trombone"); +                    break; +                } else if ("myservicekey".equals(pc.getIdentifier())) {  // rls test  added for bearer test +                   pc.setPassword("skpass"); +                   break; +                } +            } +        } +    } +} +</programlisting> + </informalexample> + </section> + <section id="sid-78906915_SAMLHolder-Of-KeyAssertionScenario-Cryptopropertiesandkeystorefilesxx"> + + <title>Crypto properties and keystore files</title> + <para>WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data. The file contains implementation-specific properties such as a keystore location, password, default alias and the like. This application is using the Merlin implementation. File clientKeystore.properties contains this information.</para> + <para> + File clientstore.jks, is a Java KeyStore (JKS) repository. It contains self signed certificates for myservicekey and mystskey. + <emphasis role="italics">Self signed certificates are not appropriate for production use.</emphasis> + </para> + <informalexample> + <programlisting> +org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin +org.apache.ws.security.crypto.merlin.keystore.type=jks +org.apache.ws.security.crypto.merlin.keystore.password=cspass +org.apache.ws.security.crypto.merlin.keystore.alias=myclientkey +org.apache.ws.security.crypto.merlin.keystore.file=META-INF/clientstore.jks +</programlisting> + </informalexample> + </section> + </section> + </section> </section> <section id="sid-3866797"> @@ -5725,95 +8348,116 @@ <section id="sid-3866797_WS-ReliableMessaging-Additionalconfiguration"> <title>Additional configuration</title> - <para> - Fine-grained tuning of WS-Reliable Messaging engine requires setting up proper RM features in the - <code>Bus</code> - using a Spring XML descriptor; here is an example: - </para> + <para>Fine-grained tuning of WS-Reliable Messaging engine requires setting up proper RM features and attach them for instance to the client proxy. Here is an example:</para> <informalexample> <programlisting> -&lt;beans - xmlns="http://www.springframework.org/schema/beans" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xmlns:cxf="http://cxf.apache.org/core" - xmlns:wsa="http://cxf.apache.org/ws/addressing" - xmlns:http="http://cxf.apache.org/transports/http/configuration" - xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy&q... - xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager" - xsi:schemaLocation=" - http://cxf.apache.org/core - http://cxf.apache.org/schemas/core.xsd - http://cxf.apache.org/transports/http/configuration - http://cxf.apache.org/schemas/configuration/http-conf.xsd - http://schemas.xmlsoap.org/ws/2005/02/rm/policy - http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd - http://cxf.apache.org/ws/rm/manager - http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd - http://www.springframework.org/schema/beans - http://www.springframework.org/schema/beans/spring-beans.xsd"&gt; +package org.jboss.test.ws.jaxws.samples.wsrm.client; - &lt;cxf:bus&gt; - &lt;cxf:features&gt; - &lt;cxf:logging/&gt; - &lt;wsa:addressing/&gt; - &lt;wsrm-mgr:reliableMessaging&gt; - &lt;wsrm-policy:RMAssertion&gt; - &lt;wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/&gt; - &lt;wsrm-policy:AcknowledgementInterval Milliseconds="2000"/&gt; - &lt;/wsrm-policy:RMAssertion&gt; - &lt;wsrm-mgr:destinationPolicy&gt; - &lt;wsrm-mgr:acksPolicy intraMessageThreshold="0" /&gt; - &lt;/wsrm-mgr:destinationPolicy&gt; - &lt;/wsrm-mgr:reliableMessaging&gt; - &lt;/cxf:features&gt; - &lt;/cxf:bus&gt; -&lt;/beans +//... +import javax.xml.ws.Service; +import org.apache.cxf.ws.rm.feature.RMFeature; +import org.apache.cxf.ws.rm.manager.AcksPolicyType; +import org.apache.cxf.ws.rm.manager.DestinationPolicyType; +import org.apache.cxf.ws.rmp.v200502.RMAssertion; +import org.apache.cxf.ws.rmp.v200502.RMAssertion.AcknowledgementInterval; +import org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService; + +//... +Service service = Service.create(wsdlURL, serviceName); + +RMFeature feature = new RMFeature(); +RMAssertion rma = new RMAssertion(); +RMAssertion.BaseRetransmissionInterval bri = new RMAssertion.BaseRetransmissionInterval(); +bri.setMilliseconds(4000L); +rma.setBaseRetransmissionInterval(bri); +AcknowledgementInterval ai = new AcknowledgementInterval(); +ai.setMilliseconds(2000L); +rma.setAcknowledgementInterval(ai); +feature.setRMAssertion(rma); +DestinationPolicyType dp = new DestinationPolicyType(); +AcksPolicyType ap = new AcksPolicyType(); +ap.setIntraMessageThreshold(0); +dp.setAcksPolicy(ap); +feature.setDestinationPolicy(dp); + +SimpleService proxy = (SimpleService)service.getPort(SimpleService.class, feature); +proxy.echo("Hello World"); </programlisting> </informalexample> - <para>The client needs to pick up the bus configuration such as below:</para> + <para> + The same can of course be achieved by factoring the feature into a custom pojo extending + <code>org.apache.cxf.ws.rm.feature.RMFeature</code> + and setting the obtained property in a client configuration: + </para> <informalexample> <programlisting> package org.jboss.test.ws.jaxws.samples.wsrm.client; -import java.net.URL; -import java.io.File; -import javax.xml.namespace.QName; -import javax.xml.ws.Service; -import org.apache.cxf.Bus; -import org.apache.cxf.BusFactory; -import org.jboss.wsf.stack.cxf.client.configuration.JBossWSBusFactory; -import org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService; +import org.apache.cxf.ws.rm.feature.RMFeature; +import org.apache.cxf.ws.rm.manager.AcksPolicyType; +import org.apache.cxf.ws.rm.manager.DestinationPolicyType; +import org.apache.cxf.ws.rmp.v200502.RMAssertion; +import org.apache.cxf.ws.rmp.v200502.RMAssertion.AcknowledgementInterval; -public final class SimpleServiceTestCase +public class CustomRMFeature extends RMFeature { - private static final String serviceURL = "http://localhost:8080/jaxws-samples-wsrm/SimpleService"; + public CustomRMFeature() { + super(); + RMAssertion rma = new RMAssertion(); + RMAssertion.BaseRetransmissionInterval bri = new RMAssertion.BaseRetransmissionInterval(); + bri.setMilliseconds(4000L); + rma.setBaseRetransmissionInterval(bri); + AcknowledgementInterval ai = new AcknowledgementInterval(); + ai.setMilliseconds(2000L); + rma.setAcknowledgementInterval(ai); + super.setRMAssertion(rma); + DestinationPolicyType dp = new DestinationPolicyType(); + AcksPolicyType ap = new AcksPolicyType(); + ap.setIntraMessageThreshold(0); + dp.setAcksPolicy(ap); + super.setDestinationPolicy(dp); + } +} +</programlisting> + </informalexample> + <para> + ... this is how the + <code>jaxws-client-config.xml</code> + descriptor would look: + </para> + <informalexample> + <programlisting> +&lt;?xml version="1.0" encoding="UTF-8"?&gt; - public static void main(String[] args) throws Exception - { - URL cxfConfig = new File("resources/jaxws/samples/wsrm/cxf.xml").toURL(); - Bus bus = new JBossWSBusFactory().createBus(cxfConfig); - try - { - BusFactory.setThreadDefaultBus(bus); +&lt;jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee" + xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd"&gt; - // create service - QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsrm";, "SimpleService"); - URL wsdlURL = new URL(serviceURL + "?wsdl"); - Service service = Service.create(wsdlURL, serviceName); - SimpleService proxy = (SimpleService)service.getPort(SimpleService.class); + &lt;client-config&gt; + &lt;config-name&gt;Custom Client Config&lt;/config-name&gt; + &lt;property&gt; + &lt;property-name&gt;cxf.features&lt;/property-name&gt; + &lt;property-value&gt;org.jboss.test.ws.jaxws.samples.wsrm.client.CustomRMFeature&lt;/property-value&gt; + &lt;/property&gt; + &lt;/client-config&gt; - // invoke methods - proxy.echo("Hello World!"); - } - finally - { - // shutdown bus - bus.shutdown(true); - } - } -} +&lt;/jaxws-config&gt; </programlisting> </informalexample> + <para>... and this is how the client would set the configuration:</para> + <informalexample> + <programlisting> +import org.jboss.ws.api.configuration.ClientConfigUtil; +import org.jboss.ws.api.configuration.ClientConfigurer; + +//... +Service service = Service.create(wsdlURL, serviceName); +SimpleService proxy = (SimpleService)service.getPort(SimpleService.class); + +ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer(); +configurer.setConfigProperties(proxy, "META-INF/jaxws-client-config.xml", "Custom Client Config"); +proxy.echo("Hello World!"); +</programlisting> + </informalexample> </section> </section> </section> @@ -5840,7 +8484,7 @@ <emphasis role="italics">HTTP</emphasis> WS endpoints (in <emphasis role="italics">war</emphasis> - archives). The webservices layer of JBoss Application Server takes care of looking for + archives). The webservices layer of WildFly takes care of looking for <emphasis role="italics">JMS</emphasis> enpdoints in the deployed archive and starts them delegating to the Apache CXF core similarly as with <emphasis role="italics">HTTP</emphasis> @@ -5932,18 +8576,6 @@ archives doesn't need any entry for JMS endpoints. </para> </note> - <note> - <para> - At the time of writing, the Apache CXF support for JMS transport requires - <emphasis role="italics">Spring</emphasis> - libraries to be available at runtime. - </para> - <para> - Please make sure - <emphasis role="italics">Spring</emphasis> - is properly installed on the application server, perhaps using the JBossWS installation option for it. - </para> - </note> </section> <section id="sid-3866801_SOAPoverJMS-Examples"> @@ -6032,13 +8664,13 @@ <emphasis role="italics">HelloWorldImplPort</emphasis> here is meant for using the <emphasis role="italics">testQueue</emphasis> - that's available by default on JBoss Application Server 7 + that has to be created before deploying the endpoint. </para> </important> <para> At the time of writing, <emphasis role="italics">java:/ConnectionFactory</emphasis> - is the default connection factory JNDI location on JBoss Application Server 7 + is the default connection factory JNDI location. </para> <para> For allowing remote JNDI lookup of the connection factory, a specific service ( @@ -6053,7 +8685,6 @@ </para> <important> <para>Have a look at the application server domain for finding out the configured connection factory JNDI locations.</para> - <para>Remote JNDI support is available starting from JBoss Application Server 7.1.</para> </important> <para>The endpoint implementation is a basic JAX-WS POJO using @WebService annotation to refer to the consumed contract:</para> <informalexample> @@ -6090,7 +8721,7 @@ archive and deploy it: </para> <informalexample> - <programlisting>alessio@inuyasha /dati/jbossws/stack/cxf/trunk $ jar -tvf ./modules/testsuite/cxf-spring-tests/target/test-libs/jaxws-cxf-jms-only-deployment.jar + <programlisting>alessio@inuyasha /dati/jbossws/stack/cxf/trunk $ jar -tvf ./modules/testsuite/cxf-tests/target/test-libs/jaxws-cxf-jms-only-deployment.jar 0 Thu Jun 23 15:18:44 CEST 2011 META-INF/ 129 Thu Jun 23 15:18:42 CEST 2011 META-INF/MANIFEST.MF 0 Thu Jun 23 15:18:42 CEST 2011 org/ @@ -6109,7 +8740,7 @@ <para> A dependency on <code>org.hornetq</code> - module needs to be added in MANIFEST.MF when deploying to JBoss Application Server 7. + module needs to be added in MANIFEST.MF when deploying to WildFly. </para> <informalexample> <programlisting>Manifest-Version: 1.0 @@ -6160,7 +8791,7 @@ </informalexample> <important> <para> - Have a look at the JBoss Application Server 7 domain and messaging configuration for finding out the actual security requirements. At the time of writing, a user with + Have a look at the WildFly domain and messaging configuration for finding out the actual security requirements. At the time of writing, a user with <code>guest</code> role is required and that's internally checked using the <code>other</code> @@ -6355,7 +8986,7 @@ archive: </para> <informalexample> - <programlisting>alessio@inuyasha /dati/jbossws/stack/cxf/trunk $ jar -tvf ./modules/testsuite/cxf-spring-tests/target/test-libs/jaxws-cxf-jms-http-deployment.war + <programlisting>alessio@inuyasha /dati/jbossws/stack/cxf/trunk $ jar -tvf ./modules/testsuite/cxf-tests/target/test-libs/jaxws-cxf-jms-http-deployment.war 0 Thu Jun 23 15:18:44 CEST 2011 META-INF/ 129 Thu Jun 23 15:18:42 CEST 2011 META-INF/MANIFEST.MF 0 Thu Jun 23 15:18:44 CEST 2011 WEB-INF/ @@ -6395,7 +9026,7 @@ <para> Here too the MANIFEST.MF needs to declare a dependency on <emphasis role="italics">org.hornetq</emphasis> - module when deploying to JBoss Application Server 7. + module when deploying to WildFly. </para> </important> <para>Finally, the JAX-WS client can ineract with both JMS and HTTP endpoints as usual:</para> @@ -6977,4 +9608,312 @@ </section> </section> </section> + <section id="sid-83919125"> + + <title>Published WSDL customization</title> + <section id="sid-83919125_PublishedWSDLcustomization-Endpointaddressrewrite"> + + <title>Endpoint address rewrite</title> + <para> + JBossWS supports the rewrite of the + <code>&lt;soap:address&gt;</code> + element of endpoints published in WSDL contracts. This feature is useful for controlling the server address that is advertised to clients for each endpoint. The rewrite mechanism is configured at server level through a set of elements in the webservices subsystem of the WildFly management model. Please refer to the container documentation for details on the options supported in the selected container version. Below is a list of the elements available in the latest WildFly sources: + </para> + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry> + <para>Name</para> + </entry> + <entry> + <para>Type</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + modify-wsdl-address + + </para> + </entry> + <entry> + <para>boolean</para> + </entry> + <entry> + <para> + This boolean enables and disables the address rewrite functionality. + + When modify-wsdl-address is set to true and the content of &lt;soap:address&gt; is a valid URL, JBossWS will rewrite the URL using the values of wsdl-host and wsdl-port or wsdl-secure-port. + + When modify-wsdl-address is set to false and the content of &lt;soap:address&gt; is a valid URL, JBossWS will not rewrite the URL. The &lt;soap:address&gt; URL will be used. + + When the content of &lt;soap:address&gt; is not a valid URL, JBossWS will rewrite it no matter what the setting of modify-wsdl-address. + + If modify-wsdl-address is set to true and wsdl-host is not defined or explicitly set to + <emphasis role="italics">'</emphasis> + <code>jbossws.undefined.host</code> + _' _ the content of &lt;soap:address&gt; URL is use. JBossWS uses the requester's host when rewriting the &lt;soap:address&gt; + + When modify-wsdl-address is not defined JBossWS uses a default value of true. + + </para> + </entry> + </row> + <row> + <entry> + <para> + wsdl-host + + </para> + </entry> + <entry> + <para>string</para> + </entry> + <entry> + <para> + The hostname / IP address to be used for rewriting + <code>&lt;soap:address&gt;</code> + . + + If + <code>wsdl-host</code> + is set to + <code>jbossws.undefined.host</code> + , JBossWS uses the requester's host when rewriting the + <code>&lt;soap:address&gt;</code> + + When wsdl-host is not defined JBossWS uses a default value of ' + <code>jbossws.undefined.host</code> + '. + </para> + </entry> + </row> + <row> + <entry> + <para> + wsdl-port + + </para> + </entry> + <entry> + <para>int</para> + </entry> + <entry> + <para> + Set this property to explicitly define the HTTP port that will be used for rewriting the SOAP address. + + Otherwise the HTTP port will be identified by querying the list of installed HTTP connectors. + </para> + </entry> + </row> + <row> + <entry> + <para> + wsdl-secure-port + + </para> + </entry> + <entry> + <para>int</para> + </entry> + <entry> + <para> + Set this property to explicitly define the HTTPS port that will be used for rewriting the SOAP address. + + Otherwise the HTTPS port will be identified by querying the list of installed HTTPS connectors. + </para> + </entry> + </row> + <row> + <entry> + <para>wsdl-uri-scheme</para> + </entry> + <entry> + <para> + string + + </para> + </entry> + <entry> + <para> + This property explicitly sets the URI scheme to use for rewriting + <code>&lt;soap:address&gt;</code> + . Valid values are + <code>http</code> + and + <code>https</code> + . This configuration overrides scheme computed by processing the endpoint (even if a transport guarantee + + is specified). The provided values for + <code>wsdl-port</code> + and + <code>wsdl-secure-port</code> + (or their default values) are used depending on specified scheme. + + </para> + </entry> + </row> + <row> + <entry> + <para>wsdl-path-rewrite-rule</para> + </entry> + <entry> + <para> + string + + </para> + </entry> + <entry> + <para> + This string defines a SED substitution command (e.g., 's/regexp/replacement/g') that JBossWS executes against the path component of each &lt;soap:address&gt; URL published from the server. + + When wsdl-path-rewrite-rule is not defined, JBossWS retains the original path component of each &lt;soap:address&gt; URL. + + When 'modify-wsdl-address' is set to "false" this element is ignored. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + Additionally, users can override the server level configuration by requesting a specific rewrite behavior for a given endpoint deployment. That is achieved by setting one of the following properties within a + <emphasis role="italics">jboss-webservices.xml</emphasis> + descriptor: + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Property</para> + </entry> + <entry> + <para>Corresponding server option</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>wsdl.soapAddress.rewrite.modify-wsdl-address</para> + </entry> + <entry> + <para>modify-wsdl-address</para> + </entry> + </row> + <row> + <entry> + <para>wsdl.soapAddress.rewrite.wsdl-host</para> + </entry> + <entry> + <para>wsdl-host</para> + </entry> + </row> + <row> + <entry> + <para>wsdl.soapAddress.rewrite.wsdl-port</para> + </entry> + <entry> + <para>wsdl-port</para> + </entry> + </row> + <row> + <entry> + <para>wsdl.soapAddress.rewrite.wsdl-secure-port</para> + </entry> + <entry> + <para>wsdl-secure-port</para> + </entry> + </row> + <row> + <entry> + <para>wsdl.soapAddress.rewrite.wsdl-path-rewrite-rule</para> + </entry> + <entry> + <para>wsdl-path-rewrite-rule</para> + </entry> + </row> + <row> + <entry> + <para>wsdl.soapAddress.rewrite.wsdl-uri-scheme</para> + </entry> + <entry> + <para>wsdl-uri-scheme</para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>Here is an example of partial overriding of the default configuration for a specific deployment:</para> + <informalexample> + <programlisting>&lt;?xml version="1.1" encoding="UTF-8"?&gt; +&lt;webservices version="1.2" + xmlns="http://www.jboss.com/xml/ns/javaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee"&gt; + &lt;property&gt; + &lt;name&gt;wsdl.soapAddress.rewrite.wsdl-uri-scheme&lt;/name&gt; + &lt;value&gt;https&lt;/value&gt; + &lt;/property&gt; + &lt;property&gt; + &lt;name&gt;wsdl.soapAddress.rewrite.wsdl-host&lt;/name&gt; + &lt;value&gt;foo&lt;/value&gt; + &lt;/property&gt; +&lt;/webservices&gt;</programlisting> + </informalexample> + </section> + <section id="sid-83919125_PublishedWSDLcustomization-Systempropertyreferences"> + + <title>System property references</title> + <para>System property references wrapped within "@" characters are expanded when found in WSDL attribute and element values. This allows for instance including multiple WS-Policy declarations in the contract and selecting the policy to use depending on a server wide system property; here is an example:</para> + <informalexample> + <programlisting>&lt;wsdl:definitions ...&gt; + ... + &lt;wsdl:binding name="ServiceOneSoapBinding" type="tns:EndpointOne"&gt; + ... + &lt;wsp:PolicyReference URI=&quot;#@org.jboss.wsf.test.JBWS3628TestCase.policy(a)&quot;/&amp;gt; + &lt;wsdl:operation name="echo"&gt; + ... + &lt;/wsdl:operation&gt; + &lt;/wsdl:binding&gt; + &lt;wsdl:service name="ServiceOne"&gt; + &lt;wsdl:port binding="tns:ServiceOneSoapBinding" name="EndpointOnePort"&gt; + &lt;soap:address location="http://localhost:8080/jaxws-cxf-jbws3628/ServiceOne"/&gt; + &lt;/wsdl:port&gt; + &lt;/wsdl:service&gt; + + &lt;wsp:Policy xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... xmlns:wsp="http://www.w3.org/ns/ws-policy" wsu:Id="WS-RM_Policy"&gt; + &lt;wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"&a... + ... + &lt;/wsrmp:RMAssertion&gt; + &lt;/wsp:Policy&gt; + + &lt;wsp:Policy xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w... xmlns:wsp="http://www.w3.org/ns/ws-policy" + xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" wsu:Id="WS-Addressing_policy"&gt; + &lt;wsam:Addressing&gt; + &lt;wsp:Policy/&gt; + &lt;/wsam:Addressing&gt; + &lt;/wsp:Policy&gt; +&lt;/wsdl:definitions&gt;</programlisting> + </informalexample> + <para> + If the + <emphasis role="strong"> + <emphasis role="italics">org.jboss.wsf.test.JBWS3628TestCase.policy</emphasis> + </emphasis> + system property is defined and set to " + <emphasis role="strong"> + <emphasis role="italics">WS-Addressing_policy</emphasis> + </emphasis> + ", WS-Addressing will be enabled for the endpoint defined by the contract above. + </para> + </section> + </section> </chapter> Modified: stack/cxf/trunk/modules/dist/src/main/doc/chapter-6-JBoss_Modules.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-6-JBoss_Modules.xml 2015-04-22 18:30:24 UTC (rev 19683) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-6-JBoss_Modules.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -3,20 +3,20 @@ <chapter id="sid-4784150"> <title>JBoss Modules</title> - <para>The JBoss Web Services functionalities are provided by a given set of modules / libraries installed on the JBoss Application Server.</para> + <para>The JBoss Web Services functionalities are provided by a given set of modules / libraries installed on the server.</para> <para> - On JBoss Application Server 7, those are organized into JBoss Modules modules. In particular the + On WildFly, those are organized into JBoss Modules modules. In particular the <emphasis role="italics">org.jboss.as.webservices.*</emphasis> and <emphasis role="italics">org.jboss.ws.*</emphasis> - modules belong to the JBossWS - AS7 integration. Users should not need to change anything in them. + modules belong to the JBossWS - WildFly integration. Users should not need to change anything in them. </para> - <para>While users are of course allowed to provide their own modules for their custom needs, below is a brief collection of suggestions and hints around modules and webservices development on JBoss Application Server 7.</para> + <para>While users are of course allowed to provide their own modules for their custom needs, below is a brief collection of suggestions and hints around modules and webservices development on WildFly.</para> <section id="sid-4784150_JBossModules-Settingmoduledependencies"> <title>Setting module dependencies</title> <para> - On JBoss Aplication Server 7 the user deployment classloader does not have any visibility over JBoss internals; so for instance you can't + On WildFly the user deployment classloader does not have any visibility over JBoss internals; so for instance you can't <emphasis role="italics">directly</emphasis> use JBossWS <emphasis role="italics">implementation</emphasis> @@ -47,7 +47,7 @@ exports the classes from the module to any other module that might be depending on the module implicitly created for your deployment. </para> <note> - <para>When using annotations on your endpoints / handlers such as the Apache CXF ones (@InInterceptor, @GZIP, ...) remember to add the proper module dependency in your manifest. Otherwise your annotations are not picked up and added to the annotation index by JBoss Application Server 7, resulting in them being completely and silently ignored.</para> + <para>When using annotations on your endpoints / handlers such as the Apache CXF ones (@InInterceptor, @GZIP, ...) remember to add the proper module dependency in your manifest. Otherwise your annotations are not picked up and added to the annotation index by WildFly, resulting in them being completely and silently ignored.</para> </note> <section id="sid-4784150_JBossModules-UsingJAXB"> @@ -108,15 +108,6 @@ </para> </important> </section> - <section id="sid-4784150_JBossModules-UsingSpring"> - - <title>Using Spring</title> - <para> - The JBossWS-CXF modules have optional dependencies to the - <emphasis role="italics">org.springframework.spring</emphasis> - module. So either create that manually in the application server or use the JBossWS-CXF installation scripts for doing that. - </para> - </section> <section id="sid-4784150_JBossModules-Annotationscanning"> <title>Annotation scanning</title> @@ -136,47 +127,6 @@ <title>Using jboss-deployment-descriptor.xml</title> <para>In some circumstances, the convenient approach of setting module dependencies in MANIFEST.MF might not work. An example is the need for importing/exporting specific resources from a given module dependency. Users should hence add a jboss-deployment-structure.xml descriptor to their deployment and set module dependencies in it.</para> - <section id="sid-4784150_JBossModules-SpringbasedincontainerBuscreation"> - - <title>Spring based in-container Bus creation</title> - <para> - A noteworthy scenario requiring explicit module dependencies declaration is whenever a Spring beans descriptor based Bus is created by users in a in-container client. Spring basically resolves any beans declared in the descriptor (e.g. - <emphasis role="italics">cxf.xml</emphasis> - ), as well as any transitively referenced internal CXF descriptor, using the thread context classloader. That is the classloader associated to the deployment, which is different from the classloader used by JBossWS internally. As a consequence, in this scenario a - <emphasis role="italics">jboss-deployment-structure.xml</emphasis> - as follows is required: - - </para> - <informalexample> - <programlisting>&lt;jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2"&gt; - &lt;deployment&gt; - &lt;dependencies&gt; - &lt;module name="org.jboss.ws.cxf.jbossws-cxf-client" services="import" /&gt; - &lt;module name="org.apache.cxf.impl"&gt; - &lt;imports&gt; - &lt;include path="META-INF"/&gt; - &lt;include path="META-INF/cxf"/&gt; - &lt;/imports&gt; - &lt;/module&gt; - &lt;module name="org.springframework.spring"&gt; - &lt;imports&gt; - &lt;include path="META-INF"/&gt; - &lt;/imports&gt; - &lt;/module&gt; - &lt;/dependencies&gt; - &lt;/deployment&gt; -&lt;/jboss-deployment-structure&gt;</programlisting> - </informalexample> - <para> - The first dependency ( - <emphasis role="italics">org.jboss.ws.cxf.jbossws-cxf-client</emphasis> - ) loads JBossWS customizations as well as Apache CXF APIs first. The second dependency ( - <emphasis role="italics">org.apache.cxf.impl</emphasis> - ) loads the Apache CXF internals (in particular the CXF SpringBus class), required by Spring to load the Bus using the deployment classloader. Finally, the third dependency ( - <emphasis role="italics">org.springframework.spring</emphasis> - ) is needed to allow resolution of Spring schemas when running offline. - </para> - </section> </section> </section> </chapter> Added: stack/cxf/trunk/modules/dist/src/main/doc/chapter-8-Build_and_testsuite_framework.xml =================================================================== --- stack/cxf/trunk/modules/dist/src/main/doc/chapter-8-Build_and_testsuite_framework.xml (rev 0) +++ stack/cxf/trunk/modules/dist/src/main/doc/chapter-8-Build_and_testsuite_framework.xml 2015-04-23 12:38:25 UTC (rev 19684) @@ -0,0 +1,372 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="sid-88703514"> + + <title>Build and testsuite framework</title> + <section id="sid-88703514_Buildandtestsuiteframework-Introduction"> + + <title>Introduction</title> + <para> + The JBossWS project build and testsuites have been completely revisited in version 5.0.0.Beta3. As a result, JBossWS uses the + <emphasis role="italics">Arquillian</emphasis> + framework to run its integration tests against WildFly containers. + </para> + <para> + There are three test modules in JBossWS' testsuite, + <emphasis role="italics">cxf-tests</emphasis> + , + <emphasis role="italics">shared-tests</emphasis> + and + <emphasis role="italics">cxf-spring-tests</emphasis> + . Each test module requires at least one + <emphasis role="italics">WildFly</emphasis> + container to run; multiple containers are used for modules whose tests can't run at the same time on the same container. By default, containers are managed (started / stopped) by Arquillian.The JBossWS build system fetches a copy of the required container from the Maven repository, unpacks it, patches it installing the current webservices stack on it and finally hands it over to Arquillian for the testsuite runs. The test framework also allows letting Arquillian manage an already available container instance on the local filesystem. Finally, it's also possible to execute single tests against a locally running container (non-Arquillian managed) and run the tests concurrently. + </para> + <section id="sid-88703514_Buildandtestsuiteframework-Prerequisitesandrequirements"> + + <title>Prerequisites and requirements</title> + <itemizedlist> + <listitem> + <para>Maven version 3.2.2 or higher is required to build and run the testsuite.</para> + </listitem> + <listitem> + <para>A unique class name for each test across the testsuite's three child modules; classes may have the same package name across the child modules but the overall full-qualified name has to be unique to avoid breaking concurrent tests runs.</para> + </listitem> + </itemizedlist> + </section> + </section> + <section id="sid-88703514_Buildandtestsuiteframework-Architectureoverview"> + + <title>Architecture overview</title> + <para>When the build fetches the a container from the Maven repository, a patched copy of it is put within the target/test-server sub-directory of each testsuite module. For instance, you could have:</para> + <sidebar> + <para> + ./modules/testsuite/cxf-tests/target/test-server/jbossws-cxf-dist-5.0.0-SNAPSHOT/wildfly-8.1.0.Final + + ./modules/testsuite/shared-tests/target/test-server/jbossws-cxf-dist-5.0.0-SNAPSHOT/wildfly-8.1.0.Final + + ./modules/testsuite/cxf-spring-tests/target/test-server/jbossws-cxf-dist-5.0.0-SNAPSHOT/wildfly-8.1.0.Final + </para> + </sidebar> + <para> + Each container copy is also provided with specific standalone mode configuration files ( + <emphasis role="italics">jbws-testsuite-SOME_IDENTIFIER.xml</emphasis> + ) in the + <code>standalone/configuration</code> + server directory. The actual contents of such descriptors depends on the tests that are to be run against such container configurations (the most common difference when compared to the vanilla standalone.xml is the setup op additional security domains, system properties, web connectors etc.) Each configuration also includes logging setup to ensure logs are written to unique files ( + <emphasis role="italics">jbws-testsuite-SOME_IDENFIFIER.log</emphasis> + ) in + <code>standalone/log</code> + directory. + </para> + <section id="sid-88703514_Buildandtestsuiteframework-TargetContainerIdentification"> + + <title>Target Container Identification</title> + <para> + JBossWS supports the current WildFly release and several back versions for testing. See the + <ulink url="https://community.jboss.org/wiki/JBossWS-SupportedTargetContain... target containers</ulink> + page for details. + + Maven profiles are used to identify the target container to be used for testing. The naming convention is + <emphasis role="italics">wildflyXYZ</emphasis> + , for example + <emphasis role="italics">wildfly820</emphasis> + to mean WIldFly 8.2.0.Final. + </para> + <para> + To run tests against an existing local copy of a WildFly container, the user must specify the absolute path to the server implementation's home directory using the command line option, + <emphasis role="italics">-Dserver.home=/foo/bar</emphasis> + . The server is not expected to be running, as the build will create various standalone server configurations and start multiple instances on different port numbers. However, if a single test of few tests are executed only, the user can have those executed against live WildFly instances previously started on the same port numbers expected by the tests. Arquillian is configured to detect such scenario and use the available server. + </para> + </section> + <section id="sid-88703514_Buildandtestsuiteframework-PortMapping"> + + <title>Port Mapping</title> + <para> + To facilitate concurrent testing a port offset has been defined for each of the server configurations. The offsets are defined in the + <code>&lt;properties&gt;</code> + element of the + <code>modules/testsuite/pom.xml</code> + file. + </para> + </section> + </section> + <section id="sid-88703514_Buildandtestsuiteframework-CommandLineOptions"> + + <title>Command Line Options</title> + <para>As any other Maven-based project, JBossWS is built as follows:</para> + <informalexample> + <programlisting>mvn -P[profile] -D[options] [phase]</programlisting> + </informalexample> + <section id="sid-88703514_Buildandtestsuiteframework-Profile"> + + <title>Profile</title> + <para>JBossWS uses Maven profiles to declare the target container and other types of environment setup. Multiple profiles are provided as a comma separated list of profile names. Only a single target container profile is allowed at the same time though.</para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Profile</para> + </entry> + <entry> + <para> + Description + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + <code>wildflyXYZ</code> + + </para> + </entry> + <entry> + <para>Designates the target container to use, where XYZ is WildFly's three digit version number</para> + </entry> + </row> + <row> + <entry> + <para> + <code>spring</code> + + </para> + </entry> + <entry> + <para> + Enables Spring support; this causes Spring libraries to be installed on the target container and the cxf-spring-tests testsuite module to be also run + + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>fast</code> + + </para> + </entry> + <entry> + <para> + Declares the tests are to be run concurrently + + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>dist</code> + + </para> + </entry> + <entry> + <para> + Explicitly includes + <emphasis role="italics">dist</emphasis> + module in the build; by default this is automatically triggered (only) when a + <code>wildflyXYZ</code> + profile is set. + + </para> + </entry> + </row> + <row> + <entry> + <para> + <code>testsuite</code> + + </para> + </entry> + <entry> + <para> + Explicitly includes the testsuite modules in the build; by default this is automatically triggered (only) when a + <code>wildflyXYZ</code> + profile is set. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + <section id="sid-88703514_Buildandtestsuiteframework-Options"> + + <title>Options</title> + <para>Below is a list of the available build / test options:</para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + <para>Option</para> + </entry> + <entry> + <para> + Description + + </para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para> + server.home + + </para> + </entry> + <entry> + <para> + Declares the absolute path to a given local server instance. + + </para> + </entry> + </row> + <row> + <entry> + <para>exclude-udp-tests</para> + </entry> + <entry> + <para>Force skipping the UDP tests. This option might be needed when running on a network that does not allow UDP broadcast.</para> + </entry> + </row> + <row> + <entry> + <para> + nodeploy + + </para> + </entry> + <entry> + <para> + Do not upgrade the WS stack on the target server container. + + </para> + </entry> + </row> + <row> + <entry> + <para> + noprepare + + </para> + </entry> + <entry> + <para>Skip integration tests preparation phase, which includes tuning of the server configurations, wsconsume/wsprovide invocations, etc.</para> + </entry> + </row> + <row> + <entry> + <para> + debug + + </para> + </entry> + <entry> + <para>Turns on Surefire debugging of integration tests only. Debugging address is 5005.</para> + </entry> + </row> + <row> + <entry> + <para>jboss.bind.address</para> + </entry> + <entry> + <para>Starts the containers bound to the specified network interface address.</para> + </entry> + </row> + <row> + <entry> + <para>arquillian.deploymentExportPath</para> + </entry> + <entry> + <para> + Instructs Arquillian to write the actual test deployments to disk in the specified module sub-directory. + + </para> + </entry> + </row> + <row> + <entry> + <para> + test + + </para> + </entry> + <entry> + <para> + Runs the testcases in the specified comma-separated list of JUnit classes + + </para> + </entry> + </row> + <row> + <entry> + <para> + maven.surefire.debug + + </para> + </entry> + <entry> + <para> + Turns on Surefire debugging in any module including tests. + + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + <section id="sid-88703514_Buildandtestsuiteframework-Examples"> + + <title>Examples</title> + <para>Build the project, deploy the WS stack to a local copy of WildFly 8.2.0.Final and run the testsuite:</para> + <informalexample> + <programlisting>mvn -Pwildfly820 -Dserver.home=/foo/wildfly-8.2.0.Final integration-test</programlisting> + </informalexample> + <para> + Use + <emphasis role="italics">WildFly 8.1.0.Final</emphasis> + as the target container (letting the build fetch it), patch it with current WS stack (including Spring libraries) and run only test + <emphasis role="italics">BasicDocTestCase</emphasis> + that is located in the + <emphasis role="italics">cxf-spring-test</emphasis> + module: + </para> + <informalexample> + <programlisting>mvn -Pwildfly810,spring integration-test -Dtest="org/jboss/test/ws/jaxws/cxf/wsrm/BasicDocTestCase"</programlisting> + </informalexample> + <para>Build, deploy, then run the tests concurrently. Run till Maven post-integration-test phase to trigger test servers shutdown and save memory at the end of each testsuite module:</para> + <informalexample> + <programlisting>mvn -Pfast,wildfly810 post-integration-test</programlisting> + </informalexample> + <para>Completely clean the project:</para> + <informalexample> + <programlisting>mvn -Pdist,testsuite,spring clean</programlisting> + </informalexample> + <para>Build the WS stack and install it on a specified server instance without running the integration testsuite:</para> + <informalexample> + <programlisting>mvn -Pwildfly900 -Dserver.home=/foo/wildfly-9.0.0.Alpha2-SNAPSHOT package</programlisting> + </informalexample> + <para> + When a server.home option is not provided, the build creates a zip archive with a vanilla WildFly server patched with the current WS stack: the zip file path is modules/dist/target/jbossws-cxf-dist-${ + <emphasis role="strong">project.version}</emphasis> + -wildflyXYZ.zip + </para> + <informalexample> + <programlisting>mvn -Pwildfly810 package</programlisting> + </informalexample> + </section> + </section> + <section id="sid-88703514_Buildandtestsuiteframework-Containerremotedebugging"> + + <title>Container remote debugging</title> + <para>While debugging the a testcase is simply a matter of providing the -Ddebug option, remote debugging the container code that runs the WS stack requires few additional setup steps. The suggested approach is to identify a single test to run; before actually running the test, manually start a target container in debug mode and specifying the proper port offset and server configuration (have a look at the arquillian.xml decriptors in the testsuite). Then run the tests with -Dserver.home=... option pointing to the home dir for the server currently running.</para> + </section> + </chapter> Property changes on: stack/cxf/trunk/modules/dist/src/main/doc/chapter-8-Build_and_testsuite_framework.xml ___________________________________________________________________ Added: svn:mime-type + text/xml Added: svn:keywords + Rev Date Added: svn:eol-style + native