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 (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

OS

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:

http://www.oracle.com/technetwork/java/javase/downloads/jdk-6u32-downloads-1594644.html

Directory Server

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
/opt/ds1/setup
–cli
–baseDN dc=example,dc=com
–addBaseEntry
–ldapPort 389
–adminConnectorPort 4444
–rootUserDN cn=Directory Manager
–rootUserPassword password
–no-prompt
–noPropertiesFile

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

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 -)
cd /opt
mv apache-tomcat-7.0.27 tomcat
/opt/tomcat/bin/startup.sh

OpenAM

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
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: .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