31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper Copyright (c) 2008 Sun Microsystems Inc. All Rights Reserved
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper The contents of this file are subject to the terms
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper of the Common Development and Distribution License
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper (the License). You may not use this file except in
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper compliance with the License.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper You can obtain a copy of the License at
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper https://opensso.dev.java.net/public/CDDLv1.0.html or
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper See the License for the specific language governing
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper permission and limitations under the License.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper When distributing Covered Code, include this CDDL
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper Header Notice in each file and include the License file
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper If applicable, add the following below the CDDL Header,
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper with the fields enclosed by brackets [] replaced by
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper your own identifying information:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper "Portions Copyrighted [year] [name of copyright owner]"
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper $Id: readme.txt,v 1.1 2009/01/30 12:05:35 kalpanakm Exp $
0595fb660c93faf1fdbaad7e1300eb342b5baf31Mark de Reeper Portions Copyrighted 2013-2014 ForgeRock AS.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper------------------------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperJ2EE Policy Agent Sample Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper------------------------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperThis document describes how to use the agent sample application in conjunction
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperwith the Sun Application Server and the J2EE Agent. Please note that the agent
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperneeds to be installed first before deploying this sample application.
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de Reeper * Configure the OpenAM server
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper * Configure the agent properties
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper * Compiling and Assembling the Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper * Deploying the Sample Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper * Running the Sample Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper * Troubleshooting
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperThe sample application is a collection of servlets, JSPs and EJB's that
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperdemonstrate the salient features of the J2EE policy Agent. These features
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperinclude SSO, web-tier declarative security, programmatic security, URL policy
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperevaluation and session/policy/profile attribute fetch. The web.xml deployment
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperdescriptor has already been edited to include the Agent Filter. The
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperdeployment descriptors and source code are available in the sampleapp/src
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperThe sample application is supported for Policy Agent 3.0.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperThe application is already built and ready to be deployed. It is available at
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperNote, the instructions here assume that you have installed the agent
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de Reepersuccessfully and have followed the steps outlined in the OpenAM
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperPolicy Agent 3.0 Guide for Sun Java System Application Server 9, including
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperthe post-installation steps.
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de ReeperConfigure the OpenAM server
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper---------------------------------------------
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de ReeperThis agent sample application requires that the OpenAM server is configured
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperwith the subjects and policies required by the sample application.
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de ReeperOn OpenAM admin console, do the following configuration.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper1. Create the following users:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper Here is the following list of users with username/password :
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper2. Assign Users to Groups
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper Create new groups for employee, manager, everyone, and customer. Then assign
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper the users to the groups as follows:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper o andy, bob, chris, dave, ellen, frank
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper o andy, bob, chris
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper o andy, bob, chris, dave, ellen, frank, gina
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper o chris, ellen
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper3. Create the following URL Policies:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper In the following URLs, replace the <hostname> and <port> with the
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper actual fully qualified host name and port on which the sample
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper application will be running.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper + http://<hostname>:<port>/agentsample/invokerservlet
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper + http://<hostname>:<port>/agentsample/protectedservlet
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper + http://<hostname>:<port>/agentsample/securityawareservlet
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper + http://<hostname>:<port>/agentsample/unprotectedservlet
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper o Subject: all authenticated users.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper + http://<hostname>:<port>/agentsample/urlpolicyservlet
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper o Subject: Group: customer
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperConfigure the agent properties
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper------------------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper If the agent configuration is centralized, then do the following steps.
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de Reeper 1). login to OpenAM console as amadmin user
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 2). navigate to Access Control/realm/Agents/J2EE, and click on the agent
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper instance link (assume the agent instance is already created, otherwise
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper refer to the agent doc to create the agent instance).
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 3). in tab "Application", section "Access Denied URI Processing", property
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper "Resource Access Denied URI", enter agentsample in the Map Key field,
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper /agentsample/authentication/accessdenied.html in the Map Value field, and
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper SAVE the change.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 4). in tab "Application", section "Login Processing", property "Login Form URI",
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper add /agentsample/authentication/login.html, and SAVE the change.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 5). in tab "Application", section "Not Enforced URI Processing", property
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper "Not Enforced URIs", add the following entries:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper /agentsample/
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper and SAVE the change.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper If the agent configuration is local, then edit the local agent configuration
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper file OpenSSOAgentConfiguration.properties located at the directory
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper <agent_install_root>/Agent_<instance_number>/config with following changes:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper * Not enforced List:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.notenforced.uri[0] = /agentsample/public/*
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.notenforced.uri[1] = /agentsample/images/*
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.notenforced.uri[2] = /agentsample/styles/*
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.notenforced.uri[3] = /agentsample/index.html
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.notenforced.uri[4] = /agentsample/
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.notenforced.uri[5] = /agentsample
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper * Access Denied URI:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.access.denied.uri[agentsample] = /agentsample/authentication/accessdenied.html
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper com.sun.identity.agents.config.login.form[0] = /agentsample/authentication/login.html
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper Optionally, you can try out the fetch mode features that allow the agent to
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper fetch some values and make them available to your application. For example,
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper you can fetch user profile values(like email or full name) from the user data
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de Reeper store of your OpenAM setup and make them available to your application code
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper (through cookies, headers, or request attributes) for application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper customization. See the Policy Agent 3.0 for details about the fetching
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper attributes for details on using this feature. If you change the agent's
0595fb660c93faf1fdbaad7e1300eb342b5baf31Mark de Reeper configuration for the attribute fetching, the showHttpHeaders.jsp page of the
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper sample application will show all the attributes being fetched. You can choose
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper to try this later after you have already installed and deployed the agent and
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper sample application in order to learn about this feature.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperCompiling and Assembling the Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper----------------------------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperThis section contains instructions to build and assemble the sample application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperusing a Command Line Interface (CLI).
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperTo build the entire application from scratch, follow these steps:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 1. Set your JAVA_HOME and CLASSPATH to JDK1.4 or above.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 2. Replace 'APPSERV_LIB_DIR' in build.xml with the directory where j2ee.jar
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper is located. For example: replace APPSERV_LIB_DIR with
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper /opt/SUNWappserver/appserver/lib where /opt/SUNWappserver/appserver is
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper your <appserver_install_root>.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 3 Change the Universal User Id (UUID)
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper By default, the Application server specific deployment descriptors assume
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de Reeper that the OpenAM Server product was installed under default Org/Realm
0595fb660c93faf1fdbaad7e1300eb342b5baf31Mark de Reeper "dc=openam,dc=forgerock,dc=org". If the Org/Realm for the deployment scenario
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper is different from the default root suffix, the UUID for the role/principal
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper mappings should be changed accordingly. The UUID can be obtained from the
dca1e5e05c4dc49f6ce1ceb50100476adc3281b1Mark de Reeper e.g. the root suffix of the OpenAM server deployment is "dc=xyz,dc=com".
0595fb660c93faf1fdbaad7e1300eb342b5baf31Mark de Reeper then replace all the occurrences of "dc=openam,dc=forgerock,dc=org" with
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper "dc=xyz,dc=com" in etc/sun-web.xml and etc/sun-application.xml.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 4. Compile and assemble the application.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper execute the command <appserver_install_root>/bin/asant
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper under <agent_install_root>/sampleapp/ to execute the default target build
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper and rebuild the EAR file.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper The build target creates a built and dist directory with the EAR file.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 5. Deploy the application. After you have re-created the sample application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper from scratch, you may proceed directly to Deploying the Sample Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper or optionally perform step 5.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 6. Optionally you can run 'ant rebuild' to clean the application project
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper area and run a new build.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperNow you are ready to use the dist/agentsample.ear file for deployment.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperDeploying the Sample Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper--------------------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperTo deploy the application, do the following:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperExecute the command asadmin deploy
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper<appserver_install_root/bin/asadmin deploy --user <username> --password <password> <agent_install_root>/sampleapp/dist/agentsample.ear
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperOr you can log into the Application Server Admin Console to deploy the agentsample.ear.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperVerifying Deployment
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper--------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperAs an optional step, you can use the Application Server Administration Tool to
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperverify that the application has been registered. Otherwise, proceed directly to
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperRunning the Sample Application.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperTo verify the registration of the application:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 1. Execute the command asadmin list-components to look at applications deployed with a server instance.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper asadmin list-components --user <username> --password <password>
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper You will see agentsample listed.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper 2. Alternately, use the Application Server Admin Console and navigate to
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper Applications > Enterprise Applications. You will see agentsample listed.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperRunning the Sample Application
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper----------------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperYou can access the application through the following URL in a web browser:
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperTraverse the various links to understand each agent feature.
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperTroubleshooting
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper----------------------------
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de ReeperIf you encounter problems when running the application, review the log files to
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperlearn what exactly went wrong. Application server log files are located at
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeper<appserver_install_root>/domains/<domain_name>/logs and the J2EE Agent logs can
31734da27b3f913bfb1da241a2e2571f33ab4629Mark de Reeperbe found at <agent_install_root>/Agent_<instance_number>/logs/debug directory.