How to set up an agent in a sub-realm?

For more Policy Agent 3.0 questions see the FAQ

In general, it is discouraged to create an agent in a sub-realm and it is encouraged to create an agent in a top level realm. So you dont need to learn about this feature unless you really need it. It is mostly here for backward compatability.

For some agents, their profiles and configuration information is not in a top level realm but is in a sub realm. By default, opensso has a top level realm called opensso. So usually when you create an agent on the fam server(when you create an agent's profile and the agent's configuration), you do this by clicking on the realm and then within that realm's page clicking the Agent tab and then creating a new agent. Sometimes a user may want an agent under a sub-realm.

Steps to configure an agent in a sub-realm

These steps will outline how to create a sub-realm under the opensso realm and then create and configure an agent to use that sub-realm. You could generalize this example for other realm names.

1) On the opensso/fam server, using the console UI, login as "amAdmin"
2) Navigate to a realm. For example to get to the default opensso realm click on the tab "Access Control". This page will list the existing realms.
3) Create a sub-realm. On the Access Control page, above the list of realm names click "New". Now on the New Realm page, choose a name (I will use "mytestsubrealm" as the name in this example) and choose a Parent realm from the displayed list(I chose "opensso" as the parent realm in this example). Then click OK to create the new sub-realm and take you back to the Access Control page which lists all the realms. You will see the new subrealm listed in the Realms table with a location of "opensso > mytestsubrealm" which indicates it is a sub-realm of opensso.
4) create an agent that is in this sub-realm. This process is just like creating an agent under the opensso realm: just click on the "mytestsubrealm" realm, then on that realms page click the "Agents" tab choose new the agent type you want and create the new agent profile and consfiguration.
Now the fam server side is set up.
5) Configure the installed agent to use this sub-realm. In the installed agent, use this sub-realm name (in our example "mytestsubrealm") as the value in the FAMAgentBootstrap.properties file for the property com.sun.identity.agents.config.organization.name = /mytestsubrealm
or whatever name you chose for mytestsubrealm as sub-realm name. Note the "/" before the name.

6) Test it out. Configure the agent configuration on the fam server for the sample app (or some other application you deployed in the installed agents application server domain) and deploy agentsample app and click around the sample application as a user and see that things work.
7) Wasn't that fun!