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 guide provides information on how to develop, deploy, and test custom assertions.
This chapter includes the following sections:
For definitions of unfamiliar terms found in this and other books, see the Glossary.
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,
"Predefined Assertion Templates" in Securing Web Services and Managing Policies with Oracle Web Services Manager
"Managing Policy Assertion Templates" in Securing Web Services and Managing Policies with Oracle Web Services Manager
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.
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 Securing Web Services and Managing Policies with Oracle Web Services Manager.
This guide describes how to create policies using custom assertions that you develop.
If you need specific functionality that is not available with the predefined policies or assertions provided by OWSM, then you can develop custom assertions to fulfill that requirement.
The following topics provide information to help you understand custom assertions:
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).
The following examples illustrate different policy combinations:
The following example shows a policy (defined by the wsp:Policy element) with one assertion (orasp:AssertionOne). For more information about the elements and Oracle extensions of their attributes, see Appendix A, "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>
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>
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.
Table 1-1 describes the supported custom assertion categories based on the web service specification they conform to and their significance. You specify the category using 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 |
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.
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.
The OWSM run time manages the life cycle of a custom assertion, which consists of four phases; initialization, execution, post-execution, and termination. 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:
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 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 OWSM run time when application is shutting down. Its invoked for a cleaner ending of the assertion lifecycle.
The policy object model defines two types of 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.
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.
Following is a pseudo-schema for Simple Assertions with only binding elements:
<Assertion> [ wsp:Optional="xsd:boolean" ]? [ orawsp:Silent="xsd:boolean" ]? [ orawsp:Enforced="xsd:boolean" ]? [ orawsp:description="xsd:string" ]? [ orawsp:category="xsd:string" ]?...> <orawsp:bindings>? </Assertion>
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.
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.
Following is a psuedo-schema for Multi-element Simple Assertions that may contain elements other than the bindings:
<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>