Cisco Policy Enforcement Point

Table Of Contents

CEPM XMLAccess Agent Guide

Contents

About This Document

Objective

Audience

Introduction

Functional Aspects of XMLAccess Agent

Deploying the XMLAccess Agent

Sample Application Implementation

Documentation Updates

Related Documentation

Obtaining Documentation and Submitting a Service Request

CEPM XMLAccess Agent Guide

---

Revised: August 6, 2009, Doc Part No: OL-19574-01

Contents

•About This Document

•Introduction

•Functional Aspects of XMLAccess Agent

•Deploying the XMLAccess Agent

•Sample Application Implementation

•Documentation Updates

•Related Documentation

•Obtaining Documentation and Submitting a Service Request

About This Document

Objective

This document gives the overview of the XMLAccess Agent and explains the functional aspects of the agent with a sample application implementation.

Audience

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

Introduction

The access control is one of the fundamental security mechanisms in information systems. You need access control when a multiuser system offers selective access to shared information. CEPM XMLAccess Agent is used to limit the access of portal resources (portlets) running under WebSphere Portal Server (WPS) to only authorized users and roles.

Functional Aspects of XMLAccess Agent

WebSphere authorization providers are modules that plug into a WPS security realm to provide security services to applications. The provider determines whether access should be granted or denied to WebSphere Server portal resources.

You can supplement or replace the WPS authorization providers with custom security providers. The XMLAccess Agent is a custom authorization provider for WPS. The XMLAccess Agent can be used for fine-grained access control to the WPS resources like portlets.

Figure 1 XML Access Agent-Functional Flow

This figure illustrates the following sequence of events:

1. The required entities (users, roles, and resources) of the portal application are created in the Policy Administration Point (PAP) console using the ResourceDiscovery feature of the Cisco Entitlement Policy Manager (CEPM).

2. Necessary mappings, such as user-to-resource and role-to-resource are done in the PAP. The XMLAccess agent updates these entitlement policies in the corresponding portal resources. Currently, this agent can be used for user-based and resource-based policies. If you belong to group-based entitlement, you can map a user to a group and then the same group to a role that is mapped to the appropriate resource.

3. Agent invokes the handler corresponding to the entitlement. For example, the agent invokes ResourcePolicy handler for the resource-based entitlement and the UserPolicy handler for the user-based entitlement.

4. The respective handler generates an xml script using the ScriptGeneretor.jar file.

5. This dynamically invokes the xmlaccess.bat file in the WPS, which updates the policy settings in the corresponding WPS resources.

Deploying the XMLAccess Agent

To deploy the XMLAccess Agent, follow these steps:

---

Step 1 Copy CEPM_XMLAccessAgentv3.3.0.0.zip file to your local machine and unzip it. The directory where Cepm_XMLAccessAgent.zip is unzipped will be referred to as <XMLAccess_Home>. Verify that the zip file contains the following files:

•Cisco_rapi.jar

•papclient.jar

•CEPM_commons.jar

•pep_config.xml

•runresourcediscoverywps.bat

•runresourcediscoverywps.sh

•scriptgenerator.jar

•XMLAccess_readme.txt and config folder

Step 2 Configure Handler in CEPM. To do this:

a. Copy the scriptgenerator.jar file from XMLAccess_Home to the ..\cepm\WEB-INF\lib folder.

b. Edit the pap_config.xml file from the <CEPM_HOME>\config folder to configure the handler as shown in the following sample <handler> tag:

<!-- UserBased/By User -->

	<handler name="UserResourceMapping" enabled="true" type="UserResourceMapping">

			<impl>com.cisco.epm.agent.wps.handler.ScriptGenerator</impl>

	       		<properties>

	            	<location>C:\portalaccess</location>

	            	<user>wpadmin</user>

	            	<pwd>wpadmin</pwd>

	            	<url>http://hostname:port/wps/config</url>

	            	<poolName>Default Domain</poolName>

	            	<xmlaccess>C:/xmlaccess.bat</xmlaccess>            

		       </properties>

	</handler>

	<!-- RoleBased/By Role -->

	<handler name="RoleResourceMapping" enabled="true" type="RoleResourceMapping">

		<impl>com.cisco.epm.agent.wps.handler.ScriptGenerator</impl>

		       <properties>

		            <location>C:\portalaccess</location>

		            <user>wpadmin</user>

		            <pwd>wpadmin</pwd>

		            <url>http://hostname:port/wps/config</url>

		            <poolName>Default Domain</poolName>

		            <xmlaccess>C:/xmlaccess.bat</xmlaccess>            

		       </properties>

	</handler>

	<!-- GroupBased/By Group -->

	<handler name="GroupResourceMapping" enabled="true" type="GroupResourceMapping">

		<impl>com.cisco.epm.agent.wps.handler.ScriptGenerator</impl>

		       <properties>

		            <location>C:\portalaccess</location>

		            <user>wpadmin</user>

		            <pwd>wpadmin</pwd>

		            <url>http://hostname:port/wps/config</url>

		            <poolName>Default Domain</poolName>

		            <xmlaccess>C:/xmlaccess.bat</xmlaccess>            

		       </properties>

	</handler>

	<!-- ResourceBased/By Resource -->

	<handler name="PolicyHandler" enabled="true" type="PolicyHandler">

		<impl>com.cisco.epm.agent.wps.handler.ScriptGenerator</impl>

		       <properties>

		            <location>C:\portalaccess</location>

		            <user>wpadmin</user>

		            <pwd>wpadmin</pwd>

		            <url>http://hostname:port/wps/config</url>

		            <poolName>Default Domain</poolName>

		            <xmlaccess>C:/xmlaccess.bat</xmlaccess>            

		       </properties>

	</handler>

Where,

The <handler> tag provides the name and type of the handler to be invoked after performing the action. Currently CEPM uses four handlers as given below:

–PolicyMapping handler—This handler is invoked when a resource based entitlement is defined in the PAP. This handler is also used when role-based policies are created.

–UserResourceMapping handler—This handler is invoked when a user-based entitlement (user-to-resource mapping) is defined in the PAP.

–RoleResourceMapping Handler—This handler is invoked when a role-based entitlement is defined in the PAP.

–GroupResourceMapping Handler—This handler is invoked when a group-based entitlement (group-to-resource mapping) is defined in the PAP.

The <impl> tag carries the implementation class details.

The <properties> tag provides following attribute settings:

–<location> attribute refers to the folder path where you store the xml files that are generated after executing the xmlaccess.bat file.

–<user> and <pwd> refer to the WebSphere portal server administrator credentials.

–<url> refers to the URL of the machine where the WebSphere portal is installed.

–<poolName> refers to the repository name where the portal entities are created in the PAP.

–<xmlaccess> refers to the absolute path of xmlaccess.bat/xmlaccess.sh. Refer Step 5.

Step 3 Start the application server on which CEPM is deployed.

Step 4 Create resources in CEPM using the runresourcediscoverywps.bat file located at XMLAccess_Home\. To do this:

a. Start the WPS server.

b. Login to Portal administration console using the administrator user ID and password.

c. Choose Administration > WebSphere Portal > Portal User Interface > Manage Pages and click the export button located against the contextRoot. Export the xml file and save the file, for example, as pageExportContextRoot.xml in the ...\XMLAccess_Home folder.

---

Note You must mention the same file name while creating the resource using the runresourcediscoverywps.bat file.

---

d. Open the pep_config.xml file and update the following tags:

–<application group>—Name of the application group to be created in the PAP console.

–<application>—Name of the application to be created in the PAP console.

–<API>—Details such as URL, user ID, and password of the machine where PAP is running.

e. Login to the PAP console and create the application group and application that are mentioned in the pep_config.xml file.

f. Edit the runresourcediscoverywps.bat file located at XMLAccess_Home\ in the following manner:

–Place the scriptgenerator.jar, papclient.jar, CEPM_Commons.jar, and Cisco_rapi.jar files in the classpath.

–Set the properties CEPM_AGENT_CONFIG and log4j.configuration to read the pep_config.xml and logging.xml file in runresourcediscoverywps.bat file.

-DCEPM_AGENT_CONFIG=<XMLAccess_Home>\config\pep\pep_config.xml 
-Dlog4j.configuration=<XMLAccess_Home>\config\logging\logging.xml

g. Run the runresourcediscoverywps.bat file located at XMLAccess_Home\ from the command prompt with input argument pageExportContextRoot.xml. For example:

runresourcediscoverywps.bat D:\XMLAccess_Home\pageExportContextRoot.xml

This creates all the resources of the WPS portal application in the PAP console.

Step 5 Copy the xmlaccess.bat and wp.xml.client.jar files from the WPSINSTALLED_HOME\PE\PortalServer\bin folder and copy the wp.base.jar file from the WPSINSTALLED_HOME\PE\PortalServer\shared\app folder to the ...\XMLAccess_Home folder.

Step 6 Create a folder called "portalaccess" in the same location as you have mentioned in the handler property tag. (Refer to Step 2b.)

Step 7 Start the WPS and log in to the administrator console with administrator privileges.

Step 8 Choose Administration > WebSphere Portal > Access > Users and Groups and create the following entities:

•Create usergroups.

•Create users and add them to the newly created usergroups. Make sure that these usergroups do not have common users.

Step 9 Go to PAP console and create the following entities:

•Create the same users and usergroups as created in the WPS.

•Do the user-to-group mapping in the same order as done in the WPS.

•Create roles. For example, Role1 and Role2.

•Do the required group-to-role mapping.

Step 10 Remove defaoult resource permissions of the portlets. To do this:

•Login to portal server with administration privilege

•Choose Administration > WebSphere Portal > Portlet Management > Portlets and enter your search terms.

•Choose your portlet from the search outcomes and click the assign access to the portlet icon. This opens the Resource Permissions page for the selected portlet. Uncheck all permission check boxes. Follow the same procedure for all portlets.

Step 11 In PAP console, choose Home > Manage Entitlements > Resource Based and create the necessary policies for the roles on the portlet resources. The corresponding user would access only those resources as per the policy configuration. You can also set a deny policy for a role on any resource that has an allow policy for the same role. Deleting the existing policy will achieve this.

---

Sample Application Implementation

Consider the following WebSphere Portal on which the XMLAccess Agent is applied. Here the user is allowed to access all the resources using the WPS access control.

Figure 2 WebSphere Portal

Using the resource discovery feature, the following resources are created in the PAP console. In this example, the Sample application is created under the Prime group.

Figure 3 Resource Home Page

On the Home > Manage Entities > Add Users to Group page, the user Johny is mapped to the Sample Group.

Figure 4 Add Users to Group.

On the Home > Manage Entities > Add Groups to Roles page, the Sample Group is mapped to the Guest role.

Figure 5

Add Groups to Roles

On the Home > Manage Entitlements > By Resource page, see an Allow:Guest entry on the Sample application.

Figure 6 Configuring Allow policy on Sample Application

When a policy is mapped the handler generates an XML script similar to the one shown here:

<?xml version="1.0" encoding="UTF-8"?>

<request   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd" type="update"  create-oids="true">

<Portal action="locate">

       <web-app action="locate"

       uid="com.screamingmedia.openportlet.wps.WSPortlet.release.Dazzle3">

           <portlet-app action="locate"

	   uid="com.screamingmedia.openportlet.wps.WSPortlet.release.Dazzle3.concrete">

	   <access-control>

	       <roll-block type="propagation" actionset="user"/>

	   </access-control>

      <Portlet action="update" active="true" name="My Vertical News">

	   <access-control>

	       <roll actionset="user" update="set"/>

	           <mapping subjectid="cn=samplegroup,o=default organization"

		   subjecttype="USER_GROUP" update="set">

	       </role>

	   </access-control>

</portlet>

</portlet-app>

</web-app>

</protal>

</request>

This script provides a unique ID to the entitled resource to avoid any conflict that may arise due to a duplicate resource. When the xmlaccess.bat file is run, the XMLAccess Agent updates the resource in the WPS, which allows the user Johny to access the specified resource.

Now a deny policy is created for the Guest role, of which Johny is a member, shown here:

Figure 7 Deny Policy

As a result of this mapping, when Johny logs in again to the application, he cannot view the denied resource as shown here:

Figure 8 Mapping on Sample Application

In this way, you can use the XMLAccess Agent to control the access of the WPS resources.

Documentation Updates

Table 1 Updates to CEPM XMLAccess 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, CCENT, CCSI, Cisco Eos, Cisco HealthPresence, Cisco IronPort, the Cisco logo, Cisco Lumin, Cisco Nexus, Cisco Nurse Connect, Cisco StackPower, Cisco StadiumVision, Cisco TelePresence, Cisco Unified Computing System, Cisco WebEx, DCE, Flip Channels, Flip for Good, Flip Mino, Flip Video, Flip Video (Design), Flipshare (Design), Flip Ultra, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn, Cisco Store, and Flip Gift Card 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. (0907R)

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.