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-SecurityPolicy
Date Mon, 08 Feb 2010 17:23:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/CXF20DOC/WS-SecurityPolicy">WS-SecurityPolicy</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~mazzag">Glen
Mazza</a>
    </h4>
     Made configuration examples somewhat clearer (I think), added WS-SecurityPolicy blog
entry
          <div id="versionComment" class="noteMacro" style="display:none; padding: 5px;">
     Made configuration examples somewhat clearer (I think), added WS-SecurityPolicy blog
entry<br />
     </div>
          <br/>
     <div class="notificationGreySide">
         <p>CXF 2.2 introduced support for using <a href="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/ws-securitypolicy.html"
rel="nofollow">WS-SecurityPolicy</a> to configure WSS4J instead of the custom configuration
documented on the <a href="/confluence/display/CXF20DOC/WS-Security" title="WS-Security">WS&#45;Security</a>
page.  However, all of the "background" material on the <a href="/confluence/display/CXF20DOC/WS-Security"
title="WS-Security">WS&#45;Security</a> page still applies and is important to
know.   WS-SecurityPolicy just provides an easier and more standards based way to configure
and control the security requirements.   With the security requirements documented in the
WSDL as <a href="/confluence/display/CXF20DOC/WS-Policy" title="WS-Policy">WS&#45;Policy</a>
fragments, other tools such as .NET can easily know how to configure themselves to inter-operate
with CXF services.</p>

<p><b>Note:</b> at this point, WS-SecurityPolicy support is ONLY available
for "WSDL first" scenarios.   The WS-SecurityPolicy fragments can only be pulled from WSDL.
  In the future, we plan to enable various code first scenarios as well, but at this time,
only WSDL first is available.</p>

<h3><a name="WS-SecurityPolicy-EnablingWSSecurityPolicy"></a>Enabling WS-SecurityPolicy</h3>
<p>In CXF 2.2, if the cxf-rt-ws-policy and cxf-rt-ws-security modules are available
on the classpath, the WS-SecurityPolicy stuff is automatically enabled.   Since the entire
security runtime is policy driven, the only requirement is that the policy engine and security
policies be available.  </p>

<p>If you are using the full "bundle" jar, all the security and policy stuff is already
included.   </p>


<h3><a name="WS-SecurityPolicy-Policydescription"></a>Policy description</h3>
<p>With WS-SecurityPolicy, the binding and/or operation in the wsdl references a <a
href="/confluence/display/CXF20DOC/WS-Policy" title="WS-Policy">WS&#45;Policy</a>
fragment that describes the basic security requirements for interacting with that service.
  The <a href="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/ws-securitypolicy.html"
rel="nofollow">WS-SecurityPolicy specification</a> allows for specifying things like
asymmetric/symmetric keys, using transports (https) for encryption, which parts/headers to
encrypt or sign, whether to sign then encrypt or encrypt then sign, whether to include timestamps,
whether to use derived keys, etc...   Basically, it describes what actions are necessary to
securely interact with the service described in the WSDL.</p>

<p>However, the WS-SecurityPolicy fragment does not include "everything" that is required
for a runtime to be able to able to create the messages.  It does not describe things such
as locations of key stores, user names and passwords, etc...  Those need to be configured
in at runtime to augment the WS-SecurityPolicy fragment.  </p>


<h3><a name="WS-SecurityPolicy-Configuringtheextraproperties"></a>Configuring
the extra properties</h3>
<p>With CXF 2.2, there are several extra properties that may need to be set to provide
the additional bits of information to the runtime:</p>

<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> ws-security.username </td>
<td class='confluenceTd'> The username used for UsernameToken policy assertions </td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.password </td>
<td class='confluenceTd'> The password used for UsernameToken policy assertions.   If
not specified, the callback handler will be called. </td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.callback-handler </td>
<td class='confluenceTd'> The WSS4J security CallbackHandler that will be used to retrieve
passwords for keystores and UsernameTokens. </td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.signature.properties </td>
<td class='confluenceTd'> The properties file/object that contains the WSS4J properties
for configuring the signature keystore and crypto objects </td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.encryption.properties </td>
<td class='confluenceTd'> The properties file/object that contains the WSS4J properties
for configuring the encryption keystore and crypto objects </td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.signature.username </td>
<td class='confluenceTd'> The username or alias for the key in the signature keystore
that will be used.   If not specified, it uses the the default alias set in the properties
file.  If that's also not set, and the keystore only contains a single key, that key will
be used. </td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.encryption.username </td>
<td class='confluenceTd'> The username or alias for the key in the encryption keystore
that will be used.   If not specified, it uses the the default alias set in the properties
file.  If that's also not set, and the keystore only contains a single key, that key will
be used.  For the web service provider, the useReqSigCert keyword can be used to accept (encrypt
to) any client whose public key is in the service's truststore (defined in ws-security.encryption.properties.)
</td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.signature.crypto </td>
<td class='confluenceTd'> Instead of specifying the signature properties, this can point
to the full <a href="http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/components/crypto/Crypto.html"
rel="nofollow">WSS4J Crypto</a> object.  This can allow easier "programmatic" configuration
of the Crypto information."</td>
</tr>
<tr>
<td class='confluenceTd'> ws-security.encryption.crypto </td>
<td class='confluenceTd'> Instead of specifying the encryption properties, this can
point to the full <a href="http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/components/crypto/Crypto.html"
rel="nofollow">WSS4J Crypto</a> object.  This can allow easier "programmatic" configuration
of the Crypto information."</td>
</tr>
</tbody></table>

<p><b>Note:</b> for Symmetric bindings that specify a protection token,
the ws-security-encryption properties are used.</p>


<h4><a name="WS-SecurityPolicy-ConfiguringviaSpring"></a>Configuring via
Spring</h4>
<p>The properties are easily configured as client or endpoint properties--use the former
for the SOAP client, the latter for the web service provider.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;beans xmlns=<span class="code-quote">"http://www.springframework.org/schema/beans"</span>
   <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance"</span>
   <span class="code-keyword">xmlns:jaxws</span>=<span class="code-quote">"http://cxf.apache.org/jaxws"</span>
   xsi:schemaLocation="http://www.springframework.org/schema/beans 
   http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
   http://cxf.apache.org/jaxws 
   http://cxf.apache.org/schemas/jaxws.xsd"&gt;

   <span class="code-tag">&lt;jaxws:client name=<span class="code-quote">"{http://cxf.apache.org}MyPortName"</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.callback-handler"</span>
value=<span class="code-quote">"interop.client.KeystorePasswordCallback"</span>/&gt;</span>
         <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.signature.properties"</span>
value=<span class="code-quote">"etc/client.properties"</span>/&gt;</span>
         <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.encryption.properties"</span>
value=<span class="code-quote">"etc/service.properties"</span>/&gt;</span>
         <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.encryption.username"</span>
value=<span class="code-quote">"servicekeyalias"</span>/&gt;</span>
      <span class="code-tag">&lt;/jaxws:properties&gt;</span>
   <span class="code-tag">&lt;/jaxws:client&gt;</span>

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

<p>For the jaxws:client's <em>name</em> attribute above, use the namespace
of the WSDL along with the <em>name</em> attribute of the desired wsdl:port element
under the WSDL's service section. (See <a href="http://tinyurl.com/yatskw4" rel="nofollow">here</a>
and <a href="http://tinyurl.com/y9e7rjf" rel="nofollow">here</a> for an example.)</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;beans xmlns=<span class="code-quote">"http://www.springframework.org/schema/beans"</span>
   <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance"</span>
   <span class="code-keyword">xmlns:jaxws</span>=<span class="code-quote">"http://cxf.apache.org/jaxws"</span>
   xsi:schemaLocation="http://www.springframework.org/schema/beans 
   http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
   http://cxf.apache.org/jaxws 
   http://cxf.apache.org/schemas/jaxws.xsd"&gt;

   &lt;jaxws:endpoint 
      id=<span class="code-quote">"MyService"</span>
      address=<span class="code-quote">"https://localhost:9001/MyService"</span>

      serviceName=<span class="code-quote">"interop:MyService"</span>
      endpointName=<span class="code-quote">"interop:MyServiceEndpoint"</span>
      implementor=<span class="code-quote">"com.foo.MyService"</span>&gt;
        
      <span class="code-tag">&lt;jaxws:properties&gt;</span>
         <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.callback-handler"</span>
value=<span class="code-quote">"interop.client.UTPasswordCallback"</span>/&gt;</span>
         <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.signature.properties"</span>
value=<span class="code-quote">"etc/keystore.properties"</span>/&gt;</span>
         <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.encryption.properties"</span>
value=<span class="code-quote">"etc/truststore.properties"</span>/&gt;</span>
         <span class="code-tag">&lt;entry key=<span class="code-quote">"ws-security.encryption.username"</span>
value=<span class="code-quote">"useReqSigCert"</span>/&gt;</span>
      <span class="code-tag">&lt;/jaxws:properties&gt;</span> 
     
   <span class="code-tag">&lt;/jaxws:endpoint&gt;</span> 
<span class="code-tag">&lt;/beans&gt;</span>
</pre>
</div></div>

<p>See this <a href="http://www.jroller.com/gmazza/entry/cxf_x509_profile_secpol"
rel="nofollow">blog entry</a> for a more end-to-end example of using WS-SecurityPolicy
with X.509 keys.</p>

<h4><a name="WS-SecurityPolicy-ConfiguringviaAPI%27s"></a>Configuring via
API's</h4>
<p>Configuring the properties for the client just involves setting the properties in
the client's RequestContext:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;
ctx = ((BindingProvider)port).getRequestContext();
ctx.put(<span class="code-quote">"ws-security.encryption.properties"</span>, properties);
port.echoString(<span class="code-quote">"hello"</span>);
</pre>
</div></div>




     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/WS-SecurityPolicy">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=112639&revisedVersion=13&originalVersion=12">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/WS-SecurityPolicy?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message