2 Creating Custom Assertions
Topics:
2.1 About Policy Name
The policy name is specified by the name attribute of the policy content. The policy name must not already exist in the OWSM Repository. Once you import the policy to the repository, you cannot edit the name of a policy. To change the policy name, you must 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 Understanding Oracle Web Services Manager. The same conventions are used to name assertions.
2.2 Developing Custom Assertions for Web Service
To develop a custom assertion, you import a custom policy file and attach it to your web service or client.
The following topics explain this further.
2.2.1 Creating the Custom Assertion Executor
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 -
oracle.logging-utils_11.1.1.jar(located atoracle_common/modules/oracle.wsm.common_12.1.2,oracle_common/modules/oracle.wsm.common_12.1.2, andoracle_common/modulesrespectively)
If necessary, add these files to your CLASSPATH.
The following example shows a custom assertion executor that you can use 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.
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;
}
}
You can run the following sample code, to determine client or service inside custom assertion executor.
String function = (String) getExecutionContext().getProperty("agent.function"); // WSMExecutionConstants.AGENT_FUNCTION
if (function != null)
isService = function.equals("agent.function.service") // WSMExecutionConstants.AGENT_FUNCTION_VAL_SERVICE
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.
2.2.2 Creating the Custom Policy File
Create the custom policy file to define the bindings and configure the custom assertion.
Custom Assertions Schema Reference 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.
<?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>To use this custom policy file with a RESTful web service and client endpoints, you must add the provides attribute to the orasp:ipAssertion element, as follows:
<orasp:ipAssertion orawsp:Silent="true" orawsp:Enforced="true"
orawsp:name="WSSecurity IpAssertion Validator"
orawsp:category="security/authentication"
orawsp:provides="{http://schemas.oracle.com/ws/2006/01/policy}REST_HTTP">
</orasp:ipAssertion>
Note:
To secure the SOAP web service endpoints, you must specify the intents in theprovides attribute and add it to the orasp:Assertion element in the custom policy file, as described in orasp:Assertion.
2.2.3 Specifying the Custom Assertion Executor
Specify the custom assertion executor in the Custom policy file or in the policy-config.xml file.
The following topics explain this further:
2.2.3.1 Specifying the Custom Assertion Executor in the Custom Policy File
You can update the custom policy to specify the custom executor information in the orawsp:Implementation element. This is shown in the example below.
The following is the example:
<?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>2.2.3.2 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. You can also specify the custom assertion executor class in the configuration file.
This section includes the following topics:
2.2.3.2.1 About the Policy Configuration File
This topic explains the format of the policy-config.xml file and the attributes for the Key element.
The format for the policy-config.xml file is shown in the following example:
<?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 describes 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 the custom policy file example in Creating the Custom Policy File, 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 the custom policy file example in Creating the Custom Policy File, 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"> |
2.2.3.2.2 Defining the Policy Configuration File
This topic shows an example of policy-config.xml file with an entry for the ipAssertion policy.
The following is the example:
<?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 the server. Add this file to the custom executor jar file as mentioned in Creating the Custom Assertion JAR File.
2.2.4 Creating the Custom Assertion JAR File
Create a 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.
2.2.5 Adding the Custom Policy to the Policy Store
You can add the custom policy to the policy store using Fusion Middleware Control or WLST.
The following topics explain this further:
2.2.5.1 Adding a Custom Policy to the Policy Store Using Fusion Middleware Control
You can add a Custom Policy to the Policy Store by 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 Securing Web Services and Managing Policies with Oracle Web Services Manager.
2.2.5.2 Adding a Custom Policy to the Policy Store Using WLST
You can import the Custom Policy to the Policy Store by using WebLogic Scripting Tool (WLST) commands.
For information, see "Importing and Exporting Documents in the Repository" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
2.2.6 Deploying the Custom Assertion
You can add the custom assertion JAR to your CLASSPATH using the WLST command or by following manual process.
Perform the following steps to deploy custom assertion using the WLST command:
- Invoke the WLST command located at
ORACLE_HOME/oracle_common/common/bin/wlst.sh(UNIX) orORACLE_HOME\oracle_common\common\bin\wlst.cmd(Windows). -
Run the
appendToExtensionLoadercommand to add the custom assertion jar to servers specified by target list:appendToExtensionLoader('path to custom-assertion.jar’, ‘comma separated targets')For example:
connect('demouser', 'demopassword', 't3://localhost:7001') appendToExtensionLoader(‘/user/home/customAssertion.jar’, ‘server1,server2,server3')
You can also add the custom assertion JAR manually to your CLASSPATH by performing the following steps:
- Stop WebLogic Server.
- Copy the custom assertion JAR file you have created as described in Creating the Custom Assertion JAR File to the following directory:
$DOMAIN_HOME/lib. - Restart WebLogic Server.
For information about starting and stopping WebLogic Server, see "Starting and Stopping Oracle WebLogic Server Instances" in Administering Oracle Fusion Middleware.
2.2.7 Attaching the Custom Policy to a Web Service
Before attaching the custom policy to a web service, you need to first create a web service and then attach the custom policy to it using Fusion Middleware Control, using WLST or at design time.
Create a web service using the information described in "Roadmap for Implementing WebLogic Web Services" in Understanding WebLogic Web Services for Oracle WebLogic Server.
Attach the custom policy to the web service, as described in "Attaching Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
2.3 Testing the Web Service
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 Administering Web Services.
You can also test your web service by creating a client proxy for the web service using clientgen. For more information, see "Using the clientgen Ant Task to Generate Client Artifacts" in Developing JAX-WS Web Services for Oracle WebLogic Server.