[an error occurred while processing this directive]

Cisco Policy Enforcement Point

CEPM JAX-RPC Agent Guide

Hierarchical Navigation

Downloads

 Feedback

Table Of Contents

CEPM JAX-RPC Agent for WebSphere Guide

Contents

About This Document

Objective

Audience

CEPM JAX-RPC Agent

Configuring JAX-RPC Agent in WebSphere Application

Configuring JAX-RPC Agent in Static Application Using In-Process PDP

Sample Application Implementation

Documentation Updates

Related Documentation

Obtaining Documentation and Submitting a Service Request


CEPM JAX-RPC Agent for WebSphere Guide

Revised: July 13, 2009, Doc Part No: OL-19567-01

Contents

•About This Document

•CEPM JAX-RPC Agent

•Configuring JAX-RPC Agent in WebSphere Application

•Configuring JAX-RPC Agent in Static Application Using In-Process PDP

•Sample Application Implementation

•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 Manger (CEPM) JAX_RPC Agent and explains the steps for installing the Agent.

Audience

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

CEPM JAX-RPC Agent

The JAX-RPC Agent is a fine-grained authorization module that protects any WebSphere application. The Agent is inserted in the request flow of a web application, in front of any resource that requires authorization protection. The JAX-RPC Agent examines every incoming Simple Object Access Protocol (SOAP) request and extracts the subject, resource, action (method name), and environment attributes from the message context in the handleRequest (MessageContext) method of CepmHandler. The Agent then passes the extracted data (subject, resource, action, envMap) to the authorization manager. Using the policy and other parameters of the requested subject, the authorization manager sends back the result of the authorization operation:

•If the decision is true which implies the user can access the requested resource.

•If the decision is false, the SOAP request is blocked and terminated by a NotAuthorized exception and an error is returned to the SOAP requester.

Figure 1 CEPM JAX-RPC Agent Deployment Diagram

In the JAX-RPC framework, while a user is trying to access a web application, the user is intercepted by Cepmhandler. This handler then sends the authorization request to the Policy Enforcement Point (PEP). As a part of the CEPM features, the PEP forwards the request to the concerned Policy Decision Point(s) (PDPs). The PDP authorizes the access permission and sends the decision to the PEP, which allows the user to access the requested application.

Configuring JAX-RPC Agent in WebSphere Application

To configure the JAX-RPC Agent in WebSphere Application Server-6.1.0:

Step 1 Unzip CEPM_JaxRpcAgentV3.3.0.0.zip file to <JAX_RPC_HOME>.

Step 2 Copy cepmjaxrpc.jar, pep.jar, and CEPM_Commons.jar files from the unzipped folder into the <PROJECTHOME>\WEB-INF\lib directory where <PROJECTHOME> is the root directory of the webservice.

Step 3 Edit the following tags in the pep_config.xml file:

a. Replace the <PDP> tag with the PDP EndPoint (that is, the host and port details of the machine where the PDP server is running).

b. Replace the <applicationgroup> and <application> tags with the names of the required application group and application that need to be protected.

c. Replace the <jax-rpc-webservice-config> tag with the subject details in the <subject> tag.

For example, if the subject is coming from "soap-header" and the key for the subject is "userid", the example tags would look like this: 

<subject source="soap-header">

       <value key="userid"/>

</subject>

If the subject is coming from "request-header" and the key for the subject is "userid", the example tags would look like this: 

<subject source="request-header">

      <value key="userid"/>

</subject>

If the subject is coming from "wsse-header" and the key for the subject is "userid", the example tags would look like this: 

<subject source="wsse-header">

      <value key="wsse"/>

</subject>

d. Update the <message-attributes> tag by setting the MessageAttributes values.

Note The key attribute defined in the <message-attributes> tag is used as the environment key for the PEP API. There can be various sources of the message attribute keys, including the SOAP-header, Request-header, and Method arguments (arg). The possible values for the <message-attributes> tag can be * (that is, it considers all attributes in the specified source), or any specific key. The CepmHandler extracts values from the specified key sources and passes them to the PEP. If the values come from the SOAP-header, the source type will be <source type="soap-header">.

You can set values as: 

<message-attributes>

    		<source type="soap-header">*</source>

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

		.

		.

		.

</message-attributes>

The following are some sample <message-attributes> tag inputs:

For "soap-header":

–For all attribute values: 

<source type="soap-header">*</source>

–For specific attribute values (stockquote and stocklimit): 

<source type="soap-header">stockquote</source>

<source type="soap-header">stocklimit</source>

For "request-header":

–For all attribute values: 

<source type="request-header">*</source>

–For specific attribute values, (stockquote and stocklimit): 

<source type="request-header">stockquote</source>

<source type="request-header">stocklimit</source>

For method arguments (for example, invoking a method stockQuote(arg1, arg2)):

–For all attribute values (arg1 and arg2): 

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

–For specific attribute values: 

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

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

Step 4 Add CepmHandler to the webservice by updating the webservices.xml file in WEB-INF folder of the web application by mentioning the handler class under the <port-component> tag as shown here: 

<webservice-description>

   <port-component>

       <handler>

          <handler-name>CEPM_JAXRPC_Handler</handler-name>

          <handler-class>com.cisco.epm.agent.webservice.CepmHandler</handler-class>

       </handler>

   </port-component>

</webservice-description>

Step 5 Create environment variables:

a. Go to the WebSphere administration console.

b. Choose Application servers > <server name> > Process Definition > 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. You must set this variable because it detects the agent configuration file. For example: 

Name=CEPM_AGENT_CONFIG

Value=JAX_RPC_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_RPC_HOME/config/jbosscache/jbosscache.xml

Note 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_RPC_HOME\config\logging\logging.xml

e. Click Apply then click Save.

Step 6 Restart the WebSphere Server to install the JAX-RPC Agent in WebSphere application.

Configuring JAX-RPC Agent in Static Application Using In-Process PDP

In-process PDP is used as an alternate for PDP when you are working with static applications. In this case there will be no pep_config.xml file. The necessary agent tag ( <jax-rpc-webservice-config>) is already a part of the pdp_config.xml file.

To configure the JAX-RPC Agent in the static application running in WebSphere Application Server-6.1.0, follow these steps:

Step 1 Unzip CepmInProcessPDPJax_Rpc_AgentV3.3.0.0.zip file to your local machine. The unzipped folder ia called <JAX_RPC_HOME>.

Step 2 Copy InProcessPDP.jar, cepmhandler.jar, thirdpartylib_inprocess.jar files from the <Inprocess_jax_rpc_home> folder to the <WebSphere-home>\AppServer\lib folder.

Step 3 Open the configure.properties file from the <JAX_RPC_HOME>/bin folder and update the following parameters:

•DOMAIN_NAME—refers to the domain name [repository name].

•CEPM.DB_SELECTION—refers to the database type. You can select Oracle, MSSQL, or DB2. If no selection is made, it will default to Oracle.

•Update the following database properties:

–CEPM.DB_URL—Database URL in the following format: jdbc:oracle:thin:@hostName:portName:databaseName

–CEPM.DB_USR—Database username

–CEPM.DB_PWD—Encrypted password

–CEPM.DB_DRIVER—Database driver name

Note The database password is encrypted in the configuration files. To get an encrypted password, run the encryptor.bat(sh) file from the <JAX_RPC_HOME>\bin folder using the following command:

For Windows: encryptor.bat JAVA_HOME Password

For Solaris/Linux: encryptor.sh JAVA_HOME Password

where JAVA_HOME is replaced with the corresponding folder path for JAVA_HOME and Password is replaced with the specified database password. When this command executes, an encrypted password is displayed. You must substitute this encrypted password in the Password parameter of the database properties in the configure.properties file.

Step 4 Run the configure.bat(sh) file from the <JAX_RPC_HOME>/bin folder to configure the in-process PDP. This generates a specific <jax-rpc-webservice-config> tag in the pdp_config.xml file.

Step 5 To check whether the in-process PDP is configured properly, run the InprocessPDPSampleTest.bat(sh) file from the <JAX_RPC_HOME>/bin folder.

The remaining steps of integrating the JAX-RPC Agent with in-process PDP are same as mentioned those to integrate the JAX-RPC agent in a web application.

Step 6 Provide the pdp server End point and CEPM API in the pdp_config.xml file.

a. Edit the < jax-rpc-webservice-config> tag and provide subject information in the <subject> tag.

For example, to get the subject from "soap-header", the tag should be modified as follows with the required key in <value> tag 

<jax-rpc-webservice-config>

<subject source="soap-header">

<value key="userid"/>

</subject>

</jax-rpc-webservice-config>

For example, to get the subject from "request-header", the tag should be modified as follows with the required key in the <value> tag: 

<jax-rpc-webservice-config>

<subject source="request-header">

<value key="userid"/>

</subject>

.

.	                                                    
</jax-rpc-webservice-config>

b. Update the <message-attributes> tag by setting the MessageAttributes values.

For "soap-header":

–For all attribute values: 

<source type="soap-header">*</source>

–For specific attribute values (stockquote and stocklimit): 

<source type="soap-header">stockquote</source>

<source type="soap-header">stocklimit</source>

For "request-header":

–For all attribute values: 

<source type="request-header">*</source>

–For specific attribute values (stockquote and stocklimit): 

<source type="request-header">stockquote</source>

<source type="request-header">stocklimit</source>

For method arguments (for example, invoking a method stockQuote(arg1, arg2)):

–For all attribute values (arg1 and arg2): 

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

–For specific attribute values: 

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

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

Step 7 Configure CepmHandler to the webservice. To do this:

a. Update the webservices.xml file in WEB-INF folder of the web application by mentioning the handler class under the <port-component> tag as shown here: 

<webservice-description>

   <port-component>

       <handler>

          <handler-name>CEPM_JAXRPC_Handler</handler-name>

          <handler-class>com.cisco.epm.agent.webservice.CepmHandler</handler-class>

       </handler>

   </port-component>

</webservice-description>

b. Place the CepmHandler.jar in the classpath, that is, application\WEB-INF\lib directory.

Step 8 Create environment variables:

a. Go to the WebSphere administration console.

b. Choose Application servers > {server name} > Process Definition > 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. You must set this variable because it detects the agent configuration file. For example: 

Name=CEPM_AGENT_CONFIG

Value=<JAX_RPC_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_RPC_HOME>/config/jbosscache/jbosscache.xml

Note This variable is set only when <cacheEnabled> tag in the pep_config.xml file is set to true.

–CEPM_HOME: This variable is set to configure the loggers. For example 

Name=CEPM_HOME 

Value=<JAX_RPC_HOME>\config\logging\logging.xml

e. Click Apply then click Save.

Step 9 Edit the SampleWebservice.war file by placing InProcessPDP.jar, CepmHandler.jar, thirdpartylib_inprocess.jar files under "WEB-INF\lib" directory.

Step 10 Restart the websphere server and access the client application.

Based on the permissions specified in 'CEPM', either user will be served with the requested resource or will get SOAPFaultException:'User Not authorized to invoke this service'.

Sample Application Implementation

To test the CaluclatorService (jax-rpc) sample with the CEPM JAX-RPC Agent:

Step 1 Find the CalculatorService.ear sample in <JAX_RPC_HOME>

Note The directory where CepmJax_Rpc_Agent.zip is unzipped will be referred as JAX_RPC_HOME directory.

Step 2 Follow the steps to configure CEPM JAX-RPC Agent as mentioned in Configuring JAX-RPC Agent in WebSphere Application.

Step 3 Edit the pep_config.xml file, and update

•the application group and application names: 

<cache>

     ;;

<applicationgroup>Prime group</applicationgroup>

<application>Calculator App</application>

•Configure the <jax-rpc-webservice-config> tag: 

<jax-rpc-webservice-config>

		<subject source="soap-header">

    		<value key="userid"/>

    	</subject>

    	<message-attributes> 

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

    	</message-attributes>

      <!--Location to insert policy attributes and obligation Ex: soap-header -->

		<insertobligations dest="soap-header"></insertobligations>

       <!-- Authorization logic method handleRequest/handleResponse  values 
request/response-->

		<handlermethod method="request"> </handlermethod>    	

    </jax-rpc-webservice-config>

Step 4 Deploy the CalculatorService.ear file in the Websphere application server.

Step 5 Start the Websphere application server.

Step 6 Use WSDL Resource Discovery to create WebService resources in CEPM UI.

a. Login to CEPM and navigate to Home > Manage Entities > Resources.

b. Under the configured application, click Create Resources from External Sources.

c. Select Source Type as wsdl.

d. Select URL/FileName Type as URL.

e. Enter the value for wsdl running in URL. For example, http://host:port/CalculatorService/services/Calculator?wsdl.

f. Click Create.

g. Select all the Operation Name and Click on Create. It will create all the resources under the specified application.

Step 7 Create a user called `WAS_USER' under Prime group: Calculator App and assign the policies as shown in Figure 2

Figure 2 User based policy creation.

Step 8 Run the Calculator client application. http://host:port/CalculatorServiceClient

Figure 3 Calculator Service.

Step 9 Based on the permissions specified in 'CEPM', 'WAS-USER' is served with the requested resource or recieves a SOAPFaultException message like 'WAS-USER Not authorized to invoke this service'.

Figure 4 Access the caliculator features based on the CEPM permissions

Step 10 Perform a Multiply operation.

Figure 5 Perform Multiply Operation

.

`WAS_USER' now has an allow policy for Multiply associated with the user profile, and is served with the Multiply operation.

Figure 6 Result of the Multiply operation

Decision for user [WAS_USER] for Resource [Prime group:Prime portal:CalculatorService] and action [mul] with environment map [{b=5, a=5}] is [true].

Step 11 Perform an Add operation.

Figure 7 Perform Add Operation

`WAS_USER' now has a deny policy for Add, the user will not be served with the Add operation.

Figure 8 Service throwing an exception

The service throws an exception message like javax.xml.rpc.soap.SOAPFaultException: WAS_USER Not authorized to invoke this service.

Documentation Updates

Table 1 Updates to CEPM JAX-RPC Agent for WebSphere Guide

Date
Description

July 7, 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.

[an error occurred while processing this directive]