Red Hat Training

A Red Hat training course is available for Red Hat Fuse

8.4. Creating an STSClient Instance

Overview

Whenever an IssuedToken policy is configured on a WSDL port, you must also configure the client to connect to an STS server to obtain a token. The code for connecting to the STS and obtaining a token is implemented by the following class: 
org.apache.cxf.ws.security.trust.STSClient
The client must explicitly create an STSClient instance to manage the client-STS connection. You can do this in either of the following ways:
  • Direct configuration—the client proxy is configured with the security.sts.client property, which contains a reference to an STSClient instance.
  • Indirect configuration—no change is made to the client proxy definition, but if the Apache CXF runtime finds an appropriately named STSClient bean in the bean registry, it will automatically inject that STSClient bean into the client proxy.
In addition to creating an STSClient instance, it is usually also necessary to enable SSL/TLS security on the STS proxy.

Direct configuration

In the case of direct configuration, your JAX-WS client proxy references an STSClient instance directly, by setting the security.sts.client property on the client proxy. The value of security.sts.client must be a reference to an STSClient instance.
For example, the following XML configuration shows how to instantiate a JAX-WS client proxy that references the STSClient with bean ID equal to default.sts-client (the bean ID is the same as the value of the name attribute): 
<beans ...>
  ...
  <jaxws:client
    id="helloWorldProxy"
    serviceClass="org.apache.hello_world_soap_http.Greeter"
    address="https://localhost:9001/SoapContext/SoapPort">
    <jaxws:properties>
      <entry key="security.sts.client" 
             value-ref="default.sts-client" />
    </jaxws:properties>
  </jaxws:client>
  ...
  <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>

Indirect configuration

In the case of indirect configuration, there is no need to set any property on the JAX-WS client proxy. Implicitly, if the IssuedToken policy assertion is applied to the relevant WSDL port, the runtime automatically searches for an STSClient bean named, WSDLPortQName.sts-client. To configure the STSClient bean indrectly, perform the following steps:
  1. Define an STSClient bean, whose name attribute has the value, WSDLPortQName.sts-client.
  2. Set abstract="true" on the bean element. This prevents Spring from instantiating the bean. The reason for this is that the runtime is responsible for the lifecycle of the STSClient object.
  3. Set the relevant properties of the STSClient bean (typically, the wsdlLocation, serviceName, and endpointName properties). After the STSClient is instantiated in Java, the properties specified in XML will be injected into the STSClient instance.
For example, the following XML configuration creates a JAX-WS client proxy, which is associated with the {http://apache.org/hello_world_soap_http}SoapPort port (this is specified in an annotation on the service class, Greeter). When the client proxy needs to fetch an issued token for the first time, the runtime automatically creates an STSClient instance, searches for the bean named WSDLPortQName.sts-client, and injects the properties from that bean into the STSClient instance. 
<beans ...>
  ...
  <jaxws:client
    id="helloWorldProxy"
    serviceClass="org.apache.hello_world_soap_http.Greeter"
    address="https://localhost:9001/SoapContext/SoapPort"
    />
  ...
  <bean name="{http://apache.org/hello_world_soap_http}SoapPort.sts-client" 
    class="org.apache.cxf.ws.security.trust.STSClient"
    abstract="true">
    <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>