Cisco Policy Enforcement Point

Table Of Contents

CEPM JACC WAS Agent Guide

Contents

About This Document

Objective

Audience

Introduction

CEPM JACC Agent Approach to Protect WebSphere Server Applications

Integrating CEPM JACC Agent with WebSphere Application Server

Integrating CEPM In-Process PDP JACC WAS Agent

Examples of JACC Agent Authorization Process

Protecting Web Resources in the WebSphere Application Server Application

Protecting EJB Resources in WebSphere Application Server Application

Documentation Updates

Related Documentation

Obtaining Documentation and Submitting a Service Request

CEPM JACC WAS Agent Guide

---

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

Contents

•About This Document

•Introduction

•CEPM JACC Agent Approach to Protect WebSphere Server Applications

•Integrating CEPM JACC Agent with WebSphere Application Server

•Integrating CEPM In-Process PDP JACC WAS Agent

•Examples of JACC Agent Authorization Process

•Documentation Updates

•Related Documentation

•Obtaining Documentation and Submitting a Service Request

About This Document

Objective

This document explains about how the Cisco JACC Agent for WebSphere Application Server helps in implementing the fine-grained authorization decisions for web applications developed using WebSphere Application Server.

Audience

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

Introduction

JACC Agent is developed using Sun Microsystem's Java Authorization Contract for Containers (JACC) specification that is part of Java 2 Platform, Enterprise Edition (J2EE) 1.4. JACC defines a contract between J2EE containers and authorization providers. The contract enables third-party authorization providers (like Cisco Enterprise Policy Manager JACC Agent) to plug into J2EE application servers, such as the WebSphere Application Server, to make the authorization decisions when a J2EE resource is accessed. The access decisions are made through the standard java.security.Policy object. CEPM JACC Agent implements the policy class, policy configuration factory class, and policy configuration interface, as per the J2EE JACC specification.

More information about the J2EE JACC specification can be found at: http://java.sun.com/j2ee/javaacc/index.html

CEPM JACC Agent Approach to Protect WebSphere Server Applications

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

If the WebSphere Server product does not fully meet your security requirements, you can supplement or replace them with custom security providers. CEPM JACC Agent is a custom authorization provider for WebSphere Application Server. The JACC Agent can be used for protecting WebSphere Application Server resources like Enterprise JavaBeans (EJBs), Servlets, JavaServer Pages (JSPs), and WebServices.

Figure 1 CEPM JACC-WAS Agent Deployment Diagram

The process shown in Figure 1WebSphere Process is carried out in the following manner:

1. Users that access protected resources are authorized using CEPM JACC Provider.

2. The WebSphere Application Server container uses information from the J2EE application deployment descriptor to determine the required role membership.

3. WebSphere Application Server uses the embedded CEPM JACC Provider to request an authorization decision from the Policy Decision Point (PDP) Server. Additional context information, when present, is also passed to the PDP. This context information is comprised of the J2EE application name and J2EE module name. If the PDP database has policies that are specified for any of the context information, the authorization server uses this information to make the authorization decision.

4. The authorization server consults the permissions that are defined for the specified user within the PDP database.

5. The PDP returns the access decision to the embedded CEPM JACC Provider.

6. WebSphere Application Server either grants or denies access to the protected method or resource, based on the decision that is returned from the PDP.

CEPM JACC Provider also provides centralized administration of multiple servers.

Figure 2 CEPM JACC Provider

Figure 2CEPM JACC Provider is a sample architecture showing WebSphere Application Servers secured by CEPM JACC Provider.

The participating WebSphere Application Servers use the PDP to make authorization decisions for incoming requests.

CEPM JACC Agent authorization process is carried out in the following manner:

Figure 3 CEPM JACC Agent Authorization Process

1. A user sends a request to the WebSphere container to access a WebSphere resource for performing a given operation.

2. The WebSphere container receives the request and invokes the method implies(protectiondomain, permission) on CEPM JACC Provider.

3. CEPM JACC Provider extracts the subject (that is, username) from "ProtectionDomain" and the requested resource from the "Permission" object and in turn calls the method isUserAccessAllowed(subject,resource,action) on the Policy Enforcement Point (PEP).

4. The PEP makes API call to the PDP by constructing a XacmlRequest using the subject, resource, and action. The API method that is called is isUserAccessAllowed(XacmlRequest).

5. The isUserAccessAllowed(XacmlRequest) method returns one of the following two boolean values to the implies() method:

TRUE—indicates that the requested access is permitted

FALSE—indicates that the requested access is explicitly denied

6. If the implies() method returns true, the requested operation is processed by the WebSphere container.

Integrating CEPM JACC Agent with WebSphere Application Server

To integrate CEPM JACC Agent with the WebSphere Application Server, follow these steps.

---

Step 1 Unzip the JACC_WAS.zip. The directory where the JACC_WAS.zip file is unzipped will be referred to as <JACC_HOME> directory.

Step 2 Copy cepmjaccagent.jar, pep.jar, CEPM_Commons.jar and papclient_classes.jar files to the WebSphere\AppServer\lib\ directory.

Step 3 Edit the pep_config.xml file.

a. Provide PDP configuration details.

b. Edit the <jacc-config> tag and set the values for application group and application to be protected.

–Edit the <app-group name="Prime group"> tag with the required application group.

–Edit the <web-application name="JACCEJBDEMO"> tag with the required application to be protected.

c. Edit the <websphere-resource> tag for protecting web resources such as jsps, servlets, and actions. Set the value as webapp and set attribute enableaction=true. This setting protects all web resources and actions. (If the enableaction attribute is set to false, then the web resources in the application will not be protected.)

d. You can also edit <websphere-resource> tag for protecting EJB resources such as ejb beans and ejb method. Set the value as ejb and set attribute enableaction=true. This setting will protect all EJB resources. (If set to false, the EJB resources in the application will not be protected.)

e. Edit the <subject source="session"> tag. You can set its value to either session or request. (Source should be the place from where the user is to be recognized. For example: Session,request)

f. Edit the <attributename="userName"> tag to use the attribute key name in the session or request.

Step 4 Start the WebSphere Application server.

Step 5 Open the WebSphere Server console (for example, http://IPAdrress:Port/ibm/console).

Step 6 From the WebSphere Application Server administrative console, choose Security > Secure administration, applications, and infrastructure.

Step 7 Click the External Authorization Providers link.

Step 8 Click the External JACC Provider link.

Step 9 Set the following fields with these values:

•Name = CEPM JACC Authorizer

•Description = CEPM

•Policy class name = com.cisco.epm.agent.jacc.websphere.CepmPolicy

•Policy configuration factory class name = com.cisco.epm.agent.jacc.websphere.CepmPolicyFactory

•Role configuration factory class name = [blank]

•Provider initialization class name = [blank]

Step 10 Click Apply and then click Save (at the top of the screen).

Step 11 Click the External Authorization using a JACC Provider radio button.

Step 12 Click Apply and then click Save (at the top of the screen).

Step 13 Under Application Security, check the Enable Application Security check box.

Step 14 Under Application Security, check the Enable Administrative Security check box.

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

Application and application group mentioned in the pep_config.xml file should be created in Policy Administration Point (PAP). The links under application and application group need to be created as resources.

---

Note In the pep_config.xml file, if the <record> tag is true, the PAP automatically creates resources while you are accessing particular page or action in the WebSphere application that is protected by Cisco Enterprise Policy Manager (CEPM). If the <record> tag is set to false, then you need to create resources manually in the PAP console.

---

Step 16 Create the following environment variables:

a. Go to the WebSphere administration console

b. Choose Application servers > <server name> > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine > Custom Properties.

c. Click New.

d. Enter the following environment variables:

–CEPM_AGENT_CONFIG—his variable is set to locate the pep_config.xml file. You must set this variable because it detects the agent configuration file. For example:

Name=CEPM_AGENT_CONFIG

Value=<CEPM_JACC_HOME>\pep_config.xml

–CEPM_DECISION_CACHE_CONFIG—This variable is set to locate the jbosscache.xml files. For example:

Name=CEPM_DECISION_CACHE_CONFIG

Value=<CEPM_JACC_HOME>/config/jbosscache/jbosscache.xml

This variable is set only when the <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=<JACC_HOME>\config\logging\logging.xml

–Click Apply and click Save.

---

Integrating CEPM In-Process PDP JACC WAS Agent

In-process PDP is used as an alternative for PDP in case of static applications. In this case there is no pep_config.xml file. The necessary agent tag (the <jacc-agent-config> tag) is accommodated in the pdp_config.xml file.

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

---

Step 1 Unzip the JACCWASAgentV3.3.0.0_InProcessPDP.zip file to your local machine.

The unzipped folder will be your <CEPM_JACC_HOME>.

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

Step 3 Open the configure.properties file from <CEPM_JACC_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 defaults 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 configured in encrypted format in configuration files. To get an encrypted password, run the encryptor.bat(sh) file from the <CEPM_JACC_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 chosen database password. When this command is executed, an encrypted password is displayed. You must copy this encrypted password in the Password parameter of the database properties in the configure.properties file.

---

Step 4 Run configure.bat(sh) file from the <CEPM_JACC_HOME>/bin folder to configure the in-process PDP. This generates a specific <jacc-agent-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 <CEPM_JACC_HOME>/bin folder.

The remaining steps of integrating the JACC Agent with in-process PDP are the same steps to integrate the JACC Agent in web application.

---

Examples of JACC Agent Authorization Process

This section provides examples of customized JACC Agent authorization processes.

Protecting Web Resources in the WebSphere Application Server Application

This example describes how JACC Agent for WebSphere protects web resources such as JSPs, servlets, HTML files, and CSS files.

---

Step 1 Log in to the sample application running on the WebSphere Application Server. The user name entered in the login page is taken as the subject in the authorization request.

The sample WebSphere application contains the following two resources that need protection:

•images

•GalleryMenu JSP

Step 2 Assume that necessary arrangements are made in the administration console by creating a resource hierarchy for the sample application that use images and GalleryMenu JSP as resources.

Configure the entitlement policies for the images and GalleryMenu JSP resources by defining allow policies on them for the External Users role from the resource-based entitlement screen in the PAP console

Figure 4 Resource Based Entitlement.

Because of these settings in PAP console, the sample application shows the two resources, images and GalleryMenu JSP.

Figure 5 Gallery Menu

Step 3 Set a deny policy on the two resources, images and GalleryMenu JSP, for the External Users role in the resource-based entitlement screen in the PAP console.

Figure 6 Deny Policy-Resource Baesd Entitlement

This setting makes the two resources, images and GalleryMenu JSP, unavailable in the sample WebSphere application

Figure 7 .

Resources unavailable in sample WebSphere Application

Protecting EJB Resources in WebSphere Application Server Application

This example describes how CEPM JACC Agent for WebSphere protects EJB resources.

---

Step 1 Deploy EJB application, EjbClient, in the WebSphere application server.

Step 2 In the PAP console, create the EjbClient_war application under Prime Group.

Step 3 In the pep_config.xml file, set these values:

<websphere-resource type="ejb" enableaction="true">*</websphere-resource>

<record>true</record>

Step 4 Access the EJB application that is deployed in the WebSphere Application Server.

In the PAP, the EJB resources will now get created under the Ejbclient_war application.

Figure 8 Resource Hierarchy

Here, the resource hierarchy shows the servlets and EJB methods present in the deployed WAR file. The EJB class name is HelloBean and it has three user defined methods: sayHello, sayHai, and sayByee.

Step 5 Set an allow policy for the External Users role for the EjbClient_war application

Figure 9 Allow Policy for External Users.

Step 6 Access the EJB application that is deployed in the WebSphere Application Server. The browser displays the following information.

Figure 10 EJB Information

Step 7 In the PAP console, set a deny policy for the two EJB method resources, HelloBean sayHello and HelloBean sayHai, for the External Users role for the EjbClient_war application

Figure 11 .Deny Poilcy-EJB method resources

Step 8 Access the EJB application that is deployed in the WebSphere Application Server.

The browser displays the following information

Figure 12 EJB deployed in WebSphere Application Server.

---

Documentation Updates

Table 1 Updates to CEPM JACC WAS 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.