How to integrate OAM with Windows Active Directory (Part 1)

Last week one of my co-workers asked me if it was possible to integrate Active Directory  with Oracle Access Manager. So here is my two part mini-series on working with Oracle Access and Active Directory.  In the first post I will focus on integrating with active directory on a basic level. Next week I will expand on this by explaining more features which can be activated when integrating with an Active Directory.

Blog One, Basic integration with Active Directory

The objective

The objective of this integration is to let users use their windows credentials to access protected websites. Usually, most websites offer little support for integration with a directory, so in order to have users authenticate with their AD credentials, an access manager will be used. The basic functionality of an access manager is to shield resources by requiring authentication against a directory for instance. In order to achieve this, the user will have to be prompted by the access manager to enter its credentials. These will be checked against Active Directory to verify that they are correct. This will allow users to login using one username and password combination. In my case with all of the research I put into this I spent about 4 hours digging through documentation and blogs. After reading this blog you will probably manage the same in 1 hour.

The concept

To connect with the Active Directory we are going to use LDAP traffic. LDAP is an open source protocol which is designed to authenticate users using a directory. Wikipedia has a surprisingly good article on this subject if you want to get a good overview without having to dive deep into the technical specification.  In order to authenticate the user we will mostly use the LDAP search and bind methods. The LDAP search method can be used to search for any object in the directory, so we will have to tune this to only find users to make authentication faster. The second LDAP method, bind, is used to authenticate the user. It can be considered the login action against the directory. Upon receiving the request the directory will hash the provided password and check if this matches the stored password. Hashing is the action of encrypting the password using a one way encryption algorithm. By doing so, the password can never be decrypted. So to check if the password was entered correctly, the incoming password is hashed or one way encrypted, the same way as the stored password. If the result is the same, the user correctly entered the correct password.  If the user entered a different password, the result of the hashing process will differ from the stored password. This is how the directory is able to check if the user has entered the correct password. The result of this action is returned to the process requesting the authentication.

Components used

Active Directory Domain Services: (alternatively an Active Directory Lightweight Domain Services can be used). For more information, see: This wikipedia article and The microsoft discription.

Oracle Access Manager 11G: This is the basic authentication manager provided by Oracle. For this setup no additional components are used. For more information on the OAM, please see The oracle overview .

The integration process

In this blog post I will not go into the details of installing AD or OAM, as this is quite well documented and frankly, I want to get to the good part. So let’s get into the steps to integrate both components:

Step 1: Create a service account in AD.

You can create a service account quite fast in AD by opening the AD users and computers tool. This will open a graphical user interface which will allow you to do basic tasks in AD. In my example I have created the domain bramtest.amis and placed my users under the Users OU. You can see my setup in the screenshot below.

You can create a new user by copying the administrator user. This will be the fastest way to create a service account, but please notice that the copied account will have elevated rights!  So my recommendation is to limit the service account login rights.  For instance by following this guide.

Step 2: Create a user identity store configuration in Oracle Access Manager.

The first step in configuring Oracle Access Manager is exposing the Active Directory(AD) to Oracle Access Manager(OAM). This is done by creating a user identity store in OAM. You can create a new user identity store by navigating to the configuration tab and selecting User Identity Store. Select new below OAM ID Stores to create a new OAM Identity store configuration.  You will be greeted by a screen like the one below. This is actually a screenshot of my working configuration, so you can use this as a template.

It is a relatively straight forward list of parameters, but there are a few things you need to take into account:

– The Store name and user search base cannot contain spaces. This will throw errors when using the configuration to authenticate a user. It is a known bug.

– The User Filter Object Classes can be used to narrow down the search result of the search operation. This can make a big difference in large scale environments. The same goes for the Group Filter Classes.

– Cache size. This is always  a consideration, I have left them in the default position as this is a test environment. Your mileage may vary if you use the same configuration.

-Also if you click the test button and it gives you an error, it can be anything, the error is most of the time misleading! I have had the system say that the user filter was wrong whist the login ID attribute was not correct for instance.

Step 3: Create an authentication module.

The next step is to map the new AD connector to an authentication module. This module or chain will be used to search for the user and check their password. For this example we are going to use a pre-defined LDAP authentication chain as this will include all the necessary steps for LDAP based authentication.

The creation of the authentication module is quite simple, select the create button on the Authentication Module page and select the create LDAP authentication module. The next screen will prompt you for a name and store. The store should be the one which was configured in the previous step. Next you can give it a name which will be used in the next step.

Step 4: Create an authentication scheme.

An authentication scheme is basically a mapping from the user inputs to the authentication module.  You typically select an authentication mechanism like forms based or x509 based authentication and an authentication module as defined in step 3. For AD I configured this in the following fashion:

I opted to use the default LDAP login screen used in forms authentication. You can change this form, but for the raw functionality it is not important.

Step 5: Apply the authentication scheme.

The last step is to use the new functionality to secure remote applications. I have opted to secure a default IIS installation with oracle webgates 10G. How to install this I will explain later in a blogpost but for now, it is important to understand that the authentication schemes are applied to an application domain as defined in OAM. You have to imagine an application domain as a collection of urls, or resources, which make up a web application.  This can be useful when you have an application which has a public page and a private page. In my example I have created an application with both a public and a private set of pages:

I will exclude the public pages form authentication whilst the secure pages are protected. So let’s investigate what is going on with the secure part of the website. The secure part of the website is secured by an authentication policy and an authorization policy. The main difference in these policies is that the authentication policy will require you to log in to the application whilst the authorization policy will check after logging in if you are allowed to see the resource. So in order to have users log into this application using AD we need to update the protected resource authentication policy. This is done by selecting the authentication policies tab and clicking the protected resource policy.  This will put you on  this page:

As you can see, I just set the AD authentication scheme, and off we go.

Result:

As a result we can see that the user is prompted for a username and password hen trying to browse to the secure part of the website. The credentials which the user enters are checked by AD and if correct, the user is granted access to the page.