This chapter describes how to use the API to implement some common features and exception handling. This information is organized into the following sections:
This section describes the various interfaces and methods to access the parameters inside the custom assertion executor.
It contains the following topics:
This topic lists interfaces and methods using which you can input parameters to custom assertions.
You can input parameters to custom assertions using the following interfaces and methods:
IAssertionBindings
IConfig
IPropertySet
getBindings
getConfigs
getPropertySets
getPropertyByName
getValue
This topic describes the various interfaces to access the contextual properties inside the custom assertion executor.
It contains the following topics:
OWSM context properties are accessed using the IMessageContext interface.
You access parameters to custom assertions using the following interfaces and methods:
IMessageContext
getServiceURL
getProperty
getAllProperty
This section describes the various interfaces to access the stages and retrieve the request and response messages inside the custom assertion executor.
It contains the following topics:
The OWSM custom security assertion has three stages: request, response, and fault.
The following is the details of these stages:
The request stage occurs when a client has made a request and that request is in the process of being delivered to its destination.
The response stage occurs after the destination has processed the message and is in the process of returning a response.
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
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 |
This topic shows an example which uses the XPath expression to identify the value of the node arg0.
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);
This topic shows an example of retrieving the value of a node by 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);
This topic explains the procedure to retrieve certificates for SSL.
To retrieve certificates for SSL:
This topic explains the procedure to access the transport properties of HTTP requests and responses.
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.
This topic describes the WSMException method to handle exceptions in the custom assertion executor.
It contains 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); } }