2976N/A

3824N/A------------------------------------

2976N/AJ2EE Policy Agent Sample Application

2976N/A------------------------------------

2976N/A

2976N/AThis document describes how to use the agent sample application in conjunction

2976N/Awith the Weblogic 10 Application Server and the J2EE Agent. Please note that

2976N/Athe agent needs to be installed first before deploying this sample application.

2976N/A

2976N/A * Overview

6238N/A * Configure the OpenAM server

2976N/A * Configure the agent properties

2976N/A * Deploying the Sample Application

2976N/A * Running the Sample Application

2976N/A * Troubleshooting

3824N/A * Optional Steps

3824N/A ** Compiling and Assembling the Application

3824N/A

3824N/A

3824N/AOverview

5728N/A--------

3842N/AThe sample application is a collection of servlets, JSPs and EJB's that

3842N/Ademonstrate the salient features of the J2EE policy Agent. These features

3824N/Ainclude SSO, web-tier declarative security, programmatic security, URL policy

3842N/Aevaluation and session/policy/profile attribute fetch. The web.xml deployment

2976N/Adescriptor has already been edited to include the Agent Filter. The

2976N/Adeployment descriptors and source code are available in the sampleapp/src

2976N/Adirectory.

6238N/A

6251N/AThe sample application is supported for Policy Agent 3.0.

6251N/A

6251N/AThe application is already built and ready to be deployed. It is available at

6251N/Asampleapp/dist/agentsample.ear.

6258N/A

4287N/ANote, the instructions here assume that you have installed the agent

3824N/Asuccessfully and have followed the steps outlined in the OpenAM

6251N/APolicy Agent 3.0 Guide for BEA WebLogic Server/Portal 10.0, including the

6251N/Apost-installation steps.

3824N/A

2976N/A

2976N/A

2976N/A

2976N/AConfigure the OpenAM server

2976N/A----------------------------------------------

2976N/AThis agent sample application requires that the OpenAM server is configured

2976N/Awith the subjects and policies required by the sample application.

6238N/A

2976N/AOn OpenAM admin console, do the following configuration.

2976N/A1. Create the following users:

2976N/A Here is the following list of users with username/password :

2976N/A

2976N/A * andy/andy

2976N/A * bob/bob

2976N/A * chris/chris

2976N/A * dave/dave

2976N/A * ellen/ellen

6238N/A * frank/frank

5022N/A * gina/gina

3824N/A

5636N/A

2976N/A2. Assign Users to Groups

2976N/A Create new groups for employee, manager, everyone, and customer. Then assign

2976N/A the users to the groups as follows:

2976N/A

5022N/A * employee:

5636N/A o andy, bob, chris, dave, ellen, frank

5636N/A * manager:

5636N/A o andy, bob, chris

5636N/A * everyone:

5636N/A o andy, bob, chris, dave, ellen, frank, gina

5636N/A * customer:

5636N/A o chris, ellen

5636N/A

2976N/A3. Create the following URL Policies:

2976N/A In the following URLs, replace the <hostname> and <port> with the

5636N/A actual fully qualified host name and port on which the sample

5636N/A application will be running.

5636N/A

5636N/A * Policy 1:

5636N/A o allow:

5636N/A + http://<hostname>:<port>/agentsample/jsp/*

5636N/A + http://<hostname>:<port>/agentsample/invokerservlet

5636N/A + http://<hostname>:<port>/agentsample/protectedservlet

4915N/A + http://<hostname>:<port>/agentsample/securityawareservlet

4915N/A + http://<hostname>:<port>/agentsample/unprotectedservlet

5636N/A o Subject: all authenticated users.

2976N/A * Policy 2:

2976N/A o allow:

4915N/A + http://<hostname>:<port>/agentsample/urlpolicyservlet

4915N/A o Subject: Group: customer

4915N/A

5636N/A

4915N/A

4915N/A

2976N/AConfigure the agent properties

2976N/A--------------------------------------------

2976N/A

5636N/A If the agent configuration is centralized, then do the following steps.

2976N/A 1). login to OpenAM console as amadmin user

2976N/A 2). navigate to Access Control/realm/Agents/J2EE, and click on the agent

2976N/A instance link (assume the agent instance is already created, otherwise

4915N/A refer to the agent doc to create the agent instance).

2976N/A 3). in tab "Application", section "Access Denied URI Processing", property

5636N/A "Resource Access Denied URI", enter agentsample in the Map Key field,

2976N/A /agentsample/authentication/accessdenied.html in the Map Value field, and

2976N/A SAVE the change.

2976N/A 4). in tab "Application", section "Login Processing", property "Login Form URI",

4261N/A add /agentsample/authentication/login.html, and SAVE the change.

5224N/A 5). in tab "Application", section "Not Enforced URI Processing", property

2976N/A "Not Enforced URIs", add the following entries:

2976N/A /agentsample/public/*

5636N/A /agentsample/images/*

5218N/A /agentsample/styles/*

4261N/A /agentsample/index.html

2976N/A /agentsample

4261N/A and SAVE the change.

4261N/A 6). in tab "Application", section "Privilege Attributes Processing", property

2976N/A "Privileged Attribute Mapping",

3824N/A add the following entries:

2976N/A a) add the UUID of group employee in the Map Key field of the UI

2976N/A add am_employee_role in the Corresponding Map Value field of the UI

2976N/A and click the Add button.

2976N/A b) add the UUID of group manager in the Map Key field of the UI

6238N/A add am_manager_role in the Corresponding Map Value field of the UI

3007N/A and click the Add button.

2976N/A c) then SAVE the change.

2976N/A Note you can find the UUID (Universal User ID) of the groups employee

2976N/A and manager from the OpenAM console group page.

2976N/A For example, if the UUID of employee is id=employee,ou=group,dc=opensso,dc=java,dc=net

2976N/A and the UUID of manager is id=manager,ou=group,dc=opensso,dc=java,dc=net

5636N/A then you need to add the following entries in the "Privileged Attribute Mapping".

5636N/A a) add id=employee,ou=group,dc=opensso,dc=java,dc=net in the Map Key

5636N/A field of the UI.

3449N/A add am_employee_role in the Corresponding Map Value field of the UI

3449N/A and click the Add button.

3449N/A b) add id=manager,ou=group,dc=opensso,dc=java,dc=net in the Map Key

6238N/A field of the UI.

2976N/A add am_manager_role in the Corresponding Map Value field of the UI

5636N/A and click the Add button.

5636N/A

5636N/A

5636N/A If the agent configuration is local, then edit the local agent configuration

5636N/A file OpenSSOAgentConfiguration.properties located at the directory

2976N/A <agent_install_root>/Agent_<instance_number>/config with following changes:

5636N/A

2976N/A * Not enforced List:

4261N/A com.sun.identity.agents.config.notenforced.uri[0] = /agentsample/public/*

5636N/A com.sun.identity.agents.config.notenforced.uri[1] = /agentsample/images/*

5224N/A com.sun.identity.agents.config.notenforced.uri[2] = /agentsample/styles/*

2976N/A com.sun.identity.agents.config.notenforced.uri[3] = /agentsample/index.html

2976N/A com.sun.identity.agents.config.notenforced.uri[4] = /agentsample

5636N/A

5218N/A * Access Denied URI:

4261N/A com.sun.identity.agents.config.access.denied.uri[agentsample] = /agentsample/authentication/accessdenied.html

2976N/A * Form List:

4261N/A com.sun.identity.agents.config.login.form[0] = /agentsample/authentication/login.html

4261N/A

2976N/A * Privileged Attribute Mapping:

3824N/A com.sun.identity.agents.config.privileged.attribute.mapping[id\=employee,ou\=group,dc\=opensso,dc\=java,dc\=net] = am_employee_role.

2976N/A com.sun.identity.agents.config.privileged.attribute.mapping[id\=manager,ou\=group,dc\=opensso,dc\=java,dc\=net] = am_manager_role.

2976N/A Note the above settings assume the UUIDs of group employee and manager are

2976N/A "id=employee,ou=group,dc=opensso,dc=java,dc=net" and

3449N/A "id=manager,ou=group,dc=opensso,dc=java,dc=net" respectively. Change to

5218N/A the appropriate UUIDs accordingly.

3449N/A

5636N/A

3449N/A

3449N/A Optionally, you can try out the fetch mode features that allow the agent to

3449N/A fetch some values and make them available to your application. For example,

2976N/A you can fetch user profile values(like email or full name) from the user data

4261N/A store of your OpenAM setup and make them available to your application code

5636N/A (through cookies, headers, or request attributes) for application

4261N/A customization. See the Policy Agent 3.0 for details about the fetching

5636N/A attributes for details on using this feature. If you change the agent's

5224N/A configuartion for the attribute fetching, the showHttpHeaders.jsp page of the

2976N/A sample application will show all the attributes being fetched. You can choose

2976N/A to try this later after you have already installed and deployed the agent and

5636N/A sample application in order to learn about this feature.

5218N/A

4261N/ADeploying the Sample Application

2976N/A--------------------------------

4261N/ANote, before deploying the sample application, please be sure that you have

4261N/Adeployed the Agent Application, which should have been done after installing

2976N/Athe agent. This is explained in the OpenAM Policy Agent 3.0 Guide for

3824N/ABEA WebLogic Server/Portal 10.0 in the chapter which

2976N/Aoutlined the post-installation tasks.

2976N/A

2976N/ATo deploy the application, do the following:

2976N/A

2976N/AGo to BEA WebLogic server console and deploy the sample application.

Running the Sample Application

----------------------------

You can run the application through the following URL:

http://<hostname>:<port>/agentsample

Traverse the various links to understand each agent feature.

Troubleshooting

----------------------------

If you encounter problems when running the application, review the log files to

learn what exactly went wrong. J2EE Agent logs can be found at

<agent_install_root>/Agent_<instance_number>/logs/debug directory.

Also, see the OpenAM Policy Agent 3.0 Guide for BEA WebLogic

Server/Portal 10.0.

Optional Steps

----------------------------

Compiling and Assembling the Application (Optional)

---------------------------------------------------

The application is already built and ready to be deployed, so you could skip

this section. If you want to change something or get familiar with the build

details, then this section is useful.

This section contains instructions to build and assemble the sample application

using a Command Line Interface (CLI).

To rebuild the entire application from scratch, follow these steps:

1. This requires that you have downloaded and installed Apache Ant, at least

Ant version 1.6.5. Also be sure to have ant/bin in your path.

1. Set your JAVA_HOME to include JDK1.5 or above. Also, include the

JAVA_HOME/bin directory in your path.

2. Replace 'APPSERV_LIB_DIR' in build.xml with the directory where

weblogic.jar and api.jar are located.

For Example: Replace APPSERV_LIB_DIR with

/usr/local/bea/wlserver_10.0/server/lib where /usr/local/bea is

where you installed WebLogic BEA 10

3. Compile and assemble the application.

For example: execute the command ant

under <agent_install_root>/sampleapp/ to execute the default target build

and rebuild the EAR file.

The build target creates a built and dist directory with the EAR file.

Note that you can also run 'ant rebuild' to clean the application project

area and run a new build.

Now you are ready to use the dist/agentsample.ear file for deployment.