Fusion Middleware Documentation
Advanced Search


Developing Extensible Applications for Oracle Web Services Manager
Close Window

Table of Contents

Show All | Collapse

1 Understanding Policies and Assertions

Oracle Web Services Manager (OWSM) 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 OWSM. 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:

1.1 Predefined Policies and Assertions

OWSM provides read-only predefined policies with Oracle Fusion Middleware. For information about the OWSM policies and their use, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

Each policy consists of one or more assertions, defined at the domain-level, that define the security requirements. A set of predefined assertion templates are provided out-of-the-box. The predefined assertions are described in "Predefined Assertion Templates" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

For more information about using the predefined assertions, see "Managing Policy Assertion Templates" in Securing Web Services and Managing Policies with Oracle Web Services Manager. In addition to using existing assertions, you can develop your own custom assertions using the APIs for OWSM.

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

  • Create policies from custom assertions

The first three methods of creating policies are described in "Managing Web Service Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager. This guide describes how to create policies using custom assertions that you develop.

1.3 About Custom Assertions

This section describes the following topics:

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 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 Supported Custom Assertion Categories

Table 1-1 provides a list of the supported custom 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 Supported Custom 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

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 <orawsp:bindings> element used to define the bindings in the assertion, and all its subelements, see orawsp:bindings in Securing Web Services and Managing Policies with Oracle Web Services Manager.

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 OWSM run time manages the life cycle of custom assertion. For each phase, the OWSM run time invokes a method of custom assertion executor. The following methods must be implemented inside the custom assertion executor of the custom policy:

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

  2. 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".

  3. IResult postExecute(IContext messageContext): Executes any task required after policy execution.

  4. void destroy(): The destroy method is invoked by OWSM 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:

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>