1 Understanding Policies and Assertions

Oracle Web Services Manager (Oracle WSM) delivers a set of predefined policies and assertion templates that are automatically available when you install Oracle Fusion Middleware. You may need to develop custom assertions when specific functionality is not provided with the standard policies that come with the product. For example, an application may require the use of a type of authentication that is not available in Oracle WSM. In this situation, a custom authentication assertion needs to be created. This manual provides information on how to develop, deploy, and test custom assertions.

This chapter contains the following topics:

Predefined Policies and Assertions
Creating Policies
About Custom Assertions

1.1 Predefined Policies and Assertions

Oracle Fusion Middleware 11g Release 1 (11.1.1) is packaged with predefined policies. For information on the Oracle Fusion Middleware Web Services policies, see Appendix B, "Predefined Policies" in Security and Administrator's Guide for Web Services.

Each policy consists of one or more assertions, defined at the domain-level, that define the security requirements. A set of predefined assertions are provided out-of-the-box. The predefined assertions are described in Appendix C, "Predefined Assertion Templates" in Security and Administrator's Guide for Web Services.

For more information on using the existing predefined assertions, see "Working with Assertions" in Security and Administrator's Guide for Web Services. In addition to using existing assertions, you can develop your own custom assertions using the APIs for Oracle WSM.

1.2 Creating Policies

You can create a Web service policy in one of the following ways:

Create a new policy using existing assertion templates
Create a new policy from an existing policy
Import a policy from a file
Create policies from custom assertions

The first three methods of creating policies are described in "Managing Web Service Policies" in the Security and Administrator's Guide for Web Services. This guide describes how to create policies using custom assertions that you develop.

1.3 About Custom Assertions

This section describes the following topics:

Section 1.3.1, "Policies, Assertions, Expressions, and Operators"
Section 1.3.2, "Understanding Assertion Categories"
Section 1.3.3, "Rules for Binding of Custom Assertions"
Section 1.3.4, "Life Cycle of a Custom Assertion"
Section 1.3.5, "Types of Custom Assertions"

1.3.1 Policies, Assertions, Expressions, and Operators

Web services use policies to describe their capabilities and requirements. Policies define how a message must be secured and delivered reliably, whether a message must flow a transaction, and so on. A policy is a set of assertions (rules, requirements, obligations) that express specific policy requirements or properties of a Web service.

A policy assertion is a basic unit representing an individual requirement, capability or property in a policy. Assertions use domain-specific semantics to enable interoperability.

A policy expression is an XML representation of a policy. The policy expression consists of various logical combinations of the basic policy assertions that form the content of the wsp:Policy element. The logical combinations are created using policy operators (wsp:Policy, wsp:All, and wsp:ExactlyOne elements).

Example 1-1 shows a policy (defined by the wsp:Policy element) with one assertion (orasp:AssertionOne). For more information on the elements and Oracle extensions of their attributes, see the Appendix A, "Schema Reference for Custom Assertions".

Example 1-1 Policy with One Assertion

<wsp:Policy
    xmlns="http://schemas.xmlsoap.org/ws/2004/09/policy"  
    xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy" >
        
           <orasp:AssertionOne orawsp:Silent="true" orawsp:Enforced="true"
           orawsp:name="Validator"
           orawsp:category="security/authentication">
           ...
          </orasp:AssertionOne>
</wsp:Policy>

Example 1-2 shows a list of policy assertions wrapped by the policy operator wsp:All element (all of the policy assertions in the list must evaluate to true). The wsp:Policy element is semantically equivalent to wsp:All.

Example 1-2 Policy with Two Assertions and wsp:All Operator

<wsp:Policy
    xmlns="http://schemas.xmlsoap.org/ws/2004/09/policy"  
    xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy" >
        
          <wsp:All>
           <orasp:AssertionOne orawsp:Silent="true" orawsp:Enforced="true"
           orawsp:name="SAMLValidator"
           orawsp:category="security/authentication">
           ...
          </orasp:AssertionOne>
          <orasp:AssertionTwo orawsp:Silent="true" orawsp:Enforced="true"
           orawsp:name="UserNameValidator"
           orawsp:category="security/authentication">
           ...
           </orasp:AssertionTwo>
         </wsp:All>
         
</wsp:Policy>

In Example 1-3, each line within the operators <wsp:All>...</wsp:All> represents a valid policy alternative. The policy is satisfied if one set of the policy alternatives is true.

Example 1-3 Policy with Many Assertions and wsp:ExactlyOne Operator

<wsp:Policy
    xmlns="http://schemas.xmlsoap.org/ws/2004/09/policy"  
    xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy" >
        
       <wsp:ExactlyOne>
          <wsp:All>
           <orasp:SAML orawsp:Silent="true" orawsp:Enforced="true"
           orawsp:name="SAML"
           orawsp:category="security/authentication">
           ...
          </orasp:SAML>
          </wsp:All>
          <wsp:All>
          <orasp:Username orawsp:Silent="true" orawsp:Enforced="true"
           orawsp:name="Username"
           orawsp:category="security/authentication">
           ...
           </orasp:Username>
         </wsp:All>
         
    </wsp:ExactlyOne>
</wsp:Policy>

Using the operators and combinations of policy assertions, you can create complex policy alternatives.

1.3.2 Understanding Assertion Categories

Table 1-1 provides a list of the assertion categories based on the Web service specification they conform to and their significance. You specify the category using the orawsp:category, an attribute of the orasp:Assertion element. Chapter 3, "Stepping Through Sample Custom Assertions" provides samples for various categories of security custom assertions.

Table 1-1 Assertion Categories

Category	Description	Valid Values for orawsp:category
Security	Policies that implement the WS-Security 1.0 and 1.1 standards, which allow the communication of various security token formats, such as SAML, Kerberos, and X.509. They enforce authentication and authorization of users, identity propagation, and message protection.	security/authentication, security/msg-protection, security/authorization, security/logging
MTOM Attachments	Policies with attachments that are in MTOM format. Message Transmission Optimization Mechanism (MTOM) format enables efficient transfer of binary data to be sent to and from Web services.	mtom
Reliable Messaging	Policies that support the WS-ReliableMessaging protocol. This guarantees the delivery of SOAP messages. WS-ReliableMessaging makes use of a reliable messaging source and a reliable messaging destination and supports a number of Delivery Assurances. For more information, see WS-ReliableMessaging specification at: `http://docs.oasis-open.org/ws-rx/wsrm/200702`	wsrm
WS-Addressing	Policies in which simple object access protocol (SOAP) messages include WS-Addressing headers and that allow Web services to communicate addressing information.	addressing
Management	Policies used to store request, response, and fault messages to a message log.	management

Using Enterprise Manager Fusion Middlware Control, you can view, edit, and manage policies of different categories. Note that policies of a category can be attached to specific endpoints. See the next section for rules for binding custom assertions.

1.3.3 Rules for Binding of Custom Assertions

For a description of the <oraswsp:bindings> element used to define the bindings in the assertion, and all its subelements, see orawsp:bindings in Security and Administrator's Guide for Web Services.

1.3.4 Life Cycle of a Custom Assertion

The life cycle of a custom assertion involves four phases of initialization, execution, post-execution and termination. The Oracle WSM run time manages the life cycle of custom assertion. For each phase, the Oracle WSM run time invokes a method of custom assertion executor. The following methods must be implemented inside the custom assertion executor of the custom policy:

void init(IAssertion ia, IExecutionContext context, IContext msgContext): This method is called after the AssertionExecutor is created or after one of the properties has been changed.
IResult execute(IContext mcontext): This method is invoked at stages such as request, response, and in the event of a fault. This method must always return a non-null IResult object. To find the stage of policy execution, see Section 4.3, "Accessing Request, Response, and Fault Message Objects".
IResult postExecute(IContext messageContext): Executes any task required after policy execution.
void destroy(): The destroy method is invoked by Oracle WSM run time when application is shutting down. Its invoked for a cleaner ending of the assertion lifecycle.

1.3.5 Types of Custom Assertions

The policy object model defines two types of assertions:

"Simple Assertions"
"Multi-Element Simple Assertions"

1.3.5.1 Simple Assertions

A Simple Assertion contains only one assertion (defining a single behavior) and cannot contain other assertions. A Simple Assertion maps to an org.w3c.dom.Element that does not have any nested elements except for extensions defined by Oracle. The class for the Simple Assertion extends the class oracle.wsm.policy.model.ISimpleAssertion. ISimpleOracleAssertion provides the extensions defined by Oracle for a WS-Policy Assertion.

Usage

Simple Assertions:

Cannot contain nested elements other than Oracle extension element <orawsp:bindings>
Cannot contain other assertions
Use the default Serializer and De-Serializer
Use the default Implementation class
Must extend the base class SimpleAssertion. The method getAssertionType must return the appropriate value if you introduce a new Class.
Do not need Serializer and De-Serializer if you introduce a new Class.

Pseudo-schema

The pseudo-schema for Simple Assertions with only binding elements is as follows:

<Assertion>
[ wsp:Optional="xsd:boolean" ]?
[ orawsp:Silent="xsd:boolean" ]?
[ orawsp:Enforced="xsd:boolean" ]?
[ orawsp:description="xsd:string" ]?
[ orawsp:category="xsd:string" ]?...>
<orawsp:bindings>?
</Assertion>

1.3.5.2 Multi-Element Simple Assertions

A Multi-element Simple Assertion cannot contain other assertions; however, it may contain nested XML elements. A Multi-element Simple Assertion maps to an org.w3c.dom.Element which has nested XML elements and extension elements defined by Oracle. The class for the Multi-element Simple Assertion extends the class oracle.wsm.policy.model.IMultiElementSimpleAssertion.

Usage

Multi-element Simple Assertions:

May contain nested XML elements other than Oracle extension element <orawsp:bindings>
Cannot contain other assertions and are defined in domain-specific specifications. Nested XML elements participate in policy intersections only if domain-specific intersection semantics are defined.

Pseudo-schema

Multi-element Simple Assertion may contain elements other than the bindings. The psuedo-schema is:

<Assertion>
[ wsp:Optional="xsd:boolean" ]?
[ orawsp:Silent="xsd:boolean" ]?
[ orawsp:Enforced="xsd:boolean" ]?
[ orawsp:description="xsd:string" ]?
[ orawsp:category="xsd:string" ]?...>
<other-xml-elements>+
<orawsp:bindings>?
</Assertion>