This chapter describes how to create custom assertions. It includes the following sections:
If the predefined assertion templates, defined in "Predefined Assertion Templates", do not fit your needs, you can create your own custom assertions.
To create a custom assertion, you need to create the following files:
Custom assertion class—Implements the Java class and its parsing and enforcement logic.
Custom policy file—Enables you to define the bindings for and configure the custom assertion.
policy-config.xml file—Registers the custom policy file.
You package the assertion class and policy-config.xml file as a JAR file and make the JAR file available in the CLASSPATH for your domain. Then, you import the custom policy file and attach it to your Web service or client, as required.
The following sections describe each step in the process.
Create the custom assertion class to execute and validate the logic of your policy assertion. The custom assertion class must extend oracle.wsm.policyengine.impl.AssertionExecutor.
When building the custom assertion class, ensure that the following JAR files are in your CLASSPATH: wsm-policy-core.jar and wsm-agent-core.jar.
The following example shows a custom assertion executor that can be used to validate the IP address of the request. If the IP address of the request is invalid, a FAULT_FAILED_CHECK exception is thrown.
For more information about the APIs that are available to you for developing your own custom assertion class, see the Java API Reference for Oracle Web Services Manager.
Example 13-1 Example Custom Assertion Class
package sampleassertion;
import oracle.wsm.common.sdk.IContext;
import oracle.wsm.common.sdk.IMessageContext;
import oracle.wsm.common.sdk.IResult;
import oracle.wsm.common.sdk.Result;
import oracle.wsm.common.sdk.WSMException;
import oracle.wsm.policy.model.IAssertionBindings;
import oracle.wsm.policy.model.IConfig;
import oracle.wsm.policy.model.IPropertySet;
import oracle.wsm.policy.model.ISimpleOracleAssertion;
import oracle.wsm.policy.model.impl.SimpleAssertion;
import oracle.wsm.policyengine.impl.AssertionExecutor;
public class IpAssertionExecutor extends AssertionExecutor {
public IpAssertionExecutor() {
}
public void destroy() {
}
public void init(oracle.wsm.policy.model.IAssertion assertion,
oracle.wsm.policyengine.IExecutionContext econtext,
oracle.wsm.common.sdk.IContext context) {
this.assertion = assertion;
this.econtext = econtext;
}
public oracle.wsm.policyengine.IExecutionContext getExecutionContext() {
return this.econtext;
}
public boolean isAssertionEnabled() {
return ((ISimpleOracleAssertion)this.assertion).isEnforced();
}
public String getAssertionName() {
return this.assertion.getQName().toString();
}
/**
* @param context
* @return
*/
public IResult execute(IContext context) throws WSMException {
try {
IAssertionBindings bindings =
((SimpleAssertion)(this.assertion)).getBindings();
IConfig config = bindings.getConfigs().get(0);
IPropertySet propertyset = config.getPropertySets().get(0);
String valid_ips =
propertyset.getPropertyByName("valid_ips").getValue();
String ipAddr = ((IMessageContext)context).getRemoteAddr();
IResult result = new Result();
if (valid_ips != null && valid_ips.trim().length() > 0) {
String[] valid_ips_array = valid_ips.split(",");
boolean isPresent = false;
for (String valid_ip : valid_ips_array) {
if (ipAddr.equals(valid_ip.trim())) {
isPresent = true;
}
}
if (isPresent) {
result.setStatus(IResult.SUCCEEDED);
} else {
result.setStatus(IResult.FAILED);
result.setFault(new WSMException(WSMException.FAULT_FAILED_CHECK));
}
} else {
result.setStatus(IResult.SUCCEEDED);
}
return result;
} catch (Exception e) {
throw new WSMException(WSMException.FAULT_FAILED_CHECK, e);
}
}
public oracle.wsm.common.sdk.IResult postExecute(oracle.wsm.common.sdk.IContext p1) {
IResult result = new Result();
result.setStatus(IResult.SUCCEEDED);
return result;
}
}
Create the custom policy file to define the bindings for and configure the custom assertion. "Schema Reference for Custom Assertions" describes the schema that you can use to construct your custom policy file and custom assertion.
The following example defines the oracle/ip_assertion_policy custom policy file. The assertion defines a comma-separated list of IP addresses that are valid for a request.
Example 13-2 Example Custom Policy File
<?xml version = '1.0' encoding = 'UTF-8'?>
<wsp:Policy xmlns="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy"
orawsp:status="enabled" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" orawsp:category="security" orawsp:attachTo="binding.server" wsu:Id="ip_assertion_policy"
xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
wsp:Name="oracle/ip_assertion_policy">
<orasp:ipAssertion orawsp:Silent="true" orawsp:Enforced="true" orawsp:name="WSSecurity IpAssertion Validator" orawsp:category="security/authentication">
<orawsp:bindings>
<orawsp:Config orawsp:name="ipassertion" orawsp:configType="declarative">
<orawsp:PropertySet orawsp:name="valid_ips">
<orawsp:Property orawsp:name="valid_ips" orawsp:type="string" orawsp:contentType="constant">
<orawsp:Value>127.0.0.1,192.168.1.1</orawsp:Value>
</orawsp:Property>
</orawsp:PropertySet>
</orawsp:Config>
</orawsp:bindings>
</orasp:ipAssertion>
</wsp:Policy>
Create a policy-config.xml file that defines an entry for the new assertion and associates it with its executor class.
The following defines the format for the policy-config.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<policy-config>
<policy-model-config>
<entry>
<key namespace="namespace" elementName="elementname"/>
<executor-classname>assertionclass</executor-classname>
</entry>
</policy-model-config>
</policy-config>
The following table lists the attributes for the key element.
Table 13-1 Attributes for Key Element
| Attribute | Description |
|---|---|
|
namespace |
Namespace of the policy. This value must match the namespace defined in the custom policy file (in Step 2). In Example 13-2, the namespace is defined as part of the <wsp:Policy> tag as follows:
xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy"
|
|
elementName |
Name of the element. This value must match the assertion name defined in the custom policy file (in Step 2). In Example 13-2, the element name ipAssertion is defined in the following tag:
<orasp:ipAssertion orawsp:Silent="true" orawsp:Enforced="true" orawsp:name="WSSecurity
IpAssertion Validator" orawsp:category="security/authentication">
|
The following provides an example of a the policy-config.xml file with an entry for the ipAssertion policy.
Example 13-3 Example policy-config.xml File
<?xml version="1.0" encoding="UTF-8"?>
<policy-config>
<policy-model-config>
<entry>
<key namespace="http://schemas.oracle.com/ws/2006/01/securitypolicy" elementName="ipAssertion"/>
<executor-classname>sampleassertion.IpAssertionExecutor</executor-classname>
</entry>
</policy-model-config>
</policy-config>
Create the custom assertion JAR file that includes the IPAssertionExecutor class and the policy-config.xml file. You can use Oracle JDeveloper, other IDE, or the jar tool to generate the JAR file.
You need to add the following files to your CLASSPATH:
Custom assertion JAR file so that the custom assertion execution class is available in the server environment.
wsm-policy-core.jar and wsm-agent-core.jar required for building the custom assertion class.
Add the custom assertion JAR to your CLASSPATH by performing the following steps:
Stop the WebLogic Server.
For more information on stopping the WebLogic Server, see Managing Server Startup and Shutdown for Oracle WebLogic Server.
Copy the custom assertion JAR file created in Step 4 to the following directory: $DOMAIN_HOME/lib.
Restart the WebLogic Server.
For more information on restarting the WebLogic Server, see Managing Server Startup and Shutdown for Oracle WebLogic Server.
Before you can attach the custom policy to a Web service, you must import it using the procedure described in "Importing Web Service Policies".
Attach the custom policy to a Web service using the steps described in "Attaching Policies to Web Services".