Red Hat Training

A Red Hat training course is available for Red Hat Fuse

5.2. Policy Expressions

Overview

In general, a wsp:Policy element is composed of multiple different policy settings (where individual policy settings are specified as policy assertions). Hence, the policy defined by a wsp:Policy element is really a composite object. The content of the wsp:Policy element is called a policy expression, where the policy expression consists of various logical combinations of the basic policy assertions. By tailoring the syntax of the policy expression, you can determine what combinations of policy assertions must be satisfied at runtime in order to satisfy the policy overall.
This section describes the syntax and semantics of policy expressions in detail.

Policy assertions

Policy assertions are the basic building blocks that can be combined in various ways to produce a policy. A policy assertion has two key characteristics: it adds a basic unit of functionality to the policy subject and it represents a boolean assertion to be evaluated at runtime. For example, consider the following policy assertion that requires a WS-Security username token to be propagated with request messages: 
<sp:SupportingTokens xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
  <wsp:Policy>
    <sp:UsernameToken/>
  </wsp:Policy>
</sp:SupportingTokens>
When associated with an endpoint policy subject, this policy assertion has the following effects:
  • The Web service endpoint marshales/unmarshals the UsernameToken credentials.
  • At runtime, the policy assertion returns true, if UsernameToken credentials are provided (on the client side) or received in the incoming message (on the server side); otherwise the policy assertion returns false.
Note that if a policy assertion returns false, this does not necessarily result in an error. The net effect of a particular policy assertion depends on how it is inserted into a policy and on how it is combined with other policy assertions.

Policy alternatives

A policy is built up using policy assertions, which can additionally be qualified using the wsp:Optional attribute, and various nested combinations of the wsp:All and wsp:ExactlyOne elements. The net effect of composing these elements is to produce a range of acceptable policy alternatives. As long as one of these acceptable policy alternatives is satisfied, the overall policy is also satisified (evaluates to true).

wsp:All element

When a list of policy assertions is wrapped by the wsp:All element, all of the policy assertions in the list must evaluate to true. For example, consider the following combination of authentication and authorization policy assertions: 
<wsp:Policy wsu:Id="AuthenticateAndAuthorizeWSSUsernameTokenPolicy">
  <wsp:All>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:UsernameToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:SamlToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
  </wsp:All>
</wsp:Policy>
The preceding policy will be satisfied for a particular incoming request, if the following conditions both hold:
  • WS-Security UsernameToken credentials must be present; and
  • A SAML token must be present.
Note
The wsp:Policy element is semantically equivalent to wsp:All. Hence, if you removed the wsp:All element from the preceding example, you would obtain a semantically equivalent example

wsp:ExactlyOne element

When a list of policy assertions is wrapped by the wsp:ExactlyOne element, at least one of the policy assertions in the list must evaluate to true. The runtime goes through the list, evaluating policy assertions until it finds a policy assertion that returns true. At that point, the wsp:ExactlyOne expression is satisfied (returns true) and any remaining policy assertions from the list will not be evaluated. For example, consider the following combination of authentication policy assertions: 
<wsp:Policy wsu:Id="AuthenticateUsernamePasswordPolicy">
  <wsp:ExactlyOne>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:UsernameToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
    <sp:SupportingTokens>
      <wsp:Policy>
        <sp:SamlToken/>
      </wsp:Policy>
    </sp:SupportingTokens>
  </wsp:ExactlyOne>
</wsp:Policy>
The preceding policy will be satisfied for a particular incoming request, if either of the following conditions hold:
  • WS-Security UsernameToken credentials are present; or
  • A SAML token is present.
Note, in particular, that if both credential types are present, the policy would be satisfied after evaluating one of the assertions, but no guarantees can be given as to which of the policy assertions actually gets evaluated.

The empty policy

A special case is the empty policy, an example of which is shown in Example 5.1, “The Empty Policy”.

Example 5.1. The Empty Policy

<wsp:Policy ... > 
   <wsp:ExactlyOne>
      <wsp:All/>
   </wsp:ExactlyOne>
</wsp:Policy>
Where the empty policy alternative, <wsp:All/>, represents an alternative for which no policy assertions need be satisfied. In other words, it always returns true. When <wsp:All/> is available as an alternative, the overall policy can be satisified even when no policy assertions are true.

The null policy

A special case is the null policy, an example of which is shown in Example 5.2, “The Null Policy”.

Example 5.2. The Null Policy

<wsp:Policy ... >
   <wsp:ExactlyOne/>
</wsp:Policy>
Where the null policy alternative, <wsp:ExactlyOne/>, represents an alternative that is never satisfied. In other words, it always returns false.

Normal form

In practice, by nesting the <wsp:All> and <wsp:ExactlyOne> elements, you can produce fairly complex policy expressions, whose policy alternatives might be difficult to work out. To facilitate the comparison of policy expressions, the WS-Policy specification defines a canonical or normal form for policy expressions, such that you can read off the list of policy alternatives unambiguously. Every valid policy expression can be reduced to the normal form.
In general, a normal form policy expression conforms to the syntax shown in Example 5.3, “Normal Form Syntax”.

Example 5.3. Normal Form Syntax

<wsp:Policy ... >
   <wsp:ExactlyOne>
        <wsp:All> <Assertion .../> ... <Assertion .../> </wsp:All>
        <wsp:All> <Assertion .../> ... <Assertion .../> </wsp:All>
        ...
   </wsp:ExactlyOne>
</wsp:Policy>
Where each line of the form, <wsp:All>...</wsp:All>, represents a valid policy alternative. If one of these policy alternatives is satisfied, the policy is satisfied overall.