Sample Application Trouble Shooting Tips on Policy Agents 2.2 for Sun Application Server 9.x or GlassFish

See All OpenSSO Policy Agents 2.2 ToubleShooting page for other agents.

This is an informal and unofficial additional resource to help you fix a problem when have installed and configuring a policy agent 2.2 on the Sun 9.x application server or also on the GlassFish application server, and now you want to try out the agent sample application. Feel free to add your own at the end of the list below.

See Opensso policy agent sample application for more detail on the sample application.

Start by checking:

• For general agent installation and configuration issues, the main trouble shooting wiki page which lists some general tips as well as some official references for more general troubleshooting info.
• Sample application readme file. The sample application directory contains a readme file that contains key information.

Now, on to some tips for using the J2EE Agent Sample Application.

General Info

The J2EE Agent download contains a sample application that you can try out and learn more about using the J2EE agents and the Access Manager to secure a web application.

• Where is the sample application?
  When you downloaded the agent, appserver_v9_agent.zip, and unzipped it, you will can look inside j2ee_agents\appserver_v9_agent\sampleapp\ directory of your agent unzip.
• When should I try the sample app?
  You should have already installed the access manager server and also the J2EE agent. Test you application server and agent installation and am server installation a little bit first to make sure your installations are working. Then try out the sample application.
• Why should I try the sample app?
  Besides just using it for learning, it is a great way to test that your agent and am server installatons are done correctly. If you can configure,deploy, use the sample application,
• Do I have to build the sample application?
  Yes, if you are using Access Manager 7.1 or earlier versions for the Access Manager server which the J2EE agent will communicate with.
  No, if you are using opensso access manager.
  The Agent download has a prebuilt ear file that you can use. BUT it has set the Uuid by default to opensoo realm, and this needs to be changed in the sample app deployment descriptor and the app must be built using the Ant scripts provided with the sample. See step 3 of the sample application readme file for details.
• What agent modes of security does it use?
  It sets com.sun.identity.agents.config.filter.mode = ALL
  and in the sample app it uses J2EE_POLICY and URL policy. Some resources are protected by J2EE deployment descriptor roles and have a matching policy on Access Manager server, and some resources are protected by URL policy (so nothing specified in sample app deploymnet decsriptors) and have a policy on AM server for that url. Right now it does not use SSO since it would require another web app, but that would be a good addition for the future.
• Where are instructions to use the sample application?
  The official Agent Guide documents how to configure an application to be protected by the J2EE agents so it is a useful general document. The sample application also contains a readme file which outlines in some detail many of the steps needed to configure the agent for the smaple application.
• Where can I go to ask questions?
  There are some forums, such as Access Manager forum which is a good place to ask questions and is friendly to beginners too.

Extra Trouble Shooting Tips

Feel free to add your own at the end of the list below

Using the Access Manager server 7.1 and NOT opensso Access Manager server

PROBLEM:
The agent that is protecting the sample application will need to communicate with an Access Manager server. Adddtionally the Access Manager server will need to create some policies and other information that match the security policy of the sample application. Opensso is the open source project where the Access Manager and Agents source code is developed. The opensso project has an access manager server version that can be downloaded and used. Or you can download the Access manager 7.1 which is the official download that is well tested.
If you are using the Access Manager 7.1 then you will need to do an extra step as well as build the agent sample application(compile and build instructions are in the readme). In particular, setp 3 of the reame build instructions must be done before building, and this step is tricky.
NOTE: SHOULD TRY TO ADD AN ERROR MESSAGE FROM LOGS and BROWSER that user would see if they forgot to do this step. as it would HELP RECOGNIZE AND DIAGNOSE this issue. NEED TO GET A SAMPLE ERROR MESSAGE.= and paste it here.
SOLUTION:
See step 3 in the sample application readme section on "Compiling and Assembling the Application".
It says ...

By default, the Application server specific deployment descriptors assume
that the OpenSSO Server product was installed under default Org/Realm
"dc=opensso,dc=java,dc=net". 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.

So you will need to do that step, which is easy to miss in the readme.
Note the agentadmin --getUuid command has a bug and actually does not work, see the troubleshooting tip below for details and a workaround to get the Uuid info you need.
Also, the readme does not mention which deployment descriptors need changing so here is a list of the decsriptors that need this change, plus some examples of what to change. It is easy to do, but more info can make it easier:
First, the deployment descriptors are located in j2ee_agents\appserver_v9_agent\sampleapp\etc\ directory.
Second, the files that need to changing are sun-application.xml and sun-web.xml.
Third, open up sun-application.xml and sun-web.xml and each has find the group name elements that have the opensso default realm Uuid as there value
<group-name>id=manager,ou=role,dc=opensso,dc=java,dc=net</group-name>
and replace the value with the Uuid of the realm you will use on your Access Manager server.

Sample readme file says to use "agentadmin --getUuid" command and that command does not work.

PROBLEM:
In step 3 of the sample application readme, in the section on "Compiling and Assembling the Application" it says to use the "agentadmin --getUuid" command to get some realm info you will need to modify in the deployment decsriptors of the sample app. But, unfortunately, the "agentadmin --getUuid" command does not seem to work. This is a known issue and documented in official docs.
SOLUTION:
You can obtain this information in another way instead of using the agent "agentadmin --getUuid" command. Instead, log in to your Access manager server console UI as the admin, click on the realm, click on subjects, click on the User or Role profile tab, click on a specific user or role that you are interested in getting the Uuid for, scroll to the bottom of the window and look at the Uuid for the user or role. This is the same info. For example, in the Access Manager console, for a role you might see something like "Universal ID: id=employee,ou=role,dc=opensso,dc=java,dc=net" or for a user(principal) named andy "Universal ID: id=andy,ou=user,dc=opensso,dc=java,dc=net".

Add a new troubleshooting tip

PROBLEM:

SOLUTION: