General Configuration

There are several ways to configure the STSClient:

Direct configuration of an STSClient bean in the properties: In this scenario, a STSClient object is created directly as a property of the client object. The wsdlLocation, service/endpoint names, etc., are all configured in line for that client.

<jaxws:client name="{http://cxf.apache.org/}MyService" 
      createdFromAPI="true">
   <jaxws:properties>
      <entry key="ws-security.sts.client">
         <!-- direct STSClient config and creation -->
         <bean class="org.apache.cxf.ws.security.trust.STSClient">
            <constructor-arg ref="cxf"/>
            <property name="wsdlLocation" value="target/wsdl/trust.wsdl"/>
            <property name="serviceName" value=
               "{http://cxf.apache.org/securitytokenservice} ...
               SecurityTokenService"/>
            <property name="endpointName" value=
               "{http://cxf.apache.org/securitytokenservice} ...
               SecurityTokenEndpoint"/>
            <property name="properties">
               <map>
                 <entry key="ws-security.username" value="alice"/>
                 <entry key="ws-security.callback-handler" 
                    value="client.MyCallbackHandler"/>
                 <entry key="ws-security.signature.properties" 
                    value="clientKeystore.properties"/>
                 <entry key="ws-security.encryption.properties" 
                    value="clientKeystore.properties"/>
                 <entry key="ws-security.encryption.username" 
                    value="mystskey"/> 
               </map>
            </property>
         </bean>            
      </entry> 
   </jaxws:properties>
</jaxws:client>

The above example shows a configuration where the STS uses the UsernameToken profile to validate the client. It is assumed the keystore identified within clientKeystore.properties contains both the private key of the client and the public key (identified above as mystskey) of the STS; if not, create separate property files for the signature properties and the encryption properties, pointing to the keystore and truststore respectively.

Remember the jaxws:client createdFromAPI attribute needs to be set to true (as shown above) if you created the client programmatically via the CXF API's--i.e., Endpoint.publish() or Service.getPort().

This also works for "code first" cases as you can do:

STSClient sts = new STSClient(...);
sts.setXXXX(....)
.....
((BindingProvider)port).getRequestContext().
   put("ws-security.sts.client", sts);

Sample clientKeystore.properties format:

org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=KeystorePasswordHere
org.apache.ws.security.crypto.merlin.keystore.alias=ClientKeyAlias
org.apache.ws.security.crypto.merlin.keystore.file=NameOfKeystore.jks

Indirect configuration based on endpoint name: If the runtime does not find a STSClient bean configured directly on the client, it checks the configuration for a STSClient bean with the name of the endpoint appended with ".sts-client". For example, if the endpoint name for your client is "{http://cxf.apache.org/}TestEndpoint", then it can be configured as:

<bean name="{http://cxf.apache.org/}TestEndpoint.sts-client" 
   class="org.apache.cxf.ws.security.trust.STSClient" abstract="true">
   <property name="wsdlLocation" value="WSDL/wsdl/trust.wsdl"/>
   <property name="serviceName" value=
      "{http://cxf.apache.org/securitytokenservice} ...
      SecurityTokenService"/>
   <property name="endpointName" value=
      "{http://cxf.apache.org/securitytokenservice} ...
      SecurityTokenEndpoint"/>
   <property name="properties">
      <map>
         <entry key="ws-security.signature.properties" 
            value="etc/alice.properties"/> 
         <entry key="ws-security.encryption.properties" 
            value="etc/bob.properties"/>   
         <entry key="ws-security.encryption.username"
            value="stskeyname"/> 
      </map>
   </property>
</bean>

This properties configured in this example demonstrate STS validation of the client using the X.509 token profile. The abstract="true" setting for the bean defers creation of the STSClient object until it is actually needed. When that occurs, the CXF runtime will instantiate a new STSClient using the values configured for this bean.

Default configuration: If an STSClient is not found from the above methods, it then tries to find one configured like the indirect, but with the name "default.sts-client". This can be used to configure sts-clients for multiple services.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – please let us know!

Leave your feedback here