This chapter describes how to use the API to implement some common features and exception handling. This information is organized into the following sections:
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.
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.
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.
You can use XPath expression to access parts of a SOAP message inside the custom assertion executor.
The following topics explain this further:
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 |
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";
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);
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);
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:
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:
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.
You can handle exceptions in the custom assertion executor using the WSMException method.
For more information, see the following topics:
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.
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);
}
}