1 Understanding Policies and Assertions in Oracle Web Services Manager

Oracle Web Services Manager (OWSM) delivers set of predefined policies and assertion templates that are automatically available when you install Oracle Fusion Middleware. OWSM also enables you to develop custom assertions when specific functionality is not provided with the predefined policies. For example, if an application requires the use of an authentication type that is not available in OWSM, then you can create a custom authentication assertion.

This chapter includes the following sections:

For definitions of unfamiliar terms found in this and other books, see the Glossary.

1.1 About 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. OWSM also provides a set of predefined assertion templates. For information about these predefined assertions and their use, see,

In addition to using the existing assertions, you can develop your own custom assertions using the APIs for OWSM. For more information, see the Java API Reference for Oracle Web Services Manager.

1.2 About Web Service Policies Creation

Policies describe the capabilities and requirements of a Web service. You can create web service policies using existing assertion templates, custom assertions, and from existing policies. You can also import a policy from zip archive.

You can use any of the following methods to create a web service policy:

  • 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 are described in "Managing Web Service Policies" in Administering Web Services.

This guide describes how to create policies using custom assertions that you develop.

1.3 Understanding Custom Assertions

You can develop custom assertions to fulfill the requirement of specific functionality that is not available with the predefined policies or assertions provided by OWSM.

The following topics provide information to help you understand custom assertions:

1.3.1 About 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).

1.3.2 About Policy Combinations

You can combine policy with either assertions or operators.

The following topics explain this in detail:

1.3.2.1 Combining a Policy with an Assertion

You can combine a policy that is defined by the wsp:Policy element with one assertion (orasp:AssertionOne). This is explained with an example below.

The following is the example. For more information about the elements and Oracle extensions of their attributes, see Custom Assertions Schema Reference.

<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>
1.3.2.2 Combining a Policy with Two Assertions and wsp:All Operator

You can combine a policy with two assertions. The following example 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.

<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>
1.3.2.3 Combining a Policy with Many Assertions and wsp:ExactlyOne Operator

You can combine a policy with many assertions and wsp:ExactlyOne operator. This is explained in the example given below.

In the following example, 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.

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

The supported custom assertion categories based on the web service specification they conform to and their significance are tabulated below. You specify the category using orawsp:category, an attribute of the orasp:Assertion element.

Table 1-1 describes this. Managing 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

You can use Enterprise Manager Fusion Middlware Control to view, edit, and manage policies of different categories. Note that policies of a category can be attached to specific endpoints. See About the Rules for Binding Custom Assertions for rules for binding custom assertions.

1.3.4 About the Rules for Binding Custom Assertions

The <orawsp:bindings> element is used to define the bindings in an assertion.

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.5 About the Life Cycle of a Custom Assertion

The OWSM runtime manages the life cycle of a custom assertion, which consists of four phases; initialization, execution, post-execution, and termination. For each phase, the OWSM runtime 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 Accessing OWSM Custom Security Assertion.

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

  • void destroy(): The destroy method is invoked by OWSM runtime when application is shutting down. Its invoked for a cleaner ending of the assertion lifecycle.

1.3.6 Understanding the Types of Custom Assertions

The policy object model defines two types of assertions: Simple Assertions and Multi-Element Simple Assertions.

The following topics explain this further:

1.3.6.1 Understanding 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.

This section contains the following topics:

1.3.6.1.1 Rules for Using Simple Assertions

This topic lists the rules for using Simple Assertions.

When using Simple Assertions, be aware of the following usage rules:

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

1.3.6.1.2 Defining a Pseudo-schema for Simple Assertions

This topic shows a pseudo-schema for Simple Assertions with only binding elements.

The following is the pseudo-schema:

<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.6.2 Understanding 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.

This section contains the following topics:

1.3.6.2.1 Rules for Using Multi-element Simple Assertions

This topic lists the usage rules for using Multi-element Simple Assertions.

When using Multi-element Simple Assertions, be aware of the following usage rules:

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

1.3.6.2.2 Defining a Pseudo-schema for Multi-element Simple Assertions

This topic shows a psuedo-schema for Multi-element Simple Assertions that may contain elements other than the bindings.

The following is the psuedo-schema:

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