LibraryToggle FramesPrintFeedback
Prev   Next

Configure the Client-STS Connection

In order to retrieve a token from the STS, the client creates a connection to the STS, which must be configured in the same way as a regular client proxy. The code for instantiating this client proxy and invoking the STS is implemented by the following special class:

org.apache.cxf.ws.security.trust.STSClient

A client that supports single sign-on must explicitly create an instance of the STSClient class. When the client parses a WS-SecurityPolicy containing an IssuedToken policy, the Apache CXF runtime automatically looks for an STSClient instance to obtain a token from the STS. In other words, the IssuedToken policy and the STSClient object work hand-in-hand: the presence of an IssuedToken policy automatically triggers the STSClient object to interact with the STS.

An interesting point about the sample client code is that it illustrates how you can use XML to configure a client proxy that has already been created in Java. In other words, this example answers the question: what do you do, when the client proxy is created in Java, but you want to specify some of its properties in XML?

First of all, consider the typical approach for instantiating a client proxy in Java, using the generated Greeter stub code, as follows:

// Java
import org.apache.hello_world_soap_http.Greeter;
import org.apache.hello_world_soap_http.SOAPService;
...
// Instantiate 'Greeter' client proxy
SOAPService ss = new SOAPService(wsdlURL, SERVICE_NAME);
Greeter port = ss.getPort(PORT_NAME, Greeter.class);

Now, in the XML configuration, you cannot use the jaxws:client element in the normal way to instantiate and configure the client proxy, because the Greeter client proxy already exists. It turns out, however, that the jaxws:client element supports a special syntax that enables you to inject properties into an existing instance, as shown in the following XML fragment:

<beans ...>
  ...
  <jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort"
                createdFromAPI="true">
    <!-- Set jaxws:properties, and so on -->
    ...
  </jaxws:client>
  ...
</beans>

The special syntax for modifying an existing client proxy uses the following attributes:

name

The full QName of the WSDL port associated with the existing client proxy (or possibly proxies).

createdFromAPI

When true, indicates that the client proxy was already created in Java code, and that this jaxws:client element should only be used to inject properties into the existing client proxy instance (or instances).

Perform the following steps to configure the STSClient:

  1. Specify the ws-security.sts.client property on the client proxy. This property is used to reference an org.apache.cxf.ws.security.trust.STSClient instance, which is responsible for connecting to the STS. This property must be set, if the effective security policy contains an IssuedToken policy.

    Edit the WibbleClient.xml file from the wsdl_first_https/src/demo/hw_https/client directory. Add the following jaxws:client element as a child of the beans element:

    <beans ...>
  ...
  <jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort" createdFromAPI="true">
      <jaxws:properties>
        <entry key="ws-security.sts.client"  value-ref="default.sts-client" />
      </jaxws:properties>
  </jaxws:client>
  ...
</beans>

  2. Create the STSClient bean as follows. Continue editing the WibbleClient.xml file. Add the following STSClient bean definition to the XML file as shown:

    <beans ...>
  ...
  <bean name="default.sts-client" 
    class="org.apache.cxf.ws.security.trust.STSClient">
    <constructor-arg ref="cxf"/>
    <property name="wsdlLocation" value="sts/wsdl/ws-trust-1.4-service.wsdl"/>
    <property name="serviceName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceProvider"/>
    <property name="endpointName" 
        value="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceSOAP"/>
  </bean>
  ...
</beans>

    Notice how the STSClient constructor requires a reference to the root Bus object (identified by the string, cxf, in the constructor-arg element) and the wsdlLocation attribute points to the the client's copy of the STS WSDL contract.

  3. Secure the client-STS connection with SSL/TLS. Continue editing the WibbleClient.xml file. Add the following http:conduit element as a child of the beans element:

    <beans ...>
  ...
  <http:conduit name="{http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl}SecurityTokenServiceSOAP.http-conduit">
    <http:tlsClientParameters disableCNCheck="true">
      <sec:trustManagers>
          <sec:keyStore type="JKS" password="stsspass"
                file="sts/certs/stsstore.jks"/>
      </sec:trustManagers>
      <sec:keyManagers keyPassword="password">
           <sec:keyStore type="JKS" password="password" 
                file="certs/wibble.jks"/>
      </sec:keyManagers>
      <sec:cipherSuitesFilter>
          <sec:include>.*_WITH_3DES_.*</sec:include>
          <sec:include>.*_WITH_DES_.*</sec:include>
          <sec:exclude>.*_WITH_NULL_.*</sec:exclude>
          <sec:exclude>.*_DH_anon_.*</sec:exclude>
      </sec:cipherSuitesFilter>
    </http:tlsClientParameters>
   </http:conduit>
  ...
</beans>

    Notice how the STSClient trust store is configured to use the sts/certs/stsstore.jks keystore file, enabling the STSClient to authenticate the remote STS.

    The name attribute of http:conduit follows the format, WSDLPortQName.http-conduit. Because WSDLPortQName matches the name of the STS WSDL port, these settings are automatically applied to the client proxy for the client-STS connection. For more details about the SSL/TLS security settings, see Security for HTTP-Compatible Bindings.

  4. Enable policy support and logging as follows. Continue editing the WibbleClient.xml file. Add the following cxf:bus element as a child of the beans element: 

    <beans ...>
  ...
  <cxf:bus xmlns:cxf="http://cxf.apache.org/core">
     <cxf:features>
        <p:policies xmlns:p="http://cxf.apache.org/policy"/>
        <cxf:logging/>
     </cxf:features>
  </cxf:bus>
  ...
</beans>
    [Note]Note

    It is essential to include the <p:policies> feature in the client's XML configuration. Otherwise, the policies in the WSDL file would have no effect whatsoever.

  5. Add the requisite XML schema locations. Continue editing the WibbleClient.xml file. To support the jaxws, cxf, and p namespace prefixes, add the highlighted schema locations and define the jaxws namespace prefix, as follows:

    <beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://cxf.apache.org/configuration/security"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  xsi:schemaLocation="
       http://cxf.apache.org/configuration/security
       http://cxf.apache.org/schemas/configuration/security.xsd
       http://cxf.apache.org/transports/http/configuration
       http://cxf.apache.org/schemas/configuration/http-conf.xsd
       http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
       http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans.xsd
       http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd
       http://cxf.apache.org/policy http://cxf.apache.org/schemas/policy.xsd">
...

  6. Add the requisite Maven dependencies. In order to use WS-SecurityPolicy, you need to ensure that the requisite JARs are included on the classpath. For the Maven build system, this requires you to include additional dependencies in the POM file. Edit the wsdl_first_https/pom.xml file and add dependencies on the cxf-rt-ws-security artifact and on the cxf-rt-ws-policy artifact as highlighted in the following fragment:

    <project ...>
    ...
    <dependencies>
        ...
        <dependency>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-rt-ws-security</artifactId>
            <version>2.4.0-fuse-00-27</version>
        </dependency>
        <dependency>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-rt-ws-policy</artifactId>
            <version>2.4.0-fuse-00-27</version>
        </dependency>
    </dependencies>
</project>
Comments powered by Disqus
Prev Up Next
 Home 
loading table of contents...