December 5, 2016

Single Sign-On Security: OpenAM and RDBMS Configuration

OpenAM is an open source platform developed by ForgeRock that provides a single sign-on feature. Many different platforms can be used for identity mapping, such as RDBMS, LDAP, etc. OpenAM also provides authentication through social networking site like Facebook, Google+, etc. 

First of all, using OpenAM as Identity provider, we need to connect OpenAM with the database. Therefore, in this post, I will focus on configuring the OpenAM connection with any database. Below is a step-by-step description to configure OpenAM with the database using Postgres. 


  • The Apache Tomcat server should be configured and running on the machine.
  • Maven should be configured.
  • Download the OpenAM source code (ver 14.0.0) using git:
  • Create OpenAM WAR file using the Maven command “mvn clean package
  • To use the Postgres Server, we need to put Postgres JDBC jar. Here I am placing this JAR directly in the Tomcat container under “Tomcat/lib” folder.
  • Add JNDI connection string to context.xml in Tomcat configuration. Add below entry into “Tomcat/conf/context.xml” file.
<Resource name="jdbc/opensso"   type="javax.sql.DataSource"  driverClassName="org.postgresql.Driver"     url="jdbc:postgresql://localhost:5432/mydb"  username="****" password="****" maxActive="20" maxIdle="10"    maxWait="-1"/>

Note: All entries above for adding JNDI resource are according to the Postgres database. Use these parameters according to your preferred database.


  1. Copy OpenAM war file in Webapps folder under your Tomcat installation and restart Tomcat server. Wait until Tomcat restarts. image1
  1. Access the OpenAM context from your local setup. Make sure that you are accessing the OpenAM using the machine/DNS name, rather than using localhost or IP. Otherwise, you will not able to access this setup from outside systems.                          image2
  1. Select the “Create Default Configuration” link available on the page. Accept the license and click continue. As a result, a dialog will pop-up. Create user and policy agents passwords.                                        image3
  1. First of all, we create a password for amAdmin and policy agent users. For this example I used “password” as the password for the “amAdmin” user, and “secret123” as the password for policy agent user.
  2. Click on the “Create Configuration” button. A pop-up will appear that starts displaying the progress for our setup. Once the configuration finished, your OpenAM setup completed.


Now we will configure OpenAM to connect with the database.

Realm Creation

  1. Click on “proceed to Login” link. To login to the system, use the same password that you created in previous step for the amAdmin user.       image5
  2. Now we will create a new Realm. This will help in configuring a new context (within OpenAM), that provides authentication using database.
  3. Click on the “New Realm” button. Provide a name for this Realm, and click on the “Create” button.               image6
  4. As a result, a new Realm is created. Select the newly created Realm.
  5. Now we will configure the newly created Realm so that it connects with our underlying database (in my case it is Postgres).                . image7

Realm Configuration

Authentication Module Configuration

  1. Click the “Authentication” option, which is available on the left hand side menu. Select the “Modules” option from the authentication sub-menu.image8
  2. Create a new module using the “Add Module” button. In the following window, create a name for the module and select the “JDBC” option from drop-down menu, because this module will use JDBC to retrieve data from database. Click on the “Create” button.                              image9
  3. This will bring up a setting page where you’ll specify JDBC settings like the database URL, JDBC Driver, user name, password, etc. Now we require to provide database connection settings according to our underlying database. In addition, this setting also requires an SQL query (a prepared statement) to retrieve the password on the basis of the username. 
  4. Fill all required entries according to our underlying database. Click on the “Save Changes” button. As a result, JDBC connection settings will be saved.     image10

Note: Since this setting also requires a JNDI name, I used the same JNDI name that is specified in the Prerequisites section. Because I am using the Postgres database for my setup, I used the setting according to my database as shown in above image. 


We need to chain our authentication module so that whenever any request comes for this Realm, our configured module will server that request.

  1. Click on the “Authentication” options available on left hand side menu and select the “Chains” sub-menu option.image11
  2. Click on the “Add Chain” button. Provide a name in the “name” text box and click on the “Create” button. image12
  3. On the following screen, click on the “Add a Module” button. Select the “JDBC” option in module and the “Required” option in the criteria from their respective drop downs. Here is where we will specify that the “JDBC  module is required” criteria for this module chain. Click on the “OK” button on the page and click on the “Save Changes” button in the main window.                             image13
  4. Select the “Chains” options again from the left-hand side menu and also delete the “ldapService” chain option. This option needs to be deleted because we want our underlying database to only have one option in this authentication chain, so as to provide data for authentication.

Data Store Configuration

Finally, we will configure the data store for this setup.

  1. Select the “Data Stores” option from the left hand side menu and click on the “New” button on the data stores screen. image14
  2. Provide a name for the data store configuration and also select the “Database Repository (Early Access)” radio button. Click on the “Next” button. image15
  3. In the settings window, fill in all of the required information according to the underlying database. This should be the same information that we already used in the JDBC module configuration section.
  4. Go to the “Plugin configuration” section. Select and remove all entries from attribute name mapping.  image16
  5. Scroll down to the “User Configuration” section on the same page. Select all of the entries from “List of user attribute name in database” and remove those entries. Most of these entries are irrelevant for our database option. Give the table name in the specified text-box and add all of the columns in the “List of user attribute name in database” section of your table using the “Add” button.
  6. Fill in the respective column name and status in the respective text boxes available on the page.
  7. In this example, I am using “A” for “Active” user and “I” for “In-Active” user. We will choose values on the basis of our table data.                                 image17
  8. Click the “Finish” button. The system control comes back to the “Data Stores” screen. Select “embedded” entry from the list and delete this entry.                                image18
  9. Finally our Realm configuration is finished.
  10. To test this configuration, go to the “Subject” tab. If all of the rows from the “user name” column (from the specified table) are displayed on the page, the configuration is successfully connected with our underlying database. image19

Note: In addition, OpenAM configuration creates logs into its configured directory in Windows under the “users/<user-name>”  (i.e. “C:\Users\manish.sharma1\“) folder. There is one OpenAM folder that contains all of the setup files and log files related to this OpenAM configuration. If it’s required to do this setup from the beginning again, or if any error has occurred during this setup, delete the OpenA and .openamcfg folders and start the configuration again from scratch.

Happy learning!