Apache CXF STS client configuration options

Apache CXF provides a Security Token Service (STS), which can issue (as well as validate, renew + cancel) security tokens using the WS-Trust protocol. A common SOAP security scenario is where a service provider requires that a client must authenticate itself to the service, by geting a token from an STS and including it in the service request. In this article, we will explore different ways of configuring the client with details of how to communicate with the STS, as well as how the service provider can provide these details to the client.

1) IssuedToken policies

The service provider can require that a client retrieve a security token from an STS by specifying a WS-SecurityPolicy IssuedToken policy (for example, in the WSDL of the service). The following IssuedToken policy fragment (see here for a concrete example) tells the client that it must include a SAML 1.1 token in the request. In addition, the token must include the client's PublicKey, the corresponding private key of which must be used to secure the request in some way (SOAP Message Signature, TLS client authentication):

<sp:IssuedToken
    sp:IncludeToken=".../IncludeToken/AlwaysToRecipient">
    <sp:RequestSecurityTokenTemplate>
        <t:TokenType>http://.../oasis-wss-saml-token-profile-1.1#SAMLV1.1</t:TokenType>
        <t:KeyType>http://.../ws-trust/200512/PublicKey</t:KeyType>
    </sp:RequestSecurityTokenTemplate>
</sp:IssuedToken>

2) STSClient configuration

So the CXF client will know that it must get a SAML 1.1 token from an STS when it sees the above policy, and that it must present the STS with a X.509 Certificate, so that the STS can embed it in the issued token. How does it know how to contact the STS? Typically, this is defined in an STSClient bean. The following configuration (see here for a concrete example), specifies the WSDL location of the STS, as well as the Service + Port QNames to use, as well as some additional security configuration:

<bean id="stsClient" class="org.apache.cxf.ws.security.trust.STSClient">
       <property name="wsdlLocation"
                 value="https://localhost:8443/SecurityTokenService/Transport?wsdl"/>
       <property name="serviceName"
                 value="{http://.../ws-trust/200512/}SecurityTokenService"/>
       <property name="endpointName"
                 value="{http://.../ws-trust/200512/}Transport_Port"/>
       <property name="properties">
           <map>
               <entry key="ws-security.username" value="alice"/>
               <entry key="ws-security.callback-handler"
                      value="org.apache.cxf.systest.sts.common.CommonCallbackHandler"/>
               <entry key="ws-security.sts.token.username" value="myclientkey"/>
               <entry key="ws-security.sts.token.properties" value="clientKeystore.properties"/>
               <entry key="ws-security.sts.token.usecert" value="true"/>
           </map>
        </property>
</bean>

While this type of configuration works well, it has a few drawbacks:

• The client must have the WSDL (location) of the STS (as well as service + port QNames). 
• The service can't communicate to the client which STS address to use (as well as service + port QNames).

Apache CXF provides two ways of addressing the limitations given above, that will be described in the next two points.

3) Communicating the STS address + service/port QNames to the client

From Apache CXF 2.7.8 it is possible for the service to communicate the STS address and service/port QNames to the client in a simple way (as opposed to using WS-MEX, as will be covered in the next section). This is illustrated by the IssuerTest.testSAML1Issuer in the CXF source. The IssuedToken policy of the service provider, has an additional child policy:

<sp:Issuer>
    <wsaw:Address>https://.../SecurityTokenService/Transport</wsaw:Address>
    <wsaw:Metadata xmlns:wst="http://.../ws-trust/200512/">
        <wsam:ServiceName EndpointName="Transport_Port">
            wst:SecurityTokenService
        </wsam:ServiceName>
    </wsaw:Metadata>
</sp:Issuer>

The "Address" Element communicates the STS address, and the "ServiceName" Element communicates the Service + Endpoint QNames to the client. With this configuration in the WSDL, the client configuration is greatly simplified. Instead of specifying the WSDL Location + Service/Port QNames, the client now only has to specify the security policy to be used in communicating with the STS. It also must set the security configuration tag "ws-security.sts.disable-wsmex-call-using-epr-address" to "true", to avoid using WS-MEX.

An obvious disadvantage to this method is that it still requires the client to have access to the security policy of the STS. However, it at least is a simple way of avoiding hardcoding service host + port numbers in client configuration. A more sophisticated method is to use WS-MEX, as will be described in the next section.

4) Using WS-MetadataExchange (WS-MEX)

The best way for the service to communicate details of the STS to the client is via WS-MetadataExchange (WS-MEX). This is illustrated by the IssuerTest.testSAML2MEX in the CXF source. The IssuedToken policy of the service provider has an Issuer policy that looks like:

<sp:Issuer>
    <wsaw:Address>https://.../SecurityTokenService/Transport</wsaw:Address>
    <wsaw:Metadata>
        <wsx:Metadata>
            <wsx:MetadataSection>
                <wsx:MetadataReference>
                    <wsaw:Address>https://.../SecurityTokenService/Transport/mex</wsaw:Address>
                </wsx:MetadataReference>
            </wsx:MetadataSection>
        </wsx:Metadata>
    </wsaw:Metadata>
</sp:Issuer>

The client uses the Metadata address to obtain the WSDL of the STS. A CXF Endpoint supports WS-MetadataExchange via a "/mex" suffix, when "cxf-rt-ws-mex" is on the classpath. Note that the client configuration does not need to define an STSClient Object at all any more, only to provide some security configuration for the request to the STS. The client first makes a call to the STS to get the WSDL that looks like:

<soap:Envelope>
    <soap:Header>
        <Action xmlns=".../addressing">http://schemas.xmlsoap.org/ws/2004/09/transfer/Get</Action>
       <MessageID xmlns=".../addressing">urn:uuid:1db606be-695b-46d4-8759-fe9d41746b42</MessageID>
       <To xmlns=".../addressing">https://.../SecurityTokenService/Transport/mex</To>
       <ReplyTo xmlns=".../addressing"><Address>.../addressing/anonymous</Address></ReplyTo>
   </soap:Header>
   <soap:Body/>
</soap:Envelope>

The STS responds with the WSDL embedded in the SOAP Body under a "Metadata" Element. The client then matches the Address defined in the Issuer policy with an endpoint address in the WSDL and uses the corresponding Service/Endpoint QName to invoke on the STS. Alternatively, the service could specify explicit QNames as per the previous example.

XKMS functionality in Apache CXF

Talend has recently donated an XKMS 2.0 implementation to Apache CXF, which is available from the CXF 2.7.7 release. It is documented on the CXF wiki here. The XKMS implementation consists of two parts. Firstly, an XKMS service is provided that exposes a SOAP interface that allows users to register X.509 certificates, as well as to both locate and validate X.509 certificates. Secondly, an implementation of the WSS4J Crypto interface is provided which allows a (WS-Security based) client to both find and validate certificates via the XKMS service.

This blog post will focus on a simple WS-Security system test in CXF, and how it uses XKMS for certificate location and validation. For more detailed information on XKMS, and how it is implemented in CXF, check out my Talend colleague Andrei Shakirin's excellent blog posts on XKMS.

1) XKMS system test with WS-Security

WS-Security is used to secure SOAP service requests/responses at the message level. How this is done is defined by a WS-SecurityPolicy fragment, which is usually defined in the WSDL of the service. Some additional configuration is required by CXF clients and services, such as what username to use, a CallbackHandler implementation to get passwords, and the location of property files which contain WSS4J Crypto configuration for signing and encrypting. See the following wiki and system tests for more information on using WS-Security and WS-SecurityPolicy in CXF.

The WS-SecurityPolicy specification defines two security "bindings" for use in securing SOAP messages at the message level - the "Symmetric" and "Asymmetric" bindings. With the Symmetric binding, the client creates a secret key to secure the message, and then uses the certificate of the service to encrypt the secret key, so that only the service can decrypt the secured message. The Asymmetric binding assumes that both the client and service have public/private key-pairs, and hence the client signs the request using its private key, and encrypts the request using the service's public key.

In each case, the client (typically) must have access to an X.509 certificate for the service. It must "locate" a certificate for the service on the outbound side for both the Symmetric and Asymmetric bindings, and it must "validate" the certificate used by the service to sign the response in the "Asymmetric" case. Up to now, the default WSS4J Crypto implementation (Merlin) uses a local Java keystore to obtain certificates. However, given that the tasks the client must perform ("locate" and "validate") map directly to XKMS operations, it's possible to use the new XKMS Crypto implementation instead.

The XkmsCryptoProvider is configured with a JAX-WS client proxy which can locate/validate X.509 Certificates from a remote XKMS SOAP service. Additionally, it can be composed with another Crypto implementation from which private keys can be retrieved (for example, when used for the Asymmetric Binding). It can also be configured with a cache to prevent repeated remote calls to the XKMS service to locate or validate a particular certificate. The default cache is based on EhCache.

Aside from the obvious advantages of being able to centralize certificate management by using XKMS, a cool additional advantage is that the client need have no local key information at all for the Symmetric binding, as it only requires the X.509 certificate of the message recipient, and no private key. This could greatly simplify key management in a large deployment.

Let's tie all of the above information on combining WS-Security with XKMS together by looking at some CXF system tests. The tests are available in the CXF WS-Security systests directory. The test source is here and test configuration files are available here. The tests show how to deploy an XKMS Service, and how to configure a JAX-WS client with the XKMS Crypto implementation to locate and validate certificates for a service invocation over both the Symmetric and Asymmetric bindings.

2) The XKMS Service

The XKMS service configuration for the test is available here. It describes a JAX-WS endpoint that can only be accessed over TLS. The endpoint implements the standard XKMS interface. A certificate repository is defined as follows:

<bean id="certificateRepo"
    class="org.apache.cxf.xkms.x509.repo.file.FileCertificateRepo">
    <constructor-arg value="src/test/resources/certs/xkms" />
</bean>

This is a simple file based certificate repository, where certificates are stored in a single directory on the filesystem (see here). A more appropriate implementation for the enterprise is the LDAP certificate repository, which is documented on the wiki. The service defines a single XKMS "locator":

<bean id="x509Locator"
    class="org.apache.cxf.xkms.x509.handlers.X509Locator">
    <constructor-arg ref="certificateRepo" />
</bean>

In other words, any "locate" query will try to find certificates in the file certificate store we have defined above. Similarly, two XKMS "validators" are configured:

<bean id="dateValidator"
    class="org.apache.cxf.xkms.x509.validator.DateValidator" />
<bean id="trustedAuthorityValidator"
    class="org.apache.cxf.xkms.x509.validator.TrustedAuthorityValidator">
    <constructor-arg ref="certificateRepo" />
</bean>

The first will validate that a given certificate is "in date". The second will look for a trusted certificate authority for the certificate in the certificate repo (under the "trusted_cas" subdirectory).

3) The JAX-WS client

Here we will just focus on the configuration for the client for the Symmetric binding use-case. It is configured as follows:

<jaxws:client
    name="{http://www.example.org/contract/DoubleIt}DoubleItSymmetricPort"
    createdFromAPI="true">
    <jaxws:properties>
        <entry key="ws-security.encryption.crypto" value-ref="xkmsCrypto"/>
        <entry key="ws-security.encryption.username" value="CN=bob, OU=eng, O=apache.org"/>
    </jaxws:properties>
</jaxws:client>

The client specifies an encryption username that corresponds to the Subject DN of the message recipient. It can also search for a certificate by the service "{serviceNamespace}serviceName" QName. The encrytion Crypto object is a reference to the XKMSCryptoProvider, which in turn is simply configured with the URL of the XKMS Service:

<bean id="xkmsClient"
    class="org.apache.cxf.xkms.client.XKMSClientFactory"
    factory-method="create">
    <constructor-arg>
        <value>https://localhost:${testutil.ports.XKMSServer}/XKMS</value>
    </constructor-arg>
    <constructor-arg ref="cxf"/>
</bean>

<bean id="xkmsCrypto"
    class="org.apache.cxf.xkms.crypto.impl.XkmsCryptoProvider">
    <constructor-arg>
        <ref bean="xkmsClient" />
    </constructor-arg>
</bean>

Before the service request, the client queries the XKMS service to locate an appropriate certificate using the configured encryption username:

Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:LocateRequest xmlns:ns2="http://www.w3.org/2002/03/xkms#" xmlns:ns3="http://www.w3.org/2001/04/xmlenc#" xmlns:ns4="http://www.w3.org/2000/09/xmldsig#" xmlns:ns5="http://www.w3.org/2002/03/xkms#wsdl" Id="6a17ae45-21a2-4484-b5ec-c71b04dda0b2" Service="http://cxf.apache.org/services/XKMS/"><ns2:QueryKeyBinding><ns2:UseKeyWith Application="urn:ietf:rfc:2459" Identifier="CN=bob, OU=eng, O=apache.org"/></ns2:QueryKeyBinding></ns2:LocateRequest></soap:Body></soap:Envelope>

The XKMS Service responds with:

Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:LocateResult xmlns:ns2="http://www.w3.org/2002/03/xkms#" xmlns:ns3="http://www.w3.org/2001/04/xmlenc#" xmlns:ns4="http://www.w3.org/2000/09/xmldsig#" xmlns:ns5="http://www.w3.org/2002/03/xkms#wsdl" ResultMajor="http://www.w3.org/2002/03/xkms#Success" RequestId="6a17ae45-21a2-4484-b5ec-c71b04dda0b2" Id="I-2984733849747242496" Service="http://cxf.apache.org/services/XKMS/"><ns2:UnverifiedKeyBinding><ns4:KeyInfo><ns4:X509Data><ns4:X509Certificate>MIIC...</ns4:X509Certificate></ns4:X509Data></ns4:KeyInfo></ns2:UnverifiedKeyBinding></ns2:LocateResult></soap:Body></soap:Envelope>

This certificate is then used to secure the service request using the Symmetric binding policy. For the Asymmetric testcase, the client also "validates" the certificate used by the service to secure the response.