Skip to end of metadata
Go to start of metadata

This is the landing page for all things developer oriented regarding the OpenAM Agents, i.e. the C agents and the J2EE agents.

The idea is that if you're a developer wanting to make rapid progress with the agents, this document will point to information on what you need to do.

C Agents (code name CASPA - C Application Server Policy Agent):

There's a link here that you might find helpful: OpenAM Policy Agents

JEE Agents (code name JASPA - Java Application Server Policy Agent):

One of the dangers is to provide so much information that you don't know where to start, but for reference, this is what we show to customers:

Here is a document Peter Major wrote back in 2013:

Supported Platforms

The platforms we support are a bit of a moving target, there is a list here: Target Platforms for Agents 3.5 but we're currently thinking that this list here is a more up to date/realistic one:!/docs/openam-policy-agents/3.5.0/jee-release-notes#table-jee-pa-platform-requirements

JASPA Quick Start:

Grab the code from here:

Build the code by looking here: JASPA Notes - Building the agent

Install it (sorry, this needs its own page, but at the moment that hasn't been written yet).  An easy path to victory is to install it in Tomcat 7 or 8.  The shortest path to victory is to install into Jetty which is very straightforward.  You will need to run it against OpenAM 14 deployed into Tomcat 8 (it needs that for the websockets).

Debugging JASPA

You can increase the initial debugging level by editing:

in the file


You can either remove the line, set the property to be empty, or change "error" to "message" Once the agent gets going, it reads its config (including the debugging level) from OpenAM, so you'll need to specify this in the General tab of the Agent User in the XUI.

HELP ME, JASPA doesn't work!  What can I do?

Place a breakpoint in SSOTaskHandler.process, which checks the incoming request for a valid JWT.  If JWT isn't present, or if it is and it is invalid, the Agent redirects to OpenAM.  The goto parameter of the OpenAM login page eventually redirects back to the very same function.  At this point JASPA should pick up the JWT.  If it does not, you're in a world of pain because OpenAM is setting a JWT which isn't visible to JASPA, which can easily result in infinite redirect loops.  Don't forget that everything is CDSSO now and that JASPA and OpenAM should be in different domains.  See the setup checklist to ensure you've correctly initialised everything.

If you find your breakpoint is not being hit in SSOTaskHandler.process, then consider it may be a problem in the not enforced URI handling.  Remember that NotEnforcedTaskHandler is only active when the returns true, which is only when not enforced URLs are defined.  Again, place a breakpoint in the process function to see if access is being denied there.

If none of your breakpoints are hit, you have possibly neglected to protect the application you are trying to access.  The process for this is web container specific, but if you're using Tomcat, see the section "Protect every webapp you want to access" in JASPA Notes - Installing on Tomcat

It's worse than that!  JASPA won't even start!!  What can I do?

When running within Tomcat, the first piece of code to be run is the static block of  com.sun.identity.agents.tomcat.v6.AmTomcatRealm.  Try putting a breakpoint there.

After I authenticate with OpenAM, I see redirect_uri_mismatch The redirection URI provided does not match a pre-registered value

 Top Level Realm > Agents > JEE > Global: You need to add the agent base URL into "Agent Root URL for CDSSO"

After I authenticate with OpenAM, I see the XUI user profile page

This will happen when you have setup the Agent and OpenAM in slightly different domains, e.g. for the Agent, but for OpenAM.  Thus cookies from OpenAM cannot be seen by the agent.  The agent - thinking there is no valid session - redirects to OpenAM to log in, but because you're already logged in, it doesn't know what to do, so dumps you on the Profile Page.  Fix this issue by firing up the XUI as amadmin and going to Configure > Global Services > Platform > Cookie Domains and changing to just

How do I change what jars JASPA deploys?

Taking the Tomcat V6 distribution as an example, the two files that need changing are:



The new jar must appear in both files.  For an example, see openam-sdk-controller (although this may not be a very good example, since the version number had to be included in the pom.xml and I don't think this is right).

JASPA Not-enforced rules:

There is a one page description of the changes here:

There is a many page (more detailed) description of the changes here:

How do I set the realms JASPA uses?

Note that the handling of realms is very different between 3.x and 5.x.  For the 3.x there was only one realm, the "Agent Realm".  5.x introduces the idea of a "Policy Evaluation Realm", which 3.x should have supported and didn't:

  1. The "Agent Realm", is the realm that contains the "definition of the agent", or the "agent user" or the "agent profile name" or the "agent profile user", whatever you like to call it.
  2. The "Policy Evaluation Realm", is the realm in which all policies are evaluated.  The users who the policies apply to must also live in this realm.

Agent Realm:
As the Agent Realm must be known before the remote configuration is gathered, the property is stored in and is called  Yes I know this property doesn't mention realm.  This isn't a typo.  Realms used to be called "organisations", just spelled a bit wrong.

Policy Evaluation Realm:

The property org.forgerock.openam.agents.config.policy.evaluation.realm is set in the remote configuration downloaded on startup (the whole startup process is described in nauseating detail here).  You can find the setting in the XUI via the realm defining the JEE Agent, Subjects > Agents > J2EE > Agent Name > OpenAM Services > Policy Client Service > Realm

Note: Only the root realm has a default Policy Set, so you will need to define the Policy Set to be used (just underneath the realm in the XUI).  You could circumvent this by naming your Policy Set "iPlanetAMWebAgentService".

  • No labels