<!--
    Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved
    Use is subject to license terms.
-->

------------------------------------
J2EE Policy Agent Sample Application
------------------------------------

This document describes how to use the agent sample application in conjunction 
with the Application Server.

    * Overview
    * Configure the Access Manager server
    * Configure the agent AMAgent.properties file
    * Deploying the Sample Application
    * Running the Sample Application
    * Troubleshooting
    * Optional Steps
    ** Compiling and Assembling the Application


Overview
--------
The sample application is a collection of servlets, JSPs and EJB's that 
demonstrate the salient features of the J2EE policy Agent. These features 
include SSO, web-tier declarative security, programmatic security, URL policy 
evaluation and session/policy/profile attribute fetch. The web.xml deployment
descriptor has already been edited to include the Agent Filter. The 
deployment descriptors and source code are available in the sampleapp/src 
directory.

The sample application is supported for Policy Agent 2.2.

The application is already built and ready to be deployed. It is available at
sampleapp/dist/agentsample.ear.

Note, the instructions here assume that you have installed the agent 
successfully and have followed the steps outlined in the Sun Java System 
Access Manager Policy Agent 2.2 Guide for BEA WebLogic Server/Portal 10.0, 
including the post-installation steps.


Configure the Access Manager server
----------------------------
This agent sample application requires that the Access Manager server is
configured with the subjects and policies required by the sample application.

1. Create the following users:
    Here is the following list of users with username/password :

    * andy/andy
    * bob/bob
    * chris/chris
    * dave/dave
    * ellen/ellen
    * frank/frank
    * gina/gina


2. Assign Users to Roles
   Create new roles for employee, manager, and everyone. Then assign the 
   users to the roles as follows:

    * employee:
          o andy, bob, chris, dave, ellen, frank
    * manager:
          o andy, bob, chris
    * everyone:
          o andy, bob, chris, dave, ellen, frank, gina

3. Group Setup:
   Create a new group called customer and then assign users to 
   that group as follows:

    * customer:
          o chris, ellen
    
4. On Access Manager admin console, create the following URL Policies:
   In the following URLs, replace the <hostname> and <port> with the 
   actual fully qualified host name and port on which the sample 
   application will be running.

    * Policy 1:
          o allow:
                + http://<hostname>:<port>/agentsample/jsp/*
                + http://<hostname>:<port>/agentsample/invokerservlet
                + http://<hostname>:<port>/agentsample/protectedservlet
                + http://<hostname>:<port>/agentsample/securityawareservlet
                + http://<hostname>:<port>/agentsample/unprotectedservlet
          o Subject: the entire organization which is all authenticated users.                     
    * Policy 2:
          o allow:
                + http://<hostname>:<port>/agentsample/urlpolicyservlet
          o Subject: Group: customer




Configure the agent AMAgent.properties file
--------------------------------

1. UUID to principal mapping in AMAgent.properties file:

    By default, the installation assumes that the Access Manager product was
    under default Org/Realm "dc=iplanet,dc=com". If the Org/Realm for the
    deployment scenario is different from the default root suffix, the Universal
    Id (UUID) for the role/principal mappings should be changed accordingly. The
    Universal Id can be obtained by using the agentadmin --getUuid command.

    For WebLogic 10.0, a UUID has to be mapped to a value of type NMTOKEN, 
    and then the mapped value is used in weblogic-ejb-jar.xml and weblogic.xml 
    files as <principal-name> element value. The mapping is specified in 
    AMAgent.properties file by the property 

                com.sun.identity.agents.config.privileged.attribute.mapping[].

    Make sure the keys in the mapping are UUIDs corresponding to your Access
    Manager installation; There is no need to change the values. Now uncomment 
    out the mappings because by default they are commented out.


2. Modify the following properties in the AMAgent.properties file:

    * Not enforced List:
          com.sun.identity.agents.config.notenforced.uri[0] = /agentsample/public/*
          com.sun.identity.agents.config.notenforced.uri[1] = /agentsample/images/*
          com.sun.identity.agents.config.notenforced.uri[2] = /agentsample/styles/*
          com.sun.identity.agents.config.notenforced.uri[3] = /agentsample/index.html
          com.sun.identity.agents.config.notenforced.uri[4] = /agentsample
    * Access Denied URI:
          com.sun.identity.agents.config.access.denied.uri = 
			/agentsample/authentication/accessdenied.html
    * Form List:
          com.sun.identity.agents.config.login.form[0] = 
                        /agentsample/authentication/login.html

3. The WebLogic server with the agent installation and hosting the sample 
   application needs to be restarted.



Deploying the Sample Application
--------------------------------
Note, before deploying the sample application, please be sure that you have
deployed the Agent Application, which should have been done after installing 
the agent.This was explained in the Sun Java System Access Manager Policy 
Agent 2.2 Guide for BEA WebLogic Server/Portal 10.0 in the chapter which 
outlined the post-installation tasks.

To deploy the application, do the following:

Go 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>/logs/debug directory.

Also, see the Sun Java System Access Manager Policy Agent 2.2 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 is 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.