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:

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: https://backstage.forgerock.com/#!/docs/openam-policy-agents/3.5.0/jee-release-notes#table-jee-pa-platform-requirements

JASPA Quick Start:

Grab the code from here: https://stash.forgerock.org/projects/OPENAM/repos/jee-agents/browse

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:

com.iplanet.services.debug.level=error

in the file

<AGENT_INSTALLATION_PATH>/Agent_001/config/OpenSSOAgentBootstrap.properties

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 for an SSO Token.  If an SSO isn't present, it 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 token.  If it does not, you're in a world of pain because OpenAM is setting a token 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 must 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 NotEnforcedEntryHelper.active 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.  If you're not running under Tomcat, then best of luck.

How do I change what jars JASPA deploys?

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

jee-agents-distribution/jee-agents-distribution-tomcat-v6/src/main/assembly/tomcat-v6_KitAssembly_Descriptor.xml

jee-agents-tomcat/jee-agents-tomcat-v6/pom.xml

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:
https://docs.google.com/document/d/1N_n4-kZ-nxs2pNkFhy0Ehs18M0DPbkNEUPr99iukHiw

There is a many page (more detailed) description of the changes here:
https://docs.google.com/document/d/10xivGjg0ON9icybi8RoHNKIRWxno3qYjHf-SNz8vsBs


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 OpenSSOAgentBootstrap.properties and is called com.sun.identity.agents.config.organization.name.  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