A simple OpenAM realm scenario
Posted 11 years ago by Nemanja Lukic
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 (Example.com) 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
Example.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.
OS installation media can be obtained from: http://www.centos.org/modules/tinycontent/index.php?id=15
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:
OpenDJ 2.4.5 LDAP server can be downloaded from: http://www.forgerock.org/opendj.html
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 OpenDJ-2.4.5.zip
mv /opt/OpenDJ-2.4.5 /opt/ds1
–rootUserDN cn=Directory Manager
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:
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: http://apache.rediris.es/tomcat/tomcat-7/v7.0.27/bin/apache-tomcat-7.0.27.tar.gz
Unpacking it makes it ready for use:
gzip -dc apache-tomcat-7.0.27.tar.gz | (cd /opt && tar xf -)
mv apache-tomcat-7.0.27 tomcat
OpenAM binaries are available on the following URL: http://download.forgerock.org/downloads/openam/openam10/10.0.0/openam_10.0.0.zip
The installation is quite straightforward:
- unzip the archive:
unzip -d /opt openam_10.0.0.zip
- 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: .example.com (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: http://openam.example.com:8080/openam/UI/Login?realm=Client1
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
exception.name=com.sun.identity.idsvcs.InvalidCredentials 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
As a colleague pointed out, https://blogs.oracle.com/docteger/entry/opensso_and_rest has some information about how to make REST calls. As per that article, you are missing uri= in the -d parameter:
Does it help?
yes, thanks for your help.
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.
Seems to me like OpenAM is unable to connect to the LDAP backend.