Part 3: OAM11g WNA Identity Store Considerations and Configurations

This post is part of a larger series on Oracle Access Manager 11g called Oracle Access Manager Academy. An index to the entire series with links to each of the separate posts is available.

This is the final post of a three part series.  In "Part 1: Under the Covers of OAM11g WNA integration with Multiple AD Forests", I covered the flow of how WNA works and what was going on behind the scenes, and in "Part 2: How to Configure OAM11g WNA for Multiple AD Forests", I went into detail on how to configure WNA.  In this final post I am going to go over what I think would be two of the most common scenarios that the OAM11g Identity Store would be used for WNA, and how it impacts the Kerberos authentication module configurations.

What’s spinning under the Identity Store covers?

If you were to turn on the OAM11g Server logs to trace level, and tail the log as a User would authenticate using IWA, you would find a point in the log where the OAM Kerberos authentication module sets the LDAP filter configured in the UserIdentificationPlugin as shown in the example log below.  This basically shows exactly what we set the plugin parameter to in the stepUIF, which was defined in the authentication module.

[2013-02-16T21:03:29.944-06:00] [oam_server1] [TRACE] [] [oracle.oam.plugin] [tid: [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: <anonymous>] [ecid: 4aaf7073ad441920:-3df584f4:13ce5e02606:-8000-00000000000002c4,0] [SRC_CLASS: UserIdentificationPlugIn] [APP: oam_server] [SRC_METHOD: process] Un-processed LDAP Filter is (uid={KEY_USERNAME })

Then as we continue to tail the log you would see a couple methods populate the actual search base and LDAP filter.  The LDAP filter includes a value {0}, which is the first array that gets populated with the user’s principal name or userPrincipalName value depending on how you configure the parameter; more on that later.

[2013-02-16T21:03:29.949-06:00] [oam_server1] [TRACE] [] [oracle.oam.user.identity.provider] [tid: [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: <anonymous>] [ecid: 4aaf7073ad441920:-3df584f4:13ce5e02606:-8000-00000000000002c4,0] [SRC_CLASS: oracle.security.am.common.jndi.ldap.proxy.DirContextProxy] [APP: oam_server] [SRC_METHOD: invoke] Arg = forest1,dc=example,dc=com
[2013-02-16T21:03:29.949-06:00] [oam_server1] [TRACE] [] [oracle.oam.user.identity.provider] [tid: [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: <anonymous>] [ecid: 4aaf7073ad441920:-3df584f4:13ce5e02606:-8000-00000000000002c4,0] [SRC_CLASS: oracle.security.am.common.jndi.ldap.proxy.DirContextProxy] [APP: oam_server] [SRC_METHOD: invoke] Arg = (&(uid={0})(objectclass=inetorgperson))

Finally following the previous authentication events, if you were to also tail the debug log of the Identity Store of choice, we would see the actual search.  For example the following is an OVD diagnostic log, you can see the final LDAP search parameters that have been translated into something the LDAP server would understand.  Highlighted in bold you can see the same searchbase and search filter, which would then retrieve the user entry and everything would be golden.

[2013-02-16T21:35:51.439-06:00] [octetstring] [NOTIFICATION] [] [com.octetstring.vde.chain.plugins.DumpTransactions.DumpTransactions] [tid: 39] [ecid: 4aaf7073ad441920:-3df584f4:13ce5e02606:-8000-000000000000031e,0:2] !SEARCH Operation: (Transaction#Adapter_Forest3.Dump After.11)[[
BindDN: cn=orcladmin
Base:   dc=forest1,dc=example,dc=com
Scope:  2
Filter: (&(samaccountname=tim.melander)(objectclass=user))
TypesOnly:      FALSE
Attrs:  [mail, cn, description, orclguid, objectclass, displayname, uid, samaccountname]!
]]

The reason I went over all this is to build an understanding of what is happening during the WNA authentication.  Now we can come up with a couple of what I think are the most common scenarios to map the Identity Store to the backend user data, whether that be OVD or another LDAP store, and map the correct configurations needed for the OAM11g custom Kerberos authentication module UserIdentificationPlugin.

OVD or Not OVD, that is the Question?

Believe it or not, you can either use OVD or another LDAP store for WNA; really.  Before we get into it, I want to give a quick primer on OVD for those that have not heard of it.  OVD is an acronym that stands for Oracle Virtual Directory, and the title literally means what it says.  Basically in a nutshell OVD is an Oracle Middleware product that uses adapters, among many other things, to aggregate backend data into a unified front end LDAP store.   If interested, you can find out more details about OVD at the Oracle Technology Network under Identity Management titled Oracle Virtual Directory.

In Part 1 and Part 2 of this series you may have noticed I used OVD because I wanted to aggregate three Active Directory forests into a single unified LDAP store, which was then used by the OAM11g custom Kerberos authentication module.  The reason for this is that I can only define a single Identity Store because of how the steps in the authentication module plugins have to be orchestrated.  You can see the dilemma, if I did not have OVD in this case I would be stuck going against a single Active Directory domain.

Another reason I used OVD, was that I took advantage of a plugin parameter I mentioned in Part 2 named {KEY_USERDOMAIN}, which was used in the UserIdentificationPlugin to grab the User’s logged in domain to dynamically set the User’s specific searchbase namespace in order to deal with duplicate samAccountNames across multiple forests.  If you are savvy to OAM11g custom authentication modules you will probably tell me, wait a minute, you could chain several steps with separate UserIdentificationPlugins where each step could be defined with unique Identity Stores.  Sorry, not really, in this case the way the Kerberos authentication module works, things do not work as you would expect.  I know, because I tried it.

Now let's talk about alternate Identity Stores other than OVD.  Say your Enterprise provisions a subset of data from all your Active Directory domains into a single external Non-Microsoft Enterprise Directory Server store.  OAM11g WNA could actually take advantage of this LDAP store and use it to search for the Users instead of using OVD.  Why, because after the OAM11g custom Kerberos authentication module gets through validating the Kerberos ticket, validating the service principal against the Microsoft KDC server, and extracts the data needed to build the searchbase and search filter I mentioned previously, all that is remaining is to look up the User in an LDAP store.  As long as all the Users happen to be in a single Enterprise Directory Server store, that LDAP store would qualify as an Identity Store that would work for this WNA solution.  Pretty cool right?

So if you know that all Active Directory Users are provisioned to a single Enterprise Directory Servers store, then good for you, this is the Identity Store you may want to use in OAM11g.  However if this is not true, then OVD11g is the way to go.  I know each client has very unique needs because of a list of reasons, so I hope one of these two options meet the majority of the people out there wanting to use this solution.  So enough fluff, let’s get into the weeds!

Using OVD as the Identity Store

This article will not get into the details of how to configure OVD in order to map all your Active Directory forests into a single LDAP store, but I do want to cover a few considerations on correctly designing the DIT (Directory Information Tree).  I want to leverage the straw man I used in Part 2 and describe it in the following DIT diagram.   At the top you have the rootDSE context, and under that you have three sub branches, each sub branch is configured with an adapter that references a forest.  What is critical is the structure of the DIT.

In the above example let’s say the user’s fully qualified user principal name is alfred.carson@forest2.example.com.   We already mentioned that when the user logs in via WNA, the OAM authentication module uses the @forest2.example.com to dynamically set the searchbase using the {KEY_USERDOMAIN} parameter value.  So in this case the searchbase would be set to dc=forest2,dc=example,dc=com.  As long as this searchbase matches up to our DIT, OAM will easily find the user, and in fact find the unique user across multiple forests even if there is another alfred.carson in say Forest3, because their location would be under the dc=forest3,dc=example,dc=com, a completely different namespace.  As you can see, defining the DIT becomes important to making this all work.  So the key to remember is that your OVD DIT must be designed in a way that maps back to how OAM WNA would set the searchbase used from the User's domain.

OVD Adapter Mapping Considerations and OAM11g Plugin Configurations

Using OVD involves one or many adapters.  There are several types of adapters and each one will either transpose and map attributes or do a straight pass through.  For example in Part 2, in my configuration, I used the OAM/AD Adapter with Mapper, which maps inetOrgPerson class attributes to Active Directory; e.g. uid would translate to samAccountName.  However if I had used the Active_Directory adapter, OVD would present samAccountName on the front end and pass it straight through to Active Directory as samAccountName; nothing would even change.  Therefore, the type of adapter you choose will greatly change the values used for the KEY_LDAP_FILTER parameter.  The following table shows just a couple examples, but you should at least get the idea.  If your requirement is different, then modify the values as needed.

OVD Adapter	OAM11g stepUIF Plugin Parameter	Recommended Value
OAM/AD  Adapter with Mapper	KEY_LDAP_FILTER	(uid={KEY_USERNAME})
Active_Directory	KEY_LDAP_FILTER	(samaccountname={KEY_USERNAME})

Using an Enterprise Directory as the Identity Store

As I mentioned earlier if all of the Active Directory users are provisioned into a common Non-Microsoft Enterprise Directory Server store, then using an Enterprise Directory Store may work.   However, not so fast, there are three requirements for this to work.

1. OAM11g must support your version of the Enterprise Directory Server as an Identity Store; see the OAM11g certification matrix to verify.
2. The value OAM11g searches needs to be either the samAccountName or the userPrincipalName because these are the values the Kerberos authentication module extracts from the User’s Kerberos ticket.
3. Finally the value that is searched in the Enterprise Directory Server store must be unique across the DIT, or at least the point at which you define the starting search base namespace otherwise the authentication would fail if there were a duplicate username.  

Requirement 2 is important, so let me elaborate.  The OAM11g custom Kerberos authentication module extracts the principal from the Kerberos ticket; I point this out with example logs in Part 1.  Let’s take for example Alfred Carson logs into the FOREST2 domain with the username alfred.carson; his userPrincipalName would look like alfred.carson@forest2.example.com.   The following table explains some possible options you could use for the stepUIF plugin parameter explained in Part 2.  As a reminder the stepUIF is one of the module plugins called UserIdentificationPlugin, which has three optional parameters, 1) KEY_LDAP_FILTER, 2) KEY_SEARCH_BASE_URL, and 3) KEY_IDENTITY_STORE_REF.  The following table relates to the values that could be used for the KEY_LDAP_FILTER parameter.

KEY_LDAP_FILTER Parameter Value	Value Extracted by Plugin used for Search
{KEY_USERNAME}	alfred.carson
{KEY_USERREALM}	forest2.example.com
{KEY_USERNAME}@{KEY_USERREALM}	alfred.carson@forest2.example.com

So extrapolating from the parameters shown in the table above, let's say one of the values that is provisioned from all the Active Directory servers is the userPrincipalNames, which is then populated for each entry in your Enterprise Directory Store.  Then say the value is stored in the attribute “userprincipalname”.  You could use then use the following KEY_LDAP_FILTER parameter value as follows.

(userprincipalname={KEY_USERNAME}@{KEY_USERREALM})

If the same attribute in your Enterprise Directory Store is “uid” instead, then modify the plugin parameter as follows.

(uid={KEY_USERNAME}@{KEY_USERREALM})

So if we go with the above parameter value, then OAM11g would pass the search to the LDAP Identity Store as follows.

(&(uid=alfred.carson@FOREST2.EXAMPLE.COM)(objectclass=user))

As you can see making some tweaks to the parameter value could meet the needs of your Identity Store.  However before we get to excited, we still need to set the search base.

Defining the Search Base Statically or Dynamically 

If you remember in Part 2 we had a plugin parameter in stepUIF called KEY_SEARCH_BASE_URL, and we used a value {KEY_USERDOMAIN}.  If we stayed with this parameter value it would use the User’s domain realm, forest2.example.com, and dynamically set the search base to dc=forest2,dc=example,dc=com.  When I talk about using OVD as the Identity Store, this would be a good thing.  However, what if we did not want it to search there because we are using our Enterprise Directory Server store instead?  Then leave the KEY_SEARCH_BASE_URL parameter value blank, and define the search base for the Users in the OAM11g Identity Store that is used for the custom Kerberos Authentication Module; remember the KEY_IDENTITY_STORE_REF parameter?  For example going with the Enterprise Directory Server DIT shown in the previous diagram, you could set the starting search base to “ou=employees,ou=internal,dc=example,dc=com”, and OAM11g would start the search there for the user.

Below is a table that shows the possible KEY_SEARCH_BASE_URL  parameter values for the UserIdentificationPlugin.  We can use the User alfred.carson@forest2.example.com as an example and see what happens.

UserIdentificationPlugin Parameter	Parameter Value	Plugin Result
KEY_SEARCH_BASE_URL	{KEY_USERDOMAIN}	dc=forest2,dc=example,dc=com
KEY_SEARCH_BASE_URL	<leave this blank>	<Uses the assigned Identity Store searchbase>

Summary

I have covered this topic pretty throughly, at least I hope to a point it will be useful for anyone.  My goal was to show the power of the custom Kerberos authentication module, and how flexible this solution can be by simply making some modifications to meet many needs.  I also hope both options for Identity Stores presented in this last part meet the majority of what people would use in a real world deployment.  I wish the best for anyone trying this solution, and I hope it helps with great success in your OAM11g WNA implementation.