WS-Trust

From commits-return-13721-apmail-cxf-commits-archive=cxf.apache.org@cxf.apache.org Thu Feb 03 21:24:23 2011
Return-Path: 
Delivered-To: apmail-cxf-commits-archive@www.apache.org
Received: (qmail 2769 invoked from network); 3 Feb 2011 21:24:23 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 3 Feb 2011 21:24:23 -0000
Received: (qmail 33248 invoked by uid 500); 3 Feb 2011 21:24:23 -0000
Delivered-To: apmail-cxf-commits-archive@cxf.apache.org
Received: (qmail 33149 invoked by uid 500); 3 Feb 2011 21:24:22 -0000
Mailing-List: contact commits-help@cxf.apache.org; run by ezmlm
Precedence: bulk
List-Help: 
List-Unsubscribe: 
List-Post: 
List-Id: 
Reply-To: dev@cxf.apache.org
Delivered-To: mailing list commits@cxf.apache.org
Received: (qmail 33142 invoked by uid 99); 3 Feb 2011 21:24:22 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 03 Feb 2011 21:24:22 +0000
X-ASF-Spam-Status: No, hits=-1994.3 required=5.0
	tests=ALL_TRUSTED,HTML_MESSAGE,MIME_HTML_ONLY
X-Spam-Check-By: apache.org
Received: from [140.211.11.22] (HELO thor.apache.org) (140.211.11.22)
    by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 03 Feb 2011 21:24:21 +0000
Received: from thor (localhost [127.0.0.1])
	by thor.apache.org (8.13.8+Sun/8.13.8) with ESMTP id p13LO0nP002809
	for ; Thu, 3 Feb 2011 21:24:00 GMT
Date: Thu, 3 Feb 2011 16:24:00 -0500 (EST)
From: confluence@apache.org
To: commits@cxf.apache.org
Message-ID: <13235154.3742.1296768240339.JavaMail.root@thor>
Subject: [CONF] Apache CXF Documentation > WS-Trust
MIME-Version: 1.0
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit
Auto-Submitted: auto-generated

    WS-Trust
    Page edited by             Glen Mazza

        Comment:
        Removed undocumented sts.token.properties and callback-handler from X.509 case, as unneeded for Symmetric w. X.509 authentication.

                         Changes (2)

            ...

                <property name="properties"> 
        <map> 

                        <entry key="ws-security.sts.token.properties" value="etc/bob.properties"/>   
            <entry key="ws-security.callback-handler" value="interop.client.KeystorePasswordCallback"/> 

                        <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> 

            ...

                            Full Content

        WS-Trust

WS-Trust support in CXF builds upon the WS-SecurityPolicy implementation to handle the IssuedToken policy assertions that could be found in the WS-SecurityPolicy fragment.  

Note: Because the WS-IssuedToken support builds on the WS-SecurityPolicy support, this is currently only available to "wsdl first" projects.

WS-Trust extends the WS-Security specification to allow issuing, renewing, and validation of security tokens.  A lot of what WS-Trust does centers around the use of a "Security Token Service", or STS.   The STS is contacted to obtain security tokens that are used to create messages to talk to the services.    The primary use of the STS is to acquire SAML tokens used to talk to the service.   Why is this interesting?

When using "straight" WS-Security, the client and server need to have keys exchanged in advance.   If the client and server are both in the same security domain, that isn't usually a problem, but for larger, complex applications spanning multiple domains, that can be a burden.  Also, if multiple services require the same security credentials, updating all the services when those credentials change can by a major operation.   

WS-Trust solves this by using security tokens that are obtained from a trusted Security Token Service.   A client authenticates itself with the STS based on policies and requirements defined by the STS.   The STS then provides a security token (example: a SAML token) that the client then uses to talk to the target service.  The service can validate that token to make sure it really came from the trusted STS.  

When the WS-SecurityPolicy runtime in CXF encounters an IssuedToken assertion in the policy, the runtime requries an instance of  org.apache.cxf.ws.security.trust.STSClient to talk to the STS to obtain the required token.    Since the STSClient is a WS-SecurityPolicy client, it will need configuration items to be able to create it's secure SOAP messages to talk to the STS.  

General Configuration

There are several ways to configure the STSClient:

Direct configuration of an STS 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.provider=org.apache.ws.security.components.crypto.Merlin
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.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.

WS-Trust 1.4 Support

CXF provides limited support of WS-Trust 1.4.  The currently supported features are listed below.

ActAs (2.2.10)
The ActAs capability allows an initiator to request a security token that allows it to act as if it were somebody else.  This capability becomes important in composite services where intermediate services make additional requests on-behalf of the true initiator.  In this scenario, the relying party (the final destination of an indirect service request) may require information about the true origin of the request.  The ActAs capability allows an intermediary to request a token that can convey this information.

The following code fragment demonstrates how to use an interceptor to dynamically set the content of the ActAs element in the STS RST.  The value may be a string containing well-formed XML or a DOM Element.  The contents will be added to the RST verbatim.  Note that this interceptor is applied to the secured client, the initiator, and not to the STSClient's interceptor chain.

public class ActAsOutInterceptor extends AbstractPhaseInterceptor<Message> {

    ActAsOutInterceptor () {
        // This can be in any stage before the WS-SP interceptors
        // setup the STS client and issued token interceptor.
        super(Phase.SETUP);
    }

    @Override
    public void handleMessage(Message message) throws Fault {

        message.put(SecurityConstants.STS_TOKEN_ACT_AS, ...);

    }
}

Alternatively, the ActAs content may be set directly on the STS as shown below.

<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="actAs" value="..."/>
    <property name="properties">
        <map>
            <entry key="ws-security.sts.token.properties" value="etc/bob.properties"/>  
            <entry key="ws-security.callback-handler" value="interop.client.KeystorePasswordCallback"/>
            <entry key="ws-security.signature.properties" value="etc/alice.properties"/> 
            <entry key="ws-security.encryption.properties" value="etc/bob.properties"/>	
        </map>
    </property>
</bean>

            Change Notification Preferences

        View Online
        |
        View Changes
                |
        Add Comment