This chapter describes how to develop custom assertions. It includes the following sections:
The policy name is specified by the name attribute of the policy content. The policy name must not already exist in the Policy Store. Once you import the policy to the Policy Store, you cannot edit the name of a policy. To change the policy name, you will need to copy the policy and assign it a different name.
Oracle recommends that you follow the policy naming conventions described in "Recommended Naming Conventions for Policies" in Security and Administrator's Guide for Web Services. The same conventions are used to name assertions.
To develop a custom assertion, you need to create the following files:
Custom assertion executor—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 can specify the custom assertion executor in one of the following files:
Custom policy file
policy-config.xml file
You package the custom assertion executor 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 executor to execute and validate the logic of your policy assertion. The custom assertion executor must extend oracle.wsm.policyengine.impl.AssertionExecutor.
When building the custom assertion executor, ensure that the following JAR files are in your CLASSPATH: wsm-policy-core.jar, wsm-agent-core.jar, and oracle.logging-utils_11.1.1.jar (located at oracle_common/modules/oracle.wsm.common_11.1.1, oracle_common/modules/oracle.wsm.agent.common_11.1.1, and oracle_common/module respectively). Add the files to the classpath.
Example 2-1 is an example of a custom assertion executor that can be used to validate the IP address of the request to the Web service. 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 executor, see the Java API Reference for Oracle Web Services Manager.
Example 2-1 Example Custom Assertion Executor
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 2-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>
Specify the custom assertion executor in any one of the following files:
Custom policy file
policy-config.xml file
Specifying the Custom Assertion Executor in the Custom Policy File
Update the custom policy to specify the custom executor information in the orawsp:Implementation element as shown in Example 2-3.
Example 2-3 Specifying the Custom Assertion Executor in the 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 IpAsertion validator" orawsp:category="security/authentication">
<orawsp:bindings>
<orawsp:Implementation>sampleassertion.IpAssertionExecutor</orawsp:Implementation>
<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>140.87.6.143,10.178.93.107</orawsp:Value>
</orawsp:Property>
</orawsp:PropertySet>
</orawsp:Config>
</orawsp:bindings>
</orasp:ipAssertion>
</wsp:Policy>
Specifying the Custom Assertion Executor in the policy-config.xml file
Create a policy-config.xml file that defines an entry for the new assertion and associates it with its custom assertion executor.
The format for the policy-config.xml file is shown in Example 2-4.
Example 2-4 policy-config.xml File Format
<?xml version="1.0" encoding="UTF-8"?>
<policy-config>
<policy-model-config>
<entry>
<key namespace="namespace" element-name="elementname"/>
<executor-classname>assertionclass</executor-classname>
</entry>
</policy-model-config>
</policy-config>
Table 2-1 lists the attributes for the key element.
Table 2-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 1). In Example 2-2, the namespace is defined as part of the <wsp:Policy> tag as follows:
xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy"
|
|
element-name |
Name of the element. This value must match the assertion name defined in the custom policy file (in Step 1). In Example 2-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">
|
Example 2-5 provides an example of a policy-config.xml file with an entry for the ipAssertion policy.
Example 2-5 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"
element-name="ipAssertion"/>
<executor-classname>sampleassertion.IpAssertionExecutor</executor-classname>
</entry>
</policy-model-config>
</policy-config>
Note:
The policy-config.xml file must be in the classpath of server. This file is also added to the custom executor jar file as mentioned in Step 4: Create the JAR File.Create the custom assertion JAR file that includes the custom assertion executor and the policy-config.xml file. You can use Oracle JDeveloper, other IDE, or the jar tool to generate the JAR file.
Add the custom policy to the policy store using Fusion Middleware Control or WLST, as described in the following sections.
Using Fusion Middleware Control
Before you can attach the custom policy to a Web service, you must import it using the procedure described in "Importing Web Service Policies" in Security and Administrator's Guide for Web Services.
Use the WebLogic Scripting Tool (WLST) commands to import the custom policy. For information, see "Migrating Policies" in Security and Administrator's Guide for Web Services.
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.
Create a Web service using the information described in "Roadmap for Implementing WebLogic Web Services" in Introducing WebLogic Web Services for Oracle WebLogic Server.
Attach the custom policy to the Web service, as described in the following sections.
Using Fusion Middleware Control
Attach the custom policy to a Web service using Fusion Middleware Control as described in "Attaching a Policy to a Web Service Using Fusion Middleware Control" in Security and Administrator's Guide for Web Services.
Using WebLogic Administration Console
Attach the custom policy to a Web service using WebLogic Administration Console as described in "Attach a WS-Policy file to a Web service" in the Oracle WebLogic Server Administration Console Help.
Attach the custom policy to a Web service using WLST as described in "Attaching a Policy to a Web Service Using WLST" in Security and Administrator's Guide for Web Services.
Attach the custom policy to a Web service using JDeveloper as described in "Using Custom Web Service Policies" in JDeveloper Online Help.
Create a client proxy for the Web service using clientgen.
For more information, see "Using the clientgen Ant Task to Generate Client Artifacts" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.
Use the Fusion Middleware Control Test Web Service page to test the operations and view results of the Web service without deploying the Web service. For more information, see "Testing Web Services" in Security and Administrator's Guide for Web Services.
Create a custom client policy from the Web service custom assertions you created in Developing Custom Assertions for Web Service. For more information on generating client policies, see "Generating Client Policies" in Security and Administrator's Guide for Web Services.