Chapter 5. The WS-Policy Framework
Abstract
This chapter provides an introduction to the basic concepts of the WS-Policy framework, defining policy subjects and policy assertions, and explaining how policy assertions can be combined to make policy expressions.
5.1. Introduction to WS-Policy
Overview
The WS-Policy specification provides a general framework for applying policies that modify the semantics of connections and communications at runtime in a Web services application. Apache CXF security uses the WS-Policy framework to configure message protection and authentication requirements.
Policies and policy references
The simplest way to specify a policy is to embed it directly where you want to apply it. For example, to associate a policy with a specific port in the WSDL contract, you can specify it as follows:
<wsdl:definitions targetNamespace="http://tempuri.org/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
...
<wsdl:service name="PingService10">
<wsdl:port name="UserNameOverTransport_IPingService" binding="BindingName">
<wsp:Policy>
<!-- Policy expression comes here! -->
</wsp:Policy>
<soap:address location="SOAPAddress"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
An alternative way to specify a policy is to insert a policy reference element,
wsp:PolicyReference, at the point where you want to apply the policy and then insert the policy element, wsp:Policy, at some other point in the XML file. For example, to associate a policy with a specific port using a policy reference, you could use a configuration like the following:
<wsdl:definitions targetNamespace="http://tempuri.org/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
...
<wsdl:service name="PingService10">
<wsdl:port name="UserNameOverTransport_IPingService" binding="BindingName">
<wsp:PolicyReference URI="#PolicyID"/>
<soap:address location="SOAPAddress"/>
</wsdl:port>
</wsdl:service>
...
<wsp:Policy wsu:Id="PolicyID">
<!-- Policy expression comes here ... -->
</wsp:Policy>
</wsdl:definitions>
Where the policy reference,
wsp:PolicyReference, locates the referenced policy using the ID, PolicyID (note the addition of the # prefix character in the URI attribute). The policy itself, wsp:Policy, must be identified by adding the attribute, wsu:Id="PolicyID".
Policy subjects
The entities with which policies are associated are called policy subjects. For example, you can associate a policy with an endpoint, in which case the endpoint is the policy subject. It is possible to associate multiple policies with any given policy subject. The WS-Policy framework supports the following kinds of policy subject:
Service policy subject
To associate a policy with a service, insert either a
<wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of the following WSDL 1.1 element:
wsdl:service—apply the policy to all of the ports (endpoints) offered by this service.
Endpoint policy subject
To associate a policy with an endpoint, insert either a
<wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of any of the following WSDL 1.1 elements:
wsdl:portType—apply the policy to all of the ports (endpoints) that use this port type.wsdl:binding—apply the policy to all of the ports that use this binding.wsdl:port—apply the policy to this endpoint only.
For example, you can associate a policy with an endpoint binding as follows (using a policy reference):
<wsdl:definitions targetNamespace="http://tempuri.org/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
...
<wsdl:binding name="EndpointBinding" type="i0:IPingService">
<wsp:PolicyReference URI="#PolicyID"/>
...
</wsdl:binding>
...
<wsp:Policy wsu:Id="PolicyID"> ... </wsp:Policy>
...
</wsdl:definitions>Operation policy subject
To associate a policy with an operation, insert either a
<wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of any of the following WSDL 1.1 elements:
wsdl:portType/wsdl:operationwsdl:binding/wsdl:operation
For example, you can associate a policy with an operation in a binding as follows (using a policy reference):
<wsdl:definitions targetNamespace="http://tempuri.org/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
...
<wsdl:binding name="EndpointBinding" type="i0:IPingService">
<wsdl:operation name="Ping">
<wsp:PolicyReference URI="#PolicyID"/>
<soap:operation soapAction="http://xmlsoap.org/Ping" style="document"/>
<wsdl:input name="PingRequest"> ... </wsdl:input>
<wsdl:output name="PingResponse"> ... </wsdl:output>
</wsdl:operation>
...
</wsdl:binding>
...
<wsp:Policy wsu:Id="PolicyID"> ... </wsp:Policy>
...
</wsdl:definitions>Message policy subject
To associate a policy with a message, insert either a
<wsp:Policy> element or a <wsp:PolicyReference> element as a sub-element of any of the following WSDL 1.1 elements:
wsdl:messagewsdl:portType/wsdl:operation/wsdl:inputwsdl:portType/wsdl:operation/wsdl:outputwsdl:portType/wsdl:operation/wsdl:faultwsdl:binding/wsdl:operation/wsdl:inputwsdl:binding/wsdl:operation/wsdl:outputwsdl:binding/wsdl:operation/wsdl:fault
For example, you can associate a policy with a message in a binding as follows (using a policy reference):
<wsdl:definitions targetNamespace="http://tempuri.org/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" ... >
...
<wsdl:binding name="EndpointBinding" type="i0:IPingService">
<wsdl:operation name="Ping">
<soap:operation soapAction="http://xmlsoap.org/Ping" style="document"/>
<wsdl:input name="PingRequest">
<wsp:PolicyReference URI="#PolicyID"/>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output name="PingResponse"> ... </wsdl:output>
</wsdl:operation>
...
</wsdl:binding>
...
<wsp:Policy wsu:Id="PolicyID"> ... </wsp:Policy>
...
</wsdl:definitions>