JBoss Community Archive (Read Only)

SwitchYard

SOAP

The SOAP component in SwitchYard provides SOAP-based web service binding support for services and references in SwitchYard. 

Binding Services with SOAP

Composite-level services can be exposed as a SOAP-based web service using the <binding.soap> binding definition.  The following configuration options are available for binding.soap when binding services:

  • wsdl : location of the WSDL used to describe the web service endpoint.  A relative path can be used if the WSDL is included in the deployed application.  If the WSDL is located outside the application, then a file: or http: URL can be used.

  • socketAddr : the IP Socket Address to be used. The value can be in the form hostName/ipAddress:portNumber or hostName/ipAddress or :portNumber.

  • wsdlPort : port name in the WSDL to use.  If unspecified, the first port definition in the WSDL is used for the service endpoint

  • contextPath : additional context path for the SOAP endpoint. Default is none.

In AS7 by default the JBossWS-CXF stack is enabled now and hence the socketAddr parameter will be ignored. However, this parameter can be used for standalone usage.

Here's an example of what a SOAP service binding looks like: 

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:service name="OrderService" promote="OrderService">
        <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:socketAddr>:9000</soap:socketAddr>        
         </soap:binding.soap>
    </sca:service>
</sca:composite>

Binding References with SOAP

Binding a reference with SOAP can be used to make SOAP-based web services available to SwitchYard services. The following configuration options are available for binding.soap when binding references:

  • wsdl : location of the WSDL used to describe the web service endpoint.  A relative path can be used if the WSDL is included in the deployed application.  If the WSDL is located outside the application, then a file: or http: URL can be used.

  • wsdlPort : port name in the WSDL to use.  If unspecified, the first port definition in the WSDL is used for the service endpoint.

  • endpointAddress : the SOAP endpoint address to override from that specified in the WSDL. Optional property, if not specified will use the one specified in the WSDL.

  • timeout : The request's time-out value in milliseconds.

  • proxy : HTTP Proxy settings for the endpoint.

  • basic/ntlm : authentication configuration for the endpoint. 

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
         <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:endpointAddress>http://www.change.com/toanewendpointurl</soap:endpointAddress>
         </soap:binding.soap>
    </sca:reference>
</sca:composite>

Proxy Configuration

If the SOAP reference needs to pass through a proxy server then the proxy server configuration can be provided using the proxy element. The following configuration options are available:

  • type : The proxy type. Can be HTTP or SOCKS, default is HTTP

  • host : The proxy host.

  • port : The proxy port (optional).

  • user : The proxy user (optional).

  • password : The proxy password (optional). 

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
        <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:endpointAddress>[http://www.change.com/toanewendpointurl]</soap:endpointAddress>
            <soap:proxy>
                <soap:type>HTTP</soap:type>
                <soap:host>192.168.1.2</soap:host>
                <soap:port>9090</soap:port>
                <soap:user>user</soap:user>
                <soap:password>password</soap:password>
            </soap:proxy>
        </soap:binding.soap>
    </sca:reference>
</sca:composite>

Authentication Configuration

If the SOAP reference endpoint is secured using BASIC/NTLM, then the authentication configuration can be provided using the basic or ntlm elements. The following configuration options are available:

  • user : the user name.

  • password : password.

  • host : the authentication host (optional).

  • port : the authentication port (optional).

  • realm : the authentication realm (optional, applicable only for BASIC).

  • domain: the Windows domain for authentication (optional, applicable only for NTLM).

A sample NTLM authentication configuration: 

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
        <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:endpointAddress>[http://www.change.com/toanewendpointurl]</soap:endpointAddress>
            <soap:ntlm>
                <soap:user>user</soap:user>
                <soap:password>password</soap:password>
                <soap:domain>domain</soap:domain>
            </soap:ntlm>
        </soap:binding.soap>
    </sca:reference>
</sca:composite>

Security

Important

It is strongly suggested that you first read up on JBoss Web Services WS-Security.

UsernameToken Support

To enable WS-Security within your application, a few steps are required:

  1. Define a Policy within your WSDL, and reference with with a PolicyReference inside your binding.

  2. Configure your <soap.binding> with an <endpointConfig> so JBossWS-CXF is configured properly.

  3. Configure your <soap.binding> with an <inInterceptors> section, including the appropriate JBossWS-CXF <interceptor> to handle incoming SOAP requests.

  4. Include a WEB-INF/jboss-web.xml in your application with a <security-domain> specified, so JBossWS-CXF knows which modules to use for authentication and roles mapping.

SwitchYard provides a policy-security-wss-username Quickstart as an example. Here are the pertinent sections:

META-INF/WorkService.wsdl 

  <binding name="WorkServiceBinding" type="tns:WorkService">
    <wsp:PolicyReference URI="#WorkServicePolicy"/>
    ...
  </binding>
  <wsp:Policy wsu:Id="WorkServicePolicy">
    <wsp:ExactlyOne>
      <wsp:All>
        <sp:SupportingTokens xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
          <wsp:Policy>
            <sp:UsernameToken sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
              <wsp:Policy>
                <sp:WssUsernameToken10/>
              </wsp:Policy>
            </sp:UsernameToken>
          </wsp:Policy>
        </sp:SupportingTokens>
      </wsp:All>
    </wsp:ExactlyOne>
  </wsp:Policy>

META-INF/switchyard.xml 

  <binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
    <wsdl>META-INF/WorkService.wsdl</wsdl>
    <contextPath>policy-security-wss-username</contextPath>
    <endpointConfig configFile="META-INF/jaxws-endpoint-config.xml" configName="SwitchYard-Endpoint-Config"/>
    <inInterceptors>
        <interceptor class="org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingPolicyInterceptor"/>
    </inInterceptors>
  </binding.soap>

WEB-INF/jaxws-endpoint-config.xml 

<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
    <endpoint-config>
        <config-name>SwitchYard-Endpoint-Config</config-name>
        <property>
            <property-name>ws-security.validate.token</property-name>
            <property-value>false</property-value>
        </property>
    </endpoint-config>
</jaxws-config>

WEB-INF/jboss-web.xml 

<jboss-web>
    <security-domain>java:/jaas/other</security-domain>
</jboss-web>

With the above pieces in place, JBossWS-CXF will intercept incoming SOAP requests, extract the UsernameToken, attempt to authenticate it against the LoginModule(s) configured in the application server's "other" security domain, and provide any authorized roles. If successful, the request will be handed over to SwitchYard, who can do further processing, including enforcing our own policies. In the case of WS-Security, SwitchYard will not attempt a second clientAuthentication, but instead will respect the outcome from JBossWS-CXF. Note that if the original clientAuthentication fails, it is a "fail-fast" scenario, and the request will not be channeled into SwitchYard.

Signature and Encryption Support

Required steps:

  1. The Policy in your WSDL needs to reflect the added requirements. An example of this can be found in the JBossWS documentation here: Signature and Encryption.

  2. Configure your <soap.binding> with an <endpointConfig> so JBossWS-CXF is configured properly.

For example:

META-INF/switchyard.xml 

  <binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
    <wsdl>META-INF/WorkService.wsdl</wsdl>
    <contextPath>policy-security-wss-username</contextPath>
    <endpointConfig configFile="META-INF/jaxws-endpoint-config.xml" configName="SwitchYard-Endpoint-Config">
  </binding.soap>

WEB-INF/jaxws-endpoint-config.xml 

<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
    <endpoint-config>
        <config-name>SwitchYard-Endpoint-Config</config-name>
        <property>
            <property-name>ws-security.callback-handler</property-name>
            <property-value>org.switchyard.quickstarts.demo.policy.security.wss.signencrypt.WorkServiceCallbackHandler</property-value>
        </property>
        <property>
            <property-name>ws-security.encryption.properties</property-name>
            <property-value>META-INF/bob.properties</property-value>
        </property>
        <property>
            <property-name>ws-security.encryption.username</property-name>
            <property-value>alice</property-value>
        </property>
        <property>
            <property-name>ws-security.signature.properties</property-name>
            <property-value>META-INF/bob.properties</property-value>
        </property>
        <property>
            <property-name>ws-security.signature.username</property-name>
            <property-value>bob</property-value>
        </property>
    </endpoint-config>
</jaxws-config>

META-INF/bob.properties 

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=password
org.apache.ws.security.crypto.merlin.keystore.alias=bob
org.apache.ws.security.crypto.merlin.file=META-INF/bob.jks

Attachments

SOAP with Attachments (SwA)

By default any attachment sent with a SOAP Envelope is passed around in a SwitchYard Message as an attachment. The default SOAPMessageComposer handles this.

SOAP with MTOM/XOP

To support optimization mechanism, the underlying stack transports/receives the attachments as Mime-Multipart messages. One additional configuration in SwitchYard that allows to expand an xop:inline's SOAP Message is this:

  • mtom : attribute xopExpand when set to true will replace the xop:include element with the contents from the Mime attachment.

sample: 

<soap:binding.soap xmlns:soap="urn:switchyard-component-soap:config:1.0">
    <soap:wsdl>Foo.wsdl</soap:wsdl>
    <soap:endpointAddress>http://modified.com/phantom</soap:endpointAddress>
    <soap:mtom enabled="true" xopExpand="true"/>
</soap:binding.soap>

MTOM can be enabled using WSDL policy as shown below or can be overridden as shown above using the SwitchYard config. 

<definitions targetNamespace="urn:switchyard-component-soap:test-ws:1.0" name="ImageService"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="urn:switchyard-component-soap:test-ws:1.0"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
    xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
    xmlns:wsoma="http://www.w3.org/2007/08/soap12-mtom-policy"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
...
    <wsp:Policy wsu:Id="ImageServicePortBinding_policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsoma:MTOM/>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
...
  <binding name="ImageServicePortBinding" type="tns:ImageService">
    <wsp:PolicyReference URI="#ImageServicePortBinding_policy"/>
    <soap:binding transport="http://www.w3.org/2003/05/soap/bindings/HTTP/" style="document"/>
    <operation name="resize">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

Addressing

SwitchYard runtime provides support for WS-A via the underlying SOAP stack. To enable WS-A you can either set a policy or use the UseAdrressing element in the WSDL as shown below: 

<definitions targetNamespace="urn:switchyard-component-soap:test-ws:1.0" name="HelloAddressingService"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="urn:switchyard-component-soap:test-ws:1.0"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
...
    <wsp:Policy wsu:Id="HelloSOAPAddressingServicePortBinding_policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsam:Addressing wsdl:required="false">
                    <wsp:Policy/>
                </wsam:Addressing>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
...
  <binding name="HelloSOAPAddressingServicePortBinding" type="tns:HelloAddressingService">
    <wsp:PolicyReference URI="#HelloSOAPAddressingServicePortBinding_policy"/>
    <soap:binding transport="http://www.w3.org/2003/05/soap/bindings/HTTP/" style="document"/>
    <operation name="sayHello">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
...
  <binding name="HelloSOAPAddressingServicePortBinding2" type="tns:HelloAddressingService2">
    <wsaw:UsingAddressing required="true" />
    <soap:binding transport="http://www.w3.org/2003/05/soap/bindings/HTTP/" style="document"/>
    <operation name="sayHello">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 09:45:38 UTC, last content change 2013-08-26 14:50:42 UTC.