Cisco Policy Enforcement Point

Table Of Contents

CEPM Axis2 Agent Guide

Contents

About This Document

Objective

Audience

Introduction

Steps to Configure Axis2 CEPM Handler to Protect Web Services

Resource Discovery (For Creating Web Services Resources) using wsdl in CEPM

Steps to Test Calculator Sample with CEPM Axis2 Agent

Documentation Updates

Related Documentation

Obtaining Documentation and Submitting a Service Request

CEPM Axis2 Agent Guide

---

Revised: July 17, 2009, OL-19564-01

Contents

•About This Document

•Introduction

•Steps to Configure Axis2 CEPM Handler to Protect Web Services

•Steps to Test Calculator Sample with CEPM Axis2 Agent

•Documentation Updates

•Related Documentation

•Obtaining Documentation and Submitting a Service Request

About This Document

Objective

This document gives the overview about the Axis2 Agent and explains the steps for configuring Axis2 CEPM handler to protect Web Services.

Audience

This guide is for administrators who use CEPM and are responsible for resource modelling and entitlement management.

Introduction

The Axis2 CEPM Handler operates as an authorization module to protect any Axis2 web services. The handler is inserted in the request flow of a web application, in front of any resource, that requires authorization protection. The handler examines every incoming Simple Object Access Protocol (SOAP) request. It extracts the required information from the MessageContext, makes a CEPM PEP call, and receives back the result of the authorization operation.

•In case of a positive reply, the request is passed to the next resource in the request flow.

•In case of a negative reply, the handler blocks and terminates the SOAP request by throwing an AxisFaultException and returns an error to the SOAP requester.

CEPM's Axis2 agent extends the following class and method:

•Class—org.apache.axis2.handlers.AbstractHandler

•Method—public InvocationResponse invoke(MessageContext msgContext) throws AxisFault, where msgContext refers to the MessageContext to process with this Handler.

•throws,

•Exception—AxisFault exception is thrown when user is not authorized to perform this operation.

Axix2 CEPM Handler shows the typical rundown of accessing a web service with Axis2 CEPM's Handler

Figure 1 Axix2 CEPM Handler

1. Client requests the Web Service to perform an operation.

2. Client request is passed to the Axis Engine, where the requested Web Service is deployed.

3. This Axis2 Engine makes a call to the configured CEPM Authorization Handler by passing the MessageContext.

4. CEPM Authorization Handler extracts the required information from the MessageContext and makes a call to the PEP.

5. PEP makes a call to the PDP or Cache and gets the decision that is, true or false.

–If the decision is false, an Axis fault exception is thrown.

–If the decision is true, the client is served with the requested Web Service to perform the operation.

Steps to Configure Axis2 CEPM Handler to Protect Web Services

To set up Axis2 CEPM handler:

---

Step 1 Copy pep.jar, papclient.jar and CEPM_Commons.jar files to <AXIS2_HOME>\WEB-INF\lib directory andcopy the cepmhandler.jar file to <AXIS2_HOME>\WEB-INF\modules directory.

Step 2 Open the pep_config.xml file from <AGENT_HOME>\config\pep folder and update the following elements:

a. Update the URL value of <pdp> to the URL on which PDP Server is running.

b. Update the URL value of <api> to the URL on which PAP is running.

c. Update the <axis2_config>/<applicationgroup> tag with the name of the application group under which the protected application is created.

For example, <applicationgroup>Prime group</applicationgroup>

d. Update the <axis2_config>/<application> tag with the name of the service which is protected by the Axis2 agent.

For example, <application>Calculator</application>

e. <axis2_config>/<subject> source can be request-header/soap-header. This tag is to consider subject key form Request-header/SOAP-header.

f. <axis2_config>/<message-attributes> source type can be Request- header/SOAP-header/args. This tag passes these attributes as environment attributes to CEPM.

Step 3 Add the Java environmental variables such as CEPM_AGENT_CONFIG, log4j.configuration and CEPM_DECISION_CACHE_CONFIG to the JAVA_OPTS for specifying the directory path of pep_config.xml, logging.xml and jbosscache.xml files.

Following is an example of JAVA_PROPERTIES:

-DCEPM_AGENT_CONFIG=<AGENT_HOME>\config\pep\pep_config.xml 
-Dlog4j.configuration=<AGENT_HOME>\config\logging\logging.xml 
-DCEPM_DECISION_CACHE_CONFIG=<AGENT_HOME>\config\jbosscache\jbosscache.xml

Step 4 Start the application server.

Step 5 For CEPM Handler configuration on any webservices, the CEPM module should be deployed in the application server and engage the CEPMModule for the webservices. To do this:

a. Open http://<host>:<port>/<AXIS2_NAME>/axis2-web, where <AXIS2_NAME> is the name of axis2 deployed in the application server.

b. Click Administration.

c. Login with Username as admin and Password as axis2.

d. Choose a service and click Engage Module. Select CEPMModule as the Module and Calculator as the Service.

e. Click Engage.

---

Note A message 'CEPMModule module is engaged to the service successfully' is displayed.

---

The WebService is now configured with CEPM Axis2 Agent.

Resource Discovery (For Creating Web Services Resources) using wsdl in CEPM

---

Step 1 Login to CEPM. Select Home > Manage Entities > Resources.

Step 2 Under the configured application, Click Create Resources from External Sources. Select Source Type as wsdl. Select URL/FileName Type as URL. Enter the value for wsdl running in URL.

For example: http://host:port/Axis2Service/services/Calculator?wsdl.

Step 3 Click Create.

Step 4 Select all of the Operation Name entries and click Create. This creates all the resources under the specified application.

---

Steps to Test Calculator Sample with CEPM Axis2 Agent

This distribution contains a sample calculator service which runs in Tomcat server.

---

Step 1 Copy Axis2Service.war [Calculator Service] fromthe <AGENT_HOME> folder and deploy in the Tomcat server.

---

Note If Axis2 is already deployed in the Tomcat server, copy Axis2Service.war [Calculator Service] from the <AGENT_HOME> folder, and place it in <AXIS2_HOME>\WEB-INF\services directory.

---

Step 2 Configure the CEPM Axis2 Agent as mentioned in Steps to Configure Axis2 CEPM Handler to Protect Web Services.

Step 3 Modify the pep_config.xml file.

<axis2_config>	

		<applicationgroup>Prime group</applicationgroup>

		<!-- ApplicationName from the above mentioned ApplicationGroup for which the 
caching will be performed -->

		<application>Calculator</application>

		<subject source="soap-header">

    		<value key="userName"/>

    	</subject>

		<message-attributes> 

		  	<source type="args">arg0</source>			

    	</message-attributes>

</axis2_config>	

Step 4 Start CEPM and perform the following tasks:

•Create a PDP. Refer to CEPM User Guide for more details on how to create a PDP.

•Create the application group 'Prime group' and the application 'Calculator' as specified in the pep_config.xml and associate the PDP.

•Run WSDL Resource Discovery in CEPM, under 'Calculator' application.

URL: http://host:port/Axis2Service/services/Calculator?wsdl

Step 5 Open Axis2ServiceClient [Calculator Service Client] under <AGENT_HOME>, and find the testClient.bat file.

Step 6 Run the testClient.bat to perform the calculator operations by passing the following command line arguments:

a. Endpoint

For example: http://host:port/Axis2Service/services/Calculator

b. UserName

c. Operator [add, sub, div or mul]

d. Operand1

e. Operand2

For example,

testClient.bat http://host:port/Axis2Service/services/Calculator Tom add 3 5

Based on the permissions specified within CEPM:

•If the user 'Tom' is authorized to perform this operation, a result is displayed.

•If the user 'Tom' is not authorized to perform this operation, a message is displayed saying `Tom is not authorized to perform add operation'.

---

Documentation Updates

Table 1 Updates to CEPM Axis2 Agent Guide

Date	Description
July 9, 2009	Minor edits and template/boilerplate updates for publication to Cisco.com
April 3, 2009	Cisco Enterprise Policy Manager (EPM) Release 3.3.0.0

Related Documentation

CEPM_User_Guide_V3.3.0.0.pdf

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What's New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at:

http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html

Subscribe to the What's New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS Version 2.0.

CCDE, CCSI, CCENT, Cisco Eos, Cisco HealthPresence, the Cisco logo, Cisco Lumin, Cisco Nexus, Cisco Nurse Connect, Cisco Stackpower, Cisco StadiumVision, Cisco TelePresence, Cisco WebEx, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn and Cisco Store are service marks; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iPhone, iQuick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise, The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.

All other trademarks mentioned in this document or website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0903R)

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

© 2009 Cisco Systems, Inc. All rights reserved.

---