CEPM JAX-WS Agent Guide V3.3.1.0 [Cisco Policy Enforcement Point]

Table Of Contents

CEPM JAX-WS Agent Guide

Contents

About This Document

Objective

Audience

CEPM JAX-WS Agent

Configuring CEPM JAX-WS Agent in Tomcat Server

Configuring CEPM JAX-WS Agent in Websphere Application Server

Resource Discovery for creating webservices resources using wsdl in CEPM

Testing a Sample Calculator Application with CEPM JAX-WS Agent

Documentation Updates

Related Documentation

Obtaining Documentation and Submitting a Service Request

CEPM JAX-WS Agent Guide

Revised: June 10, 2010, Doc Part No: OL-22922-01

Contents

•About This Document

•CEPM JAX-WS Agent

•Configuring CEPM JAX-WS Agent in Tomcat Server

•Configuring CEPM JAX-WS Agent in Websphere Application Server

•Testing a Sample Calculator Application with CEPM JAX-WS Agent

•Documentation Updates

•Related Documentation

•Obtaining Documentation and Submitting a Service Request

About This Document

Objective

This document gives the overview about the Cisco Enterprise Policy Manager (CEPM) JAX-WS Agent and explains the steps for installing the JAX-WS Agent.

Audience

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

CEPM JAX-WS Agent

In Cisco Enterprise Policy Manager (CEPM), the JAX-WS CEPM Authorization Handler is a message interceptor that can be easily plugged into the JAX-WS runtime to process the messages, and authorize access to the Web Service. This handler is invoked with a MessageContext component that provides access to messages and the ability to manage a set of properties. The Handler examines every incoming SOAP request, extracts the required information from the MessageContext and makes a PEP call, and receives the result of the authorization operation.

•In case of a positive reply (decision is true), the client is served with the requested Web Service.

•In case of a negative reply (decision is false), the handler blocks and terminates the SOAP request.

CEPM's JAX-WS2.0 Agent implements the following interface and method:

•Class: javax.xml.ws.handler.soap.SOAPHandler

•Method: public boolean handleMessage (msgContext context)

Where, msgContext refers to the MessageContext to process with this Handler.

The Handler returns an indication of whether handler processing should continue for the current message, such as

•Returns true to continue processing

•Returns false to block processing

Figure 1 shows the typical rundown of accessing a web service with JAX-WS2.0 CEPM's Handler:

Figure 1 CEPM JAX_WS Agent Deployment Diagram

The flow goes like this—

1. The client requests a Web Service to perform an operation.

2. The client request is passed to the JAX-WS Runtime component.

3. The JAX-WS Runtime makes a call to the configured CEPM Authorization Handler by passing the MessageContext.

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

5. The PEP makes a call to the PDP and gets the decision (i.e. true/false).

–If the decision is false, the client request is blocked.

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

Configuring CEPM JAX-WS Agent in Tomcat Server

To configure JAX-WS Agent in the Tomcat server version 5.5.27:

Step 1 Unzip CEPMJAX-WS_Agent.zip file. The contents of the .zip file are automatically unzipped in the JAX_WS_HOME directory..

Step 2 Copy libraries pep.jar, CEPM_Commons.jar, papclient.jar and cepmhandler.jar from JAX_WS_HOME directory to <PROJECTHOME>\WEB-INF\lib directory where <PROJECTHOME> is the root directory of the webservice.

Step 3 Open pep_config.xml file from JAX_WS_HOME\config\pep folder and update the following elements:

a. Replace the <pdp> URL value with the URL on which PDP Server is running.

b. Replace the URL value of <api> with the url on which PAP is running.

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

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

d. Replace the <application> tag with the name of the webservice which is protected by the JAX-WS agent.

For example, <application>Calculator</application>

e. <jax-ws-webservice-config>/<subject> source can be a SOAP-header, a Request-header or a WSSE-header. For example, to read a subject value from a SOAP header, set the <jax-ws-webservice-config>/<subject> tag as:
<jax-ws-webservice-config>
<subject source="soap-header">
    <value key="userid"/>
</subject>
.
.
.
</jax-ws-webservice-config>
f. <jax-ws-webservice-config>/<message-attributes> source type can be SOAP-header, Request-header, or Arguments (args). This tag passes the attributes as environment attributes to CEPM.

The following ahows a sample <message-attributes> tag input for SOAP-header:
// For all attribute values
<source type="soap-header">*</source>
//For specific attribute values e.g. stockquote, stocklimit:
<source type="soap-header">stockquote</source>
<source type="soap-header">stocklimit</source>
Refer to the CEPM PEP Configuration Guide for more information on updating pep_config.xml file.

Step 4 Add the Java environmental variables CEPM_AGENT_CONFIG, log4j.configuration and CEPM_DECISION_CACHE_CONFIG to the Java property, to specify the directory path of pep_config.xml, logging.xml and jbosscache.xml files.

Following is an example of JAVA_PROPERTIES:
JAVA_PROPERTIES = -DCEPM_AGENT_CONFIG=<JAX_WS_HOME>\config\pep\pep_config.xml 
-Dlog4j.configuration=<JAX_WS_HOME>\config\logging\logging.xml 
-DCEPM_DECISION_CACHE_CONFIG=<JAX_WS_HOME>\config\jbosscache\jbosscache.xml
Step 5 Configure CEPMHandler to the webservice. Update sun-jaxws.xml file in the <PROJECTHOME>\WEB-INF folder by specifying the handler class under <endpoint> as shown below:
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
    <handler-chain>
       <handler>
          <handler-class>com.cisco.epm.agent.jaxws.CEPMHandler</handler-class>
       </handler>
    </handler-chain>
</handler-chains>
The WebService is configured with CEPM JAX-WS Agent.

See Resource Discovery for creating webservices resources using wsdl in CEPM to know about how the resource discovery is done inthe CEPM PAP UI.

Configuring CEPM JAX-WS Agent in Websphere Application Server

To configure JAX-WS Agent in Websphere Application Server version 6.1.0.25:

Step 1 Unzip CEPMJAX-WS_Agent.zip file. The contents of the .zip file are automatically unzipped in the JAX_WS_HOME directory..

Step 2 Copy cepmhandler.jar and jaxws-ri libraries from JAX_WS_HOME directory to PROJECTHOME\WEB-INF\lib directory where PROJECTHOME is the root directory of the webservice.

Step 3 Copy libraries pep.jar, CEPM_Commons.jar and papclient.jar from JAX_WS_HOME directory to <IBM_HOME>\WebSphere\AppServer\lib directory.

Step 4 Open pep_config.xml file from JAX_WS_HOME\config\pep folder and update the following elements:

a. Replace the <pdp> URL value with the URL on which PDP Server is running.

b. Replace the URL value of <api> with the url on which PAP is running.

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

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

d. Replace the <application> tag with the name of the webservice which is protected by the JAX-WS agent.

For example, <application>Calculator</application>

e. <jax-ws-webservice-config>/<subject> source can be a SOAP-header, a Request-header or a WSSE-header. For example, to read a subject value from a SOAP header, set the <jax-ws-webservice-config>/<subject> tag as:
<jax-ws-webservice-config>
<subject source="soap-header">
    <value key="userid"/>
</subject>
.
.
</jax-ws-webservice-config>
f. <jax-ws-webservice-config>/<message-attributes> source type can be SOAP-header, Request-header, or Arguments (args). This tag passes the attributes as environment attributes to CEPM.

The following ahows a sample <message-attributes> tag input for SOAP-header:
// For all attribute values
<source type="soap-header">*</source>
//For specific attribute values e.g. stockquote, stocklimit:
<source type="soap-header">stockquote</source>
<source type="soap-header">stocklimit</source>
Refer to the CEPM PEP Configuration Guide for more information on updating pep_config.xml file.

Step 5 Create the following environment variables in the Websphere Application Server Console:

a. Go to WebSphere Application Server Admin console

b. Navigate Application servers > {server name} > Server Infrastructure > Java and Process Management > Process Definition > Additional Properties > Java Virtual Machine > Custom Properties

c. Click New.

d. Enter the following environment variables:

–CEPM_AGENT_CONFIG - This variable is set to locate pep_config.xml. It is mandatory to set this variable as it detects the agent configuration file.

For example:
Name=CEPM_AGENT_CONFIG 
Value=<JAX_WS_HOME>/config/pep/pep_config.xml
–CEPM_DECISION_CACHE_CONFIG - This variable is set to locate the jbosscache.xml.

For example,
Name=CEPM_DECISION_CACHE_CONFIG 
Value=<JAX_WS_HOME>/config/jbosscache/jbosscache.xml 
This variable is set only when <cacheEnabled> tag in the pep_config.xml file is set to True.

–log4j.configuration - This variable is set to configure the loggers.

For example,
Name=log4j.configuration 
Value=<JAX_WS_HOME>/config/logging/logging.xml
This variable is set only when <cacheEnabled> tag in the pep_config.xml file is set to True.

e. Click Apply and then click Save.

Step 6 Configure CEPMHandler to the webservice. To do this, update sun-jaxws.xml file in the <PROJECTHOME>\WEB-INF folder by specifying the handler class under <endpoint> as shown below:
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
    <handler-chain>
       <handler>
          <handler-class>com.cisco.epm.agent.jaxws.CEPMHandler</handler-class>
       </handler>
    </handler-chain>
</handler-chains>
Note You can find the sun-jaxws.xml file at <JAX_WS_HOME>/jaxws-ri.

Step 7 Deploy the webservice in WebSphere Application Server.

Step 8 Go to WebSphere Application Server Admin console.

Step 9 Navigate to Applications > Enterprise Applications and click on the deployed webservice.

Step 10 Click on Detail Properties > "Class loading and update detection" and update the "Class loader order" to "Classes loaded with application class loader first".

Step 11 Click Apply and then click Save (on the top of the screen).

Step 12 Again navigate to Applications > Enterprise Applications and click on the deployed webservice.

Step 13 Click on Modules > Manage Modules and Click on the deployed webservice module.

Step 14 Update General Properties > "Class loader order" to "Classes loaded with application class loader first".

Step 15 Click Apply and then click Save (on the top of the screen).

The WebService is configured with CEPM JAX-WS Agent.

Resource Discovery for creating webservices resources using wsdl in CEPM

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

Step 2 Under the configured application:

a. click `Create Resources from External Sources'.

b. Select Source Type as wsdl. Select URL/FileName Type as URL.

c. Enter the value for wsdl running in URL.

For example: http://host:port/CalculatorService/CalculatorService?wsdl.

Step 3 Click on Create.

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

Refer to the CEPM User Guide for more details on managing entitlement policies.

Testing a Sample Calculator Application with CEPM JAX-WS Agent

This distribution (CEPMJAX-WS_Agent.zip file) contains a sample calculator service which can run in both Apache Tomcat Server 5.5.27 and Websphere Application Server 6.1.0.25. Take the following steps to test how to protect this sample application using CEPM JAX-WS agent.

Step 1 Copy CalculatorService.war [Calculator Service] from the JAX_WS_HOME directory and deploy it in the Tomcat server (apache-tomcat-5.5.27).

Step 2 Configure the CEPM JAX-WS Agent by following the steps as mentioned in

–For Tomcat—Configuring CEPM JAX-WS Agent in Tomcat Server

–For Websphere—Configuring CEPM JAX-WS Agent in Websphere Application Server

Step 3 Modify the pep_config.xml file:
<cache 
		.
		.
		<applicationgroup>Prime group</applicationgroup>
		<application>Calculator</application>
</cache>
<jax-ws-webservice-config>
    	<subject source="soap-header">
    		<value key="user"/>
    	</subject>
		<message-attributes>    		
    		<source type="args">*</source>
		</message-attributes>
</jax-ws-webservice-config>
Step 4 Start the Tomcat server.

Step 5 Start CEPM and perform the following tasks:

•Create a PDP.

•Create the application group "Prime group" and application "Calculator" as specified in the pep_config.xml.

•In the PAP UI, go to Home > System Config > Application page. Edit the Calculator application and attach the PDP to it.

Step 6 Run WSDL Resource Discovery in CEPM under the "Calculator" application.
URL: http://host:port/CalculatorService/CalculatorService?wsdl
Step 7 Open the CalculatorClient {Calculator Service Client} under JAX_WS_HOME, and find the testClient.bat file.

Step 8 To perform some calculator operations, run testClient.bat by passing the following command line arguments.

a. Endpoint
For example: http://host:port/CalculatorService/CalculatorService
b. UserName

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

d. Operand1

e. Operand2

For Example:
testClient.bat http://host:port/CalculatorService/CalculatorService Tom add 3 5
Based on the permissions specified within CEPM:

•If the user 'Tom' is authorized to perform this operation, Result will be displayed.

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

Documentation Updates

Table 1 Updates to CEPM JAX-WS Agent Guide

Date

Description

June 10, 2010

Cisco Enterprise Policy Manager (EPM) Release 3.3.1.0

The following changes have been made to this document since Release 3.3.0.0:

•Added steps to configure CEPM JAX_WS Agent in Websphere Application Server version 6.1.0.25

Related Documentation

•CEPM User Guide V3.3.1.0

•CEPM PEP Configuration Guide

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, CCENT, CCSI, Cisco Eos, Cisco Explorer, Cisco HealthPresence, Cisco IronPort, the Cisco logo, Cisco Nurse Connect, Cisco Pulse, Cisco SensorBase, Cisco StackPower, Cisco StadiumVision, Cisco TelePresence, Cisco TrustSec, Cisco Unified Computing System, Cisco WebEx, DCE, Flip Channels, Flip for Good, Flip Mino, Flipshare (Design), Flip Ultra, Flip Video, Flip Video (Design), Instant Broadband, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn, Cisco Capital, Cisco Capital (Design), Cisco:Financed (Stylized), Cisco Store, Flip Gift Card, and One Million Acts of Green are service marks; and Access Registrar, Aironet, AllTouch, 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 Lumin, Cisco Nexus, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, Continuum, EtherFast, EtherSwitch, Event Center, Explorer, Follow Me Browsing, GainMaker, iLYNX, IOS, iPhone, IronPort, the IronPort logo, Laser Link, LightStream, Linksys, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, PCNow, PIX, PowerKEY, PowerPanels, PowerTV, PowerTV (Design), PowerVu, Prisma, ProConnect, ROSA, SenderBase, SMARTnet, Spectrum Expert, StackWise, WebEx, and the WebEx logo are registered trademarks of Cisco 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. (1002R)

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.

© 2010 Cisco Systems, Inc. All rights reserved.

Cisco Policy Enforcement Point

CEPM JAX-WS Agent Guide V3.3.1.0

Hierarchical Navigation

Downloads

Table Of Contents

CEPM JAX-WS Agent Guide

Contents

About This Document

Objective

Audience

CEPM JAX-WS Agent

Configuring CEPM JAX-WS Agent in Tomcat Server

Configuring CEPM JAX-WS Agent in Websphere Application Server

Resource Discovery for creating webservices resources using wsdl in CEPM

Testing a Sample Calculator Application with CEPM JAX-WS Agent

Documentation Updates

Related Documentation

Obtaining Documentation and Submitting a Service Request

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. (1002R)

© 2010 Cisco Systems, Inc. All rights reserved.