4 Implementing Advanced Features in Custom Assertions
This chapter describes how to use the API to implement some common features and exception handling. This information is organized into the following sections:
4.1 Supplying Parameters for Custom Assertions
You can access the parameters inside the custom assertion executor using the various interfaces and methods, such as IAssertionBindings, IConfig, IPropertySet, getBindings, getConfigs, getPropertySets, getPropertyByName, and getValue.
For step-by-step instruction on how to supply parameters for custom assertions, see Inputting Parameters to Custom Assertions.
4.2 Examining OWSM Context Properties
You can access OWSM context properties using the IMessageContext interface.
List of interfaces and methods:
-
IMessageContext
-
getServiceURL
-
getProperty
-
getAllProperty
For instructions on how to access the properties using the IMessageContext interface, see Accessing OWSM Context Properties.
4.3 Accessing OWSM Custom Security Assertion
You can access the stages and retrieve the request and response messages inside the custom assertion executor using the various interfaces.
The OWSM custom security assertion has three stages:
-
request: The request stage occurs when a client has made a request and that request is in the process of being delivered to its destination.
-
response: The response stage occurs after the destination has processed the message and is in the process of returning a response.
-
fault: The fault stage occurs in the event of a fault.
The contextual information (such as stages and messages) is passed using context properties and can be obtained by the IMessageContext interface. You can use the following interfaces and methods to access context properties:
-
IMessageContext
-
getStage
-
getRequestMessage
-
getResponseMessage
For instructions on how to access custom security assertion stages and interfaces, see Accessing Request, Response, and Fault Message Objects.
4.4 Accessing Parts of a Message Using XPath
You can use XPath expression to access parts of a SOAP message inside the custom assertion executor.
The following topics explain this further:
4.4.1 About XPath Expression
You can access parts of a SOAP message using XPath expression inside your custom policy executor.
In the following SOAP message example, the node arg0 has the value john:
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header/>
<S:Body>
<ns2:echo xmlns:ns2="http://project1/">
<arg0>john</arg0>
</ns2:echo>
</S:Body>
</S:Envelope>
In XPath, there are seven types of nodes: element, attribute, text, namespace, processing-instruction, comment, and document nodes. XPath uses path expressions to select nodes in an XML document. Table 4-1 describes some examples of XPath expressions.
Table 4-1 Examples of XPath Expressions
| Expression | Description |
|---|---|
|
/S:Envelope |
Selects from the root element S:Envelope. |
|
/S:Envelope/S:Body |
Selects all S:Body elements that are children of S:Envelope |
|
//S:Body |
Selects all S:Body elements no matter where they are in a document |
4.4.2 Identifying the Value of a Node
Follow the example to identify the value of the node arg0 using the XPath expression.
The following is the example:
//xpath expression that will be used to identify the node arg0
String xpathStr = "/S:Envelope/S:Body/ns2:echo/arg0";
4.4.3 Adding a Namespace to Namespace Context
You can define namespaces for any namespace referenced by the XPath expression and add them to the namespace context.
For example:
final DefaultNamespaceContext nsContext = new DefaultNamespaceContext();
nsContext.addEntry("S", "http://schemas.xmlsoap.org/soap/envelope/");
nsContext.addEntry("ns2", "http://project1/");
XPathFactory xpathFact = XPathFactory.newInstance();
XPath xpath = xpathFact.newXPath();
xpath.setNamespaceContext(nsContext);
4.4.4 Retrieving the Value of a Node
Follow the example to retrieve the value of a node using the evaluate method.
The following is the example:
//This will return node arg0 from SOAP message, here soapElement is
// org.w3c.dom.Elemet representation of SOAP message
org.w3c.dom.Node inputNode = (Node)xpath.evaluate(xpathStr, soapElement,
XPathConstants.NODE);
4.5 Retrieving Certificates Used by Container for SSL
You can retrieve certificates for SSL by using oracle.wsm.common.sdk.IMessageContext and then accessing the attributes of the certificate.
To retrieve certificates for SSL:
4.6 Accessing Transport Properties
You can access the transport properties of HTTP requests and responses by using the same message context as given in the example below and by retrieving the TransportContext from the message context.
To access transport properties for HTTP requests and responses:
4.7 Accessing Credential Store Framework Keys
You can use credential store framework (CSF) to manage the credentials securely, and store, retrieve, and maintain credentials.
To configure and use CSF:
Note:
The following JAR files must be included in the classpath: oracle.jps_12.1.2/jps-api.jar, oracle.jps_12.1.2/jps-unsupported-api.jar.
You must provide the CredentialAccessPermission permission to the custom policy executor jar. For more information about granting permissions, see Setting the Java Security Policy Permissions in Securing Applications with Oracle Platform Security Services.
4.8 Handling Exceptions in Custom Assertions
You can handle exceptions in the custom assertion executor using the WSMException method.
For more information, see the following topics:
4.8.1 About WSMException Method
Any exceptions during the execution of custom assertions must be handled by the WSMException in the custom assertion executor.
IResult execute(IContext mcontext) throws WSMException
This method must always return a non-null IResult object. The status field indicates success or failure or other state. The IResult.getFault() method is used to return the detailed cause for failure and returns null in case of success.
4.8.2 Processing Exceptions in WSMException
The exceptions arising from within the execute method of custom assertion executor should first be wrapped in WSMException, the execution status should be set to IResult.FAILED, and the generateFault method throws the WSMException.
The following example shows this:
IResult execute(IContext mcontext) throws WSMException {
IResult result = new Result();
try {
....
.....
} catch (Exception e) {
WSMException wsmException = new WSMException(e);
result.setStatus(IResult.FAILED);
generateFault(wsmException);
}
}