cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > WS-Trust
Date Wed, 22 Feb 2012 13:04:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-Trust">WS-Trust</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~coheigea@apache.org">Colm
O hEigeartaigh</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >&lt;/bean&gt; <br>{code}
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>h2. WS-Trust using SPNego <br> <br>As of CXF 2.4.7 and 2.5.3, CXF contains
(client) support for WS-Trust using SPNego. See the following [blog|http://coheigea.blogspot.com/2012/02/ws-trust-spnego-support-in-apache-cxf.html]
for an explanation of what this entails, and how to run some system tests in CXF for this
feature.  <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="WS-Trust-WSTrust"></a>WS-Trust</h1>

<p>WS-Trust support in CXF builds upon the <a href="/confluence/display/CXF20DOC/WS-SecurityPolicy"
title="WS-SecurityPolicy">WS&#45;SecurityPolicy</a> implementation to handle
the IssuedToken policy assertions that could be found in the WS-SecurityPolicy fragment. 
</p>

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


<p>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?</p>

<p>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.   </p>

<p>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.  </p>


<p>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.  </p>

<h2><a name="WS-Trust-GeneralConfiguration"></a>General Configuration</h2>

<p>There are several ways to configure the STSClient:</p>

<p><b>Direct configuration of an STS bean in the properties:</b><br/>
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.
 </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;jaxws:client name=<span class="code-quote">"{http://cxf.apache.org/}MyService"</span>
createdFromAPI=<span class="code-quote">"true"</span>&gt;</span>
    <span class="code-tag">&lt;jaxws:properties&gt;</span>
        <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.sts.client"</span>&gt;</span>
            <span class="code-tag"><span class="code-comment">&lt;!-- direct
STSClient config and creation --&gt;</span></span>
            <span class="code-tag">&lt;bean class=<span class="code-quote">"org.apache.cxf.ws.security.trust.STSClient"</span>&gt;</span>
                <span class="code-tag">&lt;constructor-arg ref=<span class="code-quote">"cxf"</span>/&gt;</span>
                &lt;property name=<span class="code-quote">"wsdlLocation"</span>

                   value=<span class="code-quote">"target/wsdl/trust.wsdl"</span>/&gt;
                &lt;property name=<span class="code-quote">"serviceName"</span>

                   value=<span class="code-quote">"{http://cxf.apache.org/securitytokenservice}SecurityTokenService"</span>/&gt;
                &lt;property name=<span class="code-quote">"endpointName"</span>

                   value=<span class="code-quote">"{http://cxf.apache.org/securitytokenservice}SecurityTokenEndpoint"</span>/&gt;
                <span class="code-tag">&lt;property name=<span class="code-quote">"properties"</span>&gt;</span>
                    <span class="code-tag">&lt;map&gt;</span>
                       <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.username"</span>
value=<span class="code-quote">"alice"</span>/&gt;</span>
                       &lt;entry key=<span class="code-quote">"ws-security.callback-handler"</span>

                          value=<span class="code-quote">"client.MyCallbackHandler"</span>/&gt;
                       &lt;entry key=<span class="code-quote">"ws-security.signature.properties"</span>

                          value=<span class="code-quote">"clientKeystore.properties"</span>/&gt;
                       &lt;entry key=<span class="code-quote">"ws-security.encryption.properties"</span>

                          value=<span class="code-quote">"clientKeystore.properties"</span>/&gt;
                       &lt;entry key=<span class="code-quote">"ws-security.encryption.username"</span>

                          value=<span class="code-quote">"mystskey"</span>/&gt;

                    <span class="code-tag">&lt;/map&gt;</span>
                <span class="code-tag">&lt;/property&gt;</span>
            <span class="code-tag">&lt;/bean&gt;</span>            
        <span class="code-tag">&lt;/entry&gt;</span> 
    <span class="code-tag">&lt;/jaxws:properties&gt;</span>
<span class="code-tag">&lt;/jaxws:client&gt;</span>
</pre>
</div></div>

<p>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.</p>

<p>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().</p>

<p>This also works for "code first" cases as you can do:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
STSClient sts = <span class="code-keyword">new</span> STSClient(...);
sts.setXXXX(....)
.....
((BindingProvider)port).getRequestContext().put(<span class="code-quote">"ws-security.sts.client"</span>,
sts);
</pre>
</div></div>

<p>Sample clientKeystore.properties format:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
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 
</pre>
</div></div>

<p><b>Indirect configuration based on endpoint name:</b><br/>
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 "{<a href="http://cxf.apache.org/"
class="external-link" rel="nofollow">http://cxf.apache.org/</a>}TestEndpoint", then
it can be configured as:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;bean name=<span class="code-quote">"{http://cxf.apache.org/}TestEndpoint.sts-client"</span>

    class=<span class="code-quote">"org.apache.cxf.ws.security.trust.STSClient"</span>
abstract=<span class="code-quote">"true"</span>&gt;
    <span class="code-tag">&lt;property name=<span class="code-quote">"wsdlLocation"</span>
value=<span class="code-quote">"WSDL/wsdl/trust.wsdl"</span>/&gt;</span>
    &lt;property name=<span class="code-quote">"serviceName"</span> 
        value=<span class="code-quote">"{http://cxf.apache.org/securitytokenservice}SecurityTokenService"</span>/&gt;
    &lt;property name=<span class="code-quote">"endpointName"</span> 
        value=<span class="code-quote">"{http://cxf.apache.org/securitytokenservice}SecurityTokenEndpoint"</span>/&gt;
    <span class="code-tag">&lt;property name=<span class="code-quote">"properties"</span>&gt;</span>
        <span class="code-tag">&lt;map&gt;</span>
            &lt;entry key=<span class="code-quote">"ws-security.signature.properties"</span>

                value=<span class="code-quote">"etc/alice.properties"</span>/&gt;

            &lt;entry key=<span class="code-quote">"ws-security.encryption.properties"</span>

                value=<span class="code-quote">"etc/bob.properties"</span>/&gt;

            <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.encryption.username"</span>
value=<span class="code-quote">"stskeyname"</span>/&gt;</span>	
        <span class="code-tag">&lt;/map&gt;</span>
    <span class="code-tag">&lt;/property&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
</pre>
</div></div>

<p>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.</p>

<p><b>Default configuration:</b><br/>
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.</p>

<h2><a name="WS-Trust-WSTrust1.4Support"></a>WS-Trust 1.4 Support</h2>

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

<h3><a name="WS-Trust-ActAs%282.2.10%29"></a>ActAs (2.2.10)</h3>
<p>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.</p>

<p>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.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class ActAsOutInterceptor <span class="code-keyword">extends</span>
AbstractPhaseInterceptor&lt;Message&gt; {
   
    ActAsOutInterceptor () {
        <span class="code-comment">// This can be in any stage before the WS-SP interceptors
</span>        <span class="code-comment">// setup the STS client and issued token
interceptor.
</span>        <span class="code-keyword">super</span>(Phase.SETUP);
    }

    @Override
    <span class="code-keyword">public</span> void handleMessage(Message message)
<span class="code-keyword">throws</span> Fault {

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

    }
}
</pre>
</div></div>

<p>Alternatively, the ActAs content may be set directly on the STS as shown below.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;bean name=<span class="code-quote">"{http://cxf.apache.org/}TestEndpoint.sts-client"</span>

    class=<span class="code-quote">"org.apache.cxf.ws.security.trust.STSClient"</span>
abstract=<span class="code-quote">"true"</span>&gt;
    <span class="code-tag">&lt;property name=<span class="code-quote">"wsdlLocation"</span>
value=<span class="code-quote">"WSDL/wsdl/trust.wsdl"</span>/&gt;</span>
    &lt;property name=<span class="code-quote">"serviceName"</span> 
        value=<span class="code-quote">"{http://cxf.apache.org/securitytokenservice}SecurityTokenService"</span>/&gt;
    &lt;property name=<span class="code-quote">"endpointName"</span> 
        value=<span class="code-quote">"{http://cxf.apache.org/securitytokenservice}SecurityTokenEndpoint"</span>/&gt;
    <span class="code-tag">&lt;property name=<span class="code-quote">"actAs"</span>
value=<span class="code-quote">"..."</span>/&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"properties"</span>&gt;</span>
        <span class="code-tag">&lt;map&gt;</span>
            &lt;entry key=<span class="code-quote">"ws-security.sts.token.properties"</span>

                value=<span class="code-quote">"etc/bob.properties"</span>/&gt;
 
            &lt;entry key=<span class="code-quote">"ws-security.callback-handler"</span>

                value=<span class="code-quote">"interop.client.KeystorePasswordCallback"</span>/&gt;
            &lt;entry key=<span class="code-quote">"ws-security.signature.properties"</span>

                value=<span class="code-quote">"etc/alice.properties"</span>/&gt;

            &lt;entry key=<span class="code-quote">"ws-security.encryption.properties"</span>

                value=<span class="code-quote">"etc/bob.properties"</span>/&gt;

        <span class="code-tag">&lt;/map&gt;</span>
    <span class="code-tag">&lt;/property&gt;</span>
<span class="code-tag">&lt;/bean&gt;</span>
</pre>
</div></div>

<h2><a name="WS-Trust-WSTrustusingSPNego"></a>WS-Trust using SPNego</h2>

<p>As of CXF 2.4.7 and 2.5.3, CXF contains (client) support for WS-Trust using SPNego.
See the following <a href="http://coheigea.blogspot.com/2012/02/ws-trust-spnego-support-in-apache-cxf.html"
class="external-link" rel="nofollow">blog</a> for an explanation of what this entails,
and how to run some system tests in CXF for this feature. </p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-Trust">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=112641&revisedVersion=14&originalVersion=13">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-Trust?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message