Free trial

A simple OpenAM realm scenario

A Realm is an OpenAM concept and a feature which is used to group and organise the information and configuration parameters. OpenAM has a top level realm which contains all other, user-defined, realms. We will try here to demonstrate the realm functionality on a simple but practical scenario where realms will be used to separate administration entities.

Let’s imagine a hypothetical service provider company ( which has a centralised directory for all of it’s clients, and a separate branch per client:

  • suffix: dc=example,dc=com
  • Client1: o=client1,dc=example,dc=com
  • Client2: o=client2,dc=example,dc=com would like to employ OpenAM  for access management (authentication and authorisation) in a way that users from the client companies cannot access each other’s resources. This functionality can be easily achieved by the Realms feature such that each client company has it’s own sub-realm. Below we’ll explain the detailed setup procedure.

Software for the example deployment

This exercise is based on the following software:

  • Linux CentOS 6.2 on VirtualBox with 2 GB of RAM
  • ForgeRock OpenDJ 2.4.5 directory server
  • Apache Tomcat 7.0 web container
  • ForgeRock OpenAM 10.0.0
  • Sun/Oracle Java Development Kit 1.6


Detailed CentOS installation is out of the scope of this article, but the main points are:

  • Basic Server packages are sufficient;
  • SELinux should be disabled, and
  • Firewall should be switched off.
Of course, SELinux and firewall should not be disabled in production, but for the piloting purposes it would make the troubleshooting a lot easier.

OS installation media can be obtained from:

ForgeRock software (OpenAM and OpenDJ) has been tested primarily with Sun JDK, that one has to be installed separately, and it can be obtained from:

Directory Server

OpenDJ 2.4.5 LDAP server can be downloaded from:

To install it, we’ll unzip it to ‘/opt’, rename it to something friendlier, and configure it with the root suffix ‘dc=example,dc=com’:

unzip -d /opt
mv /opt/OpenDJ-2.4.5 /opt/ds1
–baseDN dc=example,dc=com
–ldapPort 389
–adminConnectorPort 4444
–rootUserDN cn=Directory Manager
–rootUserPassword password

After the successful installation, the directory should be up and running.

OpenAM requires two repositories: configuration and data. To keep our example simple, instead of having more directories we will simply add another root suffix to simulate the second directory. ‘dc=example,dc=com’ suffix will serve as user (data) repository, so we should create a new one, ‘o=openam’ to serve as the configuration repository:

/opt/ds1/bin/dsconfig -X -n set-backend-prop -D “cn=directory manager” -w password –backend-name userRoot –add base-dn:o=openam

The next step is to create the DIT hierarchy to reflect the needs of this scenario. For that, we’ll create the the ‘tree.ldif’ file as follows:

dn: o=openam
changetype: add
objectclass: top
objectclass: organization
o: openam

dn: o=client1,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organization
o: client1

dn: o=client2,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organization
o: client2

dn: ou=people,o=client1,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: people

dn: ou=groups,o=client1,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: groups

dn: ou=people,o=client2,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: people

dn: ou=groups,o=client2,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: groups

Import the ldif:

/opt/ds1/bin/ldapmodify -c -h localhost -p 389 -D “cn=Directory Manager” -w password -f tree.ldif

The directory is now ready.


Tomcat 7.0 does not come with CentOS 6.2 repositories, so it should be installed manually. It can be downloaded from it’s official page:

Unpacking it makes it ready for use:

gzip -dc apache-tomcat-7.0.27.tar.gz | (cd /opt && tar xf -)
cd /opt
mv apache-tomcat-7.0.27 tomcat


OpenAM binaries are available on the following URL:

The installation is quite straightforward:

  • unzip the archive:

unzip -d /opt
cd /opt/opensso

  • deploy the WAR:

cp /opt/opensso/deployable-war/opensso.war /opt/tomcat/webapps/openam.war

Tomcat detects the WAR file and deploys it automatically by default. OpenAM is now ready for configuration and can be accessed on the following URL: http://<FQDN>:8080/openam

Follow the screens for the Custom Installation and enter the parameters for OpenDJ.

Step 1: set the password to: ‘password’

Step 2: set the “Cookie Domain” to: (do not forget the leading dot . ), and the “Configuration Directory” to ‘/var/opt/openam’

Step 3: “Configuration Data Store” should be OpenDJ or Sun Java Systems Directory Server, “Host Name” localhost, “Port” 389, “Encryption Key” 123456789012 (or any string of 12 characters), “Root Suffix” o=openam, “Login DN” cn=Directory Manager, “Password” password

Step 4: Other User Data Store should be selected, “Directory Name” localhost, “Port” 389, “Root Suffix” dc=example,dc=com, “Login DN” cn=Directory Manager, “Password” orionorion, “User Data Store Type” OpenDJ

Step 5: Site configuration No

Step 6: Default Policy Agent User, the password should be password1

Step 7: confirm the settings

Step 8: done!

After the installation, log in to the system as amadmin/password

  • go to Access Control tab;
  • click on the New Realm button;
  • create two new realms: Client1 and Client2;
  • for each new realm click on the realm name, go to the Data Store tab;
  • click on the configuration name in the table and change the base DN so that it points to the branch and not to the root, for example: o=client1,dc=example,dc=com (for Client2 realm you would put: o=client2,dc=example,dc=com)
  • in every realm, click on the Subjects tab;
  •  and create a new user (test1 for Client1 realm and test2 for Client2)

At this point you can log in the the OpenAM realm as a user, but take into the account:

  • when logging in, if you do not change the URL the top level realm would authenticate the user against it’s own Data Store which is configured to search for user accounts in ‘ou=people,dc=example,dc=com’;
  • it can be logged in directly to the realm by adding ?realm=Client1 (for example, or Client2) to the end of the url:
forgerock ldap ldif openam opendj realms tomcat

5 Responses to “A simple OpenAM realm scenario”

  1. groser says:

    authentication via login url is OK but via REST interface I get an error:
    curl -x “” -d”username=test1&password=demopass&realm=/client1&module=ldap” http://mydomain:8081/opensso/identity/authenticate Authentication Failed!!
    http://mydomain:8081/openam/UI/Login?realm=Client1 login is OK with same credentials
    and REST auth to / is also OK :
    curl -x “” -d”username=demo&password=demopass” is OK

  2. Avinash says:

    I am installing openam 10.0.0 on centOS with java 1.6 and tomcat 1.6 but i am facing below error.
    Creating OpenAM suffixYou have provided options for scheduling this operation as a task but optionsprovided for connecting to the server’s tasks backend resulted in thefollowing error: ‘Connect Error’

    Any kind of help is appreciated.


Leave a Reply

Related articles


Let’s make LLMs generate JSON!

In this article, we are going to talk about three tools that can, at least in theory, force any local LLM to produce structured output: LM Format Enforcer, Outlines, and Guidance. After a short description of each tool, we will evaluate their performance on a few test cases ranging from book recommendations to extracting information from HTML. And the best for the end, we will show you how forcing LLMs to produce a structured output can be used to solve a very common problem in many businesses: extracting structured records from free-form text.

Notiondipity: What I learned about browser extension development

Me and many of my colleagues at profiq use Notion for note-taking and work organization. Our workspaces contain a lot of knowledge about our work, plans, or the articles or books we read. At some point, a thought came to my mind: couldn’t we use all this knowledge to come up with project ideas suited to our skills and interests?

From ChatGPT to Smart Agents: The Next Frontier in App Integration

It has been over a year since OpenAI introduced ChatGPT and brought the power of AI and large language models (LLMs) to the average consumer. But we could argue that introducing APIs for seamlessly integrating large language models into apps developed by companies and independent hackers all over the world can be the true game changer in the long term. Developers are having heated discussions about how we can utilize this technology to develop truly useful apps that provide real value instead of just copying what OpenAI does. We want to contribute to this discussion by showing you how we think about developing autonomous agents at profiq. But first a bit of background.