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.clientproperty, which contains a reference to anSTSClientinstance. - Indirect configuration—no change is made to the client proxy definition, but if the Apache CXF runtime finds an appropriately named
STSClientbean in the bean registry, it will automatically inject thatSTSClientbean 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:
- Define an
STSClientbean, whosenameattribute has the value,WSDLPortQName.sts-client. - 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 theSTSClientobject. - Set the relevant properties of the
STSClientbean (typically, thewsdlLocation,serviceName, andendpointNameproperties). After theSTSClientis instantiated in Java, the properties specified in XML will be injected into theSTSClientinstance.
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>