Usage of Evaluate XPATH Action

[Senthil_Kumar2 (Senthil Kumar)]

1. INTRODUCTION

This tutorial will explain the configuration and usage of the runtime action " Evaluate XPath Action" using CentraSite and webMethods Mediator.

The Evaluate XPath runtime policy enforcement will help in the following

• Identify the consumer application XPath making the request for the virtual service if identify attribute is turned ON.
• Validate against a set of global or pre-registered consumer applications with XPath in wM Mediator.

2. PRE-REQUISITE

• Knowledge in basics of wM Mediator runtime & XPath
• wM Mediator target should be created in CentraSite
• CentraSite configuration should be done in wM Mediator to validate the result

3. Summary

Steps involved when using Evaluate XPath Action in CentraSite and wM Mediator

1. Create a Consumer Application ( MyXPathConsumers ) with one or more Identification token(s) and deploy it to wM Mediator.
2. Create a virtual alias in BusinessUI.
3. Configure virtual alias with Evaluate XPath action for policy enforcement.
4. Deploy the virtual alias to wM Mediator.
5. Invoke the virtual service deployed in wM Mediator using SOAP Client (eg. SOAPUI).
6. Verify the response and troubleshooting

4. CONFIGURATIONS

4.1. Create and configure a consumer application with identification token

1. Login to CentraSite Control UI and Create an asset type of “Application”.

Choose " Identification token" as identifier and set the attribute value to the token Eg. " Chennai", “Reston”, “Darmstadt”, …

1. Navigate to Operations → Deployment and invoke " Deploy Consumers " tab. Select target(s)
2. Invoke " Syncronize " to deploy the Consumer Application to wM Mediator

Confirm the status as success
User can now enforce the restriction of allowing only these consumer applications or identifying the calling applications for virtual services in wM Mediator using the Evaluate XPath policy.

1. Verify deployed consumer application ( MyXPathConsumers ) with expected attribute in wM Mediator.

a. Open wM Mediator page, http://:5555/WmMediator and click on “Consumers” link.
b. Look for the deployed Consumer Application listed as in the sample screen below

4.2. Create a virtual alias with Evaluate XPath Action in BusinessUI

Perform the following steps to create a virtual alias with evaluate XPath expression action

1. Login to BusinessUI
2. Open a service details page of the service that needs to be virtualized.
3. Click on " Virtualize " action to get virtualization wizard screen. Provide alias name (eg.VS_EchoWS_XPath) in " Create a New Virtual Alias " input box
4. Select an endpoint from the list of " Endpoints of to Virtualize " and click " Next ".
   
   

4.3. Configure the Evaluate XPath policy

1. Navigate to " Policy Enforcement " heading → " Security " → drag & drop " Evaluate XPath " action into " Enforce " message flow.
2. Click on the configure icon, the icon will appears on mouse over of " Evaluate XPath " text in message flow.
3. Select one of the following option to identify the consumer(s)
4. " Global Consumers " (relax) - wM Mediator will try to verify the token (sec.4.1.2) against a list of all global consumers available in the Mediator.
5. " Registered Consumers " (strict)- wM Mediator will try to verify the t oken (sec.4.1.2) against the list of consumer applications which are registered as consumers for this specific API.

“Do not identify” (donotidentify) - wM Mediator will not identify consumer(s). Anonymous access is allowed for this specific API.
Note: Do not identify – Does not identify the consumer, nevertheless it will evaluate the value presents in the header and the request will be sent to the native service.
This policy will fail if the expected value(s) is not present in the request header.

Setting values to Evaluate XPath expression policy parameter
Namespace: Look for the service request (refer sec. ) to know the relevant namespace(s) and include them as required in the XPATH expression. refer sec. 6.3
Prefix eg. soapenv and axis
URI eg.http://schemas.xmlsoap.org/soap/envelope/ and Apache Axis2 – Apache Axis2/Java - Next Generation Web Services
XPath Expression: //soapenv:Envelope/soapenv:Body/axis:sayHello/axis:name
wM Mediator will execute the XPath expression and get the value at the specified XPath, this value is used for the identification token during the virtual service invocation.

Optional Step: Apply Log Invocation Policy to the virtual service and select CentraSite to send the log data. This step is only to generate and validate the events

1. Click " Virtualize " to complete the virtualization of the service.

5. DEPLOY AND VALIDATE THE DEPLOYMENT

1. Deploy the virtual alias (Eg. VS_EchoWS_XPath) to wM Mediator target(s) by clicking " Publish…" option from BusinessUI.
   

Verify deployed service(s) in wM Mediator page
Invoke http://<mediator_host>:5555/WmMediator from a web browser and provide credentials to access the page

Click “Services” link to get list of mediated service(s) in the wM Mediator and find the virtual service (eg.VS_EchoWS_XPath).

Validate virtual service definition in wM Mediator

1. In the above page, click on the [VSD] link for the virtual service to see the virtual service definition (VSD).
2. It should be able to find the following entries in the VSD as seen in the below snippet when Global Consumers ( relax ) is selected.
   
   

If Registered Consumers selected as identify ( strict ) method then the enforcement action element should be looks below. This is to identify the consumer from the register consumers list

If Do not identify selected as identify ( donotidentify ) method then the enforcement action element should be looks like

6. EXECUTION AND VERIFICATION OF VIRTUAL SERVICE RUNTIME INVOCATION

1. Get the WSDL by clicking on [WSDL] to invoke the virtual service as stated in the above step 5.2.b
2. Execute the virtual service ( Eg.VS_EchoWS_XPath ) from a SOAP Client with the specific token (sec. 4.1.6.b) in the request at the given XPath.
3. The sample virtual service request looks like

<soapenv:Envelope xmlns:soapenv=" xmlns:axis=">
   <soapenv:Header/>
   <soapenv:Body>
      <axis:sayHello>
         <axis:name>Chennai</axis:name>
      </axis:sayHello>
   </soapenv:Body>
</soapenv:Envelope>

Note

Note that the XPATH expression matches with " //soapenv:Envelope/soapenv:Body/ axis:sayHello/axis:name " and namespace at line number 1

The sample virtual service response looks like the below for successful consumer identification

<soapenv:Envelope xmlns:soapenv=">
   <soapenv:Body>
      <ns:sayHelloResponse xmlns:ns=">
         <ns:return>Hello Chennai</ns:return>
      </ns:sayHelloResponse>
   </soapenv:Body>
</soapenv:Envelope>

Following request should fail because the token mismatching. Whereas, the same request will succeed (send to the native service) if " Do Not Identify" method is chosen in step 4.3.3 .

<soapenv:Envelope xmlns:soapenv=" xmlns:axis=">
   <soapenv:Header/>
   <soapenv:Body>
      <axis:sayHello>
         <axis:name>SOMEWHERE</axis:name>
      </axis:sayHello>
   </soapenv:Body>
</soapenv:Envelope>

Response with anonymous consumer(s)

<soapenv:Envelope xmlns:soapenv=">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode xmlns:ns2=">ns2:Server</faultcode>
         <faultstring>Mediator encountered an error:Consumer could not be identified. 
                  Anonymous access is not allowed for this service! 
                  while executing operation:{http://ws.apache.org/axis2}sayHello service:VS_EchoWS_XPath at time:11:42:32 PM on date:Jul 24, 2014.
                  The client ip was:101.60.202.24. The current user:Default. The consumer application:null</faultstring>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>>

1. Verifying the result in log invocation event
2. View Runtime events after invoking the service as guided in sec. 6.2 and look for Consumer attribute’s value as expected (Eg. MyXPathConsumers ).

Successful consumer identification for the given XPath expression

Failure consumer identification with the policy violation event

Note

ConsumerID attribute value will be set only for API keys consumers. Hence the ConsumerID’s value can be ignored for now.

7. TROUBLESHOOTING WITH EVALUATE XPATH ACTION

1 Exception
Consumer could not be identified

Description
ERROR Consumer could not be identified. Anonymous access is not allowed for this service!

Possible cause/ Solution
Make sure the token value is correct as specified in the consumer application. sec. 4.1.6

Make sure the XPath expression and Namespace are configured properly as mentioned in sec. 4.1.6

Make sure the token value is in the proper case (it is case sensitive)

2 Exception
Exception while executing insequence mediators for virtual service: VS_EchoWS_XPath: com.softwareag.pg.exceptions.PolicyViolationException

Description
Mediator fault handler processing exception for service

<soapenv:Envelope xmlns:soapenv=">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode xmlns:ns2=">ns2:Server
         </faultcode>
<faultstring>Mediator encountered an error:
 Consumer could not be identified. 
 Anonymous access is not allowed for this service! 
 while executing operation:{http://ws.apache.org/axis2}sayHello 
 service:VS_EchoWS_XPath at 
 time:11:58:50 AM on date:Jul 28, 2014. The client ip was:10.60.32.111. 
 The current user:Default. The consumer application:null
</faultstring>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Possible cause/ Solution
Possible Root cause: Namespace mismatching

Make sure the XPath expression and Namespace are configured properly as mentioned in sec. 4.1.6

3 Exception
Exception while processing inbound request mediator proxy receiver:com.softwareag.pg.exceptions.PolicyViolationException

Description
Error while processing the XPath

<soapenv:Envelope xmlns:soapenv=">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode xmlns:ns2=">ns2:Server</faultcode>
<faultstring>
Mediator encountered an error:Consumer could not be identified. 
Anonymous access is not allowed for this service! while executing operation:
http://ws.apache.org/axis2}sayHello service:VS_EchoWS_XPath at 
time:12:10:22 PM on date:Jul 28, 2014. The client ip was:10.60.32.111. 
The current user:Default. The consumer application:null
</faultstring>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Possible cause/ Solution
Make sure the XPath expression and Namespace are configured properly as mentioned in sec. 4.1.6
Hint

You may encounter the similar exceptions and messages for namespace or XPath mismatch case as it is related to "Consumer could not be identified"

4 Exception
Mediator encountered an error:

Either a required header is missing in the request
or
The request cannot be authenticated
or
The request fails validation in mediator

Description
Unable to locate the XPath specified

<soapenv:Envelope xmlns:soapenv=">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode xmlns:ns2=">ns2:Server</faultcode>
         <faultstring>
Mediator encountered an error:Either a required header is missing in 
the request or the  request  cannot be authenticated or the request 
fails validation in mediator while executing operation:
{http://ws.apache.org/axis2}sayHello service:VS_EchoWS_XPath at 
time:1:31:47 PM on date:Jul 28, 2014. 
The client ip was:101.60.232.212. 
The current user:Default. 
The consumer application:null
</faultstring>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Possible cause/ Solution
Possible reason: Unable to locate the XPath as specified in the configured XPAath expression in the step 4.3 with " Do not identify " method.

Make sure the XPath expression is correct and Namespace are configured properly as mentioned in sec. 4.1.6.