Cisco Policy Enforcement Point

Table Of Contents

Cisco Enterprise Policy Manager JAX-WS Agent Guide, Release 3.3.2.0

Contents

About This Document

Objective

Audience

CEPM JAX-WS Agent

Configuring CEPM JAX-WS Agent in Websphere Application Server with Web Services Feature Pack

Resource Discovery for Creating Webservices Resources Using WSDL in CEPM

Testing a Sample Application with CEPM JAX-WS Agent

Documentation Updates

Related Documentation

Obtaining Documentation and Submitting a Service Request

Cisco Enterprise Policy Manager JAX-WS Agent Guide, Release 3.3.2.0

---

Revised: March 14, 2012, Doc Part No: OL-26470-01

Contents

•About This Document

•CEPM JAX-WS Agent

•Configuring CEPM JAX-WS Agent in Websphere Application Server with Web Services Feature Pack

•Testing a Sample 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 to integrate the JAX-WS Agent with applications running in Websphere Application Server with Web Services Feature Pack applied to it.

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 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 Websphere Application Server with Web Services Feature Pack

To configure JAX-WS Agent in the Websphere application server version 6.1.0.25 with Web Services Feature Pack applied to it, complete the following steps:

---

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

Step 2 Copy CEPMHandler.jar from JAX_WS_HOME directory to PROJECTHOME\WEB-INF\lib directory, where PROJECTHOME is the root directory of the webservice.

Step 3 Copy the libraries such as 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>HelloApp</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 is 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 Add the Java environment variables such as CEPM_AGENT_CONFIG, PAP_LOG_CONFIG and CEPM_DECISION_CACHE_CONFIG to the Java property, to specify the directory path of pep_config.xml, logging.xml and jbosscache.xml files. You can add the environment variables in either of the following ways:

a. Set the JAVA_PROPERTIES as follows:

JAVA_PROPERTIES = -DCEPM_AGENT_CONFIG=<JAX_WS_HOME>\config\pep\pep_config.xml 
-DPAP_LOG_CONFIG=<JAX_WS_HOME>\config\logging\logging.xml 
-DCEPM_DECISION_CACHE_CONFIG=<JAX_WS_HOME>\config\jbosscache\jbosscache.xml

b. Create the environment variable using the WebSphere Application Server Admin Console. To do this:

•Go to WebSphere Application Server Admin console

•Choose Application servers > {server name}

•Choose Server Infrastructure > Java and Process Management > Process Definition

•Choose Additional Properties > Java Virtual Machine > Custom Properties

•Click New.

•Enter the following environment variables:

–CEPM_AGENT_CONFIG - This variable is set to locate the pep_config.xml file. 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 file.

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.

–PAP_LOG_CONFIG - This variable is set to configure the loggers.

For example,

Name=PAP_LOG_CONFIG

Value=<JAX_WS_HOME>/config/logging/logging.xml

•Click Apply and then click Save.

Step 6 Configure CEPMHandler to the webservice. To do this, update the handler-chain.xml file in the <PROJECTHOME>\WEB-INF folder by specifying the handler class under <endpoint> as shown below:

<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">

			<jws:handler-chain name="CEPMHandlerChain">

				<jws:handler>

					
<jws:handler-class>com.cisco.epm.agent.jaxws.websphere.CEPMHandler</jws:handler-class>			                   

				</jws:handler>

			</jws:handler-chain>	

		</jws:handler-chains>

The WebService is configured with CEPM JAX-WS Agent.

---

See Resource Discovery for Creating Webservices Resources Using WSDL in CEPM for more information on the resource discovery feature.

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/HelloWebService/HelloService?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 Application with CEPM JAX-WS Agent

This distribution (CEPMJAX-WS_Agent.zip) contains a sample Hello EJB Webservice which can run in Websphere Application Server 6.1.0.25. Take the following steps to test how this sample application can be protected using CEPM JAX-WS agent.

---

Step 1 Copy HelloService.ear [Hello EJB Webservice] from the JAX_WS_HOME directory and deploy it in the WebSphere Application Server.

Step 2 Configure the CEPM JAX-WS Agent by following the steps as mentioned in—Configuring CEPM JAX-WS Agent in Websphere Application Server with Web Services Feature Pack.

Step 3 Modify the pep_config.xml file:

<cache 

		.

		.

		<applicationgroup>Prime group</applicationgroup>

		<application>HelloApp</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 CEPM and perform the following tasks:

•Create a PDP.

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

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

Step 5 Run WSDL Resource Discovery in CEPM under the "HelloApp" application.

URL: http://host:port/HelloWebService/HelloService/helloservice?wsdl

Step 6 Open the HelloWebServiceClient (Hello Service Client) under JAX_WS_HOME, and find the testClient.bat file.

Step 7 To perform sayHello operation, run testClient.bat by passing the following command line arguments.

a. Endpoint

For example: http://host:port/HelloWebService/HelloService

b. UserName

c. Say Hello to

For Example:

testClient.bat http://host:port/HelloWebService/HelloService Tom Mary

Based on the permissions specified within CEPM:

•If the user 'Tom' is autorized to perform this operation, result will be displayed as -

Result is[ Hello :Mary]

•If the user 'Tom' is not autorized to perform this operation, a message will be displayed saying 'User 'Tom' is Not Authorized to Say Hello to 'Mary'.

---

Documentation Updates

Table 1 Updates to Cisco Enterprise Policy Manager JAX-WS Agent Guide, Release 3.3.2.0

Date	Description
March 14, 2012	Cisco Enterprise Policy Manager (EPM) Release 3.3.2.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

•Cisco Enterprise Policy Manager User Guide, Release 3.3.2.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 an RSS feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service. Cisco currently supports RSS Version 2.0.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned 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. (1110R)

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.

© 2012 Cisco Systems, Inc. All rights reserved.