Specifying WS-SecurityPolicy, RM, Policy in a WSDL file

WS-Policy provides a way for the provider of a web service to convey conditions under which it provides the service. A invoker might use this policy to decide whether to use or not to use the service.WS-Policy just gives basic assertion support like, <wsp:all></wsp:all>, <wsp:exactlyone></wsp:exactlyone>to express one set of policy or alternatives too. Any conditions/requirements as assertions under <wsp:all></wsp:all>become mandatory,where as assertions inside <wsp:exactlyone></wsp:exactlyone>are considered as alternatives to each other.You can read more about various combinations/interactions/alternative in OASIS WS-PolicySpecification[1].

• You can specify these WS-Poilcy assertions either inside input , output,fault, operation, port, or in binding wsdl elements.
• You can either put them directly as child elements of them, or else you can refer them using <wsp:PolicyReference> element.

Policy can be attached as described by WS-PolicyAttached [4] at following levels:

• Service Level: {Applied at <wsdl:Service>} - A policy associated with a service policy subject applies to any message exchange using any of the endpoints offered by that service.

• Endpoint Level: {Applied at <wsdl:port> or <wsdl:portType> or <wsdl:binding>} - Since <wsdl:portType> can be used with multiple Bindings, hence it is RECOMMENDED to specify only abstract policy (binding independent) at this <wsdl:portType>. I prefer to use the other two options <wsdl:port> or <wsdl:binding> to apply endpoint policy. Policies associated with an endpoint policy subject apply to any message exchange made using that endpoint.

• Operation Level: {Applied at <wsdl:portType/wsdl:operation> or <wsdl:binding/wsdl:operation>} - Policies associated with an operation policy subject apply to the message exchange described by that operation. Again, it is RECOMMENDED to specify only abstract policy at <wsdl:portType/wsdl:operation>, hence <wsdl:binding/wsdl:operation> is a prefered place to specify operation level policies.

• Message Level: {Applied at <wsdl:message> or <wsdl:portType/wsdl:operation/wsdl:input> or <wsdl:portType/wsdl:operation/wsdl:output> or <wsdl:portType/wsdl:operation/wsdl:fault> or <wsdl:binding/wsdl:operation/wsdl:input> or <wsdl:binding/wsdl:operation/wsdl:output> or <wsdl:binding/wsdl:operation/wsdl:fault>} - Policies associated with a message policy subject apply to that message (i.e. input, output or fault message).

WS-Security Policy [2], WS-RM [3] assertions are build on top of WS-Policy for specifying security or reliable messaging requirements/constraints for aservice. For example, specifying security requirements for outgoing message, I can write as,

<wsp:Policy wsu:Id="Output_Policy">
<wsp:ExactlyOne>
<wsp:All>
<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"> <sp:Body/>
</sp:SignedParts>
<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsu:Timestamp/>
</sp:EncryptedParts>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>


and I can refer this policy as,

<wsdl:binding name="WebTransactionServiceSoapBinding"
type="tns:CreditCard">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<!--wsp:PolicyReference URI="#Endpoint_Policy"/-->
<wsdl:operation name="purchase">
<soap:operation soapAction="" style="document"/>
<wsdl:input name="purchase">
<!--wsp:PolicyReference URI="#Input_Policy"/-->
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output name="purchaseResponse">
<wsp:PolicyReference URI="#Output_Policy"/>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>

or specifying RM assertions as Embedded instead of referred can be,

<wsdl:service name="CartSLSBBeanService">
<wsdl:port binding="ns1:CartSLSBBeanServiceSoapBinding"
name="CartSLSBBeanPort">
<wswa:UsingAddressing
xmlns:wswa="http://www.w3.org/2005/02/addressing/wsdl"/>
<soap:address location=" http://localhost:8181/cart/cart"/>
<wsp:Policy xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
xmlns:wsu="
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="RM">
<wsam:Addressing
xmlns:wsam=http://www.w3.org/2007/02/addressing/metadata>
<wsrmp:RMAssertion
xmlns:wsrmp=http://schemas.xmlsoap.org/ws/2005/02/rm/policy>
<wsrmp:BaseRetransmissionInterval Milliseconds="10000"/>
</wsrmp:RMAssertion>
</wsp:Policy>
</wsdl:port>
</wsdl:service>

You can read more about WS-SecurityPolicy[2] and WS RM[3] so as to understand what these assertions actually specify.I hope this helps
[1]. http://www.w3.org/TR/ws-policy/
[2]. http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.2/ws-securitypolicy.html
[3].http://docs.oasis-open.org/ws-rx/wsrmp/200608/wsrmp-1.1-spec-cd-04.html
[4]. http://www.w3.org/TR/ws-policy-attach/

Understanding WS-Trust and configuration in CXF

Apache CXF is a high-performance, extensible, Intuitive & Easy to Use open source services framework. CXF helps you build and develop services using frontend programming APIs, like JAX-WS. CXF supports a variety of web service standards including SOAP, the Basic Profile, WSDL, WS-Addressing, WS-Policy, WS-ReliableMessaging, and WS-Security.

Apache CXF 2.2 is the third major release of CXF project. I found this release very interesting as it supports WS-SecurityPolicy and Partially supports WS-Trust. WS-Trust specifically deals with the issuing, renewing, and validating of security tokens, as well as with ways to establish, assess the presence of, and broker trust relationships between participants in a secure message exchange.

WS-SecurityPolicy is a very helpful and easier way of specifying your security requirements in an interoperable way. You can access a secured web service hosted on MS server by just pointing to the wsdl containing embedded WS-SecurityPolicy or a WS-Policy reference to a separate WS-SecurityPolicy file.

In CXF-2.2, WS-Trust is supported on client side, that means that now you can access a web services hosted by any WS vendor who requires you to produce tokens for authentication and authorization. For example, if I host a web service in Metro and configures a Metro STS (Secure Token Service - which provides tokens to clients). My CXF client will talk to Metro STS to acquire a token, once acquired CXF client can then produce this token to the Metro Service as an authentication and authorization token. An STS itself is a web service - a web service that issues security tokens.

Daniel Kulp has done a great job in making WS-Trust support up and working. In future release of CXF, we will come up with full support for WS-Trust. Any one who is interested can join the development I have filed a jira task for it.

How WS-Trust works: Basically on client side, ws-policy engine while parsing and understanding service wsdl, from <issuedtoken><issuer>... <issuer>assertion it learns that the service requires a security token to be produced. gives the WS-Addressing address of the STS service and WS-MEX (Metadata Exchange) address for getting the WSDL location of STS. STS may confirm the authenticity of the client who is requesting for the token. Based on the satisfactory confirmation of the authentication of the client, <issuedtoken> may have an assertion <requestsecuritytokentemplate> in which the service may specify what kind of RST request a client should make to STS, a service may specify it's particular requirements for the Token to be produced to it, the requirements can be KeySize, KeyType, TokenType, etc.

STS issues a RSTR (RequestSecurityTokenResponse) which contains requestedToken and proofkey. A proof key indicates proof of possession of the token associated with the requested security token. There are two types of proof keys: symmetric or asymmetric. A service can specify the proof key in the <keytype> element of <requestsecuritytokentemplate>.

In case of Symmetric key, STS creates and distributes the Symmetric key to both service and client. STS gives the key to the client in the <requestedprooftoken> element. STS gives the exact copy of the key to the service in the <keyinfo> element of the <subjectconfirmation> element in the issued SAML assertion in the RSTR response to the client. Client then forward the issued SAML assertion to the service.

In case of Public Key, client doesn't want to trust STS for issuing the secret key as proof of possession. In the RST (RequestSecurityToken) message client supplies RSA key or X.509 public key to STS. STS just embeds the RSA key or X.509 public key certificate in the <keyinfo> element of the <subjectconfirmation> element in the issued SAML assertion in the RSTR response to the client. Client then forward the issued SAML assertion to the service.

In case of No Proof Key, the issued token in <requestedsecuritytoken> itself works as proof of possession.

After getting RSTR, client composes the web service request as requested by WSDL requirements of the service. It embeds the SAML assertion into the request message to the service. Service and client uses the proof key for authentication and authorization of messages afterwards.

Configuring CXF for WS-Trust

Since currently only Client side support is provided in CXF 2.2 version (as I have discussed at the start of this blog entry), all we require to do is to configure a STSClient java class, org.apache.cxf.ws.security.trust.STSClient with the properties to wsdl location, service name, endpoint name. STSClient will look into wsdl, request for an issue, validate, renewal of the required token from STS and will put into the context of WS call so that finally the ws-request can be send with the required token, proof token and SAML assertion. Usually, you configure STS client in either of below two ways,

You can configure STSClient using code-first by creating a new instance of STSClient and calling setter methods of STSClient and finally setting a property "ws-security.sts.client" oof RequestContext() method on port instance as,

((BindingProvider)port).getRequestContext().put("ws-security.sts.client", stsinstance);

or, else you can configure spring bean as,

<jaxws:client name="{http://cxf.apache.org/}MyService">

<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="joe"/>

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

</entry>

</jaxws:properties>

</jaxws:client>