Thursday, October 6, 2011

Understanding OAM Authentication Schemes, Modules, Step Orchestration, and Plug-ins

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.

I've been working on a post about plugging your own code into Oracle Access Manager (OAM) to "do" user authentication. Before I get to that post I thought it would be a good idea to explain all of stuff between when OAM collects a credential (for example a username and password entered on an HTML form) to establishing an authenticated session.

In OAM 11g the whole authentication flow from credential collection through session establishment is configurable by you the administrator, 99% of the time without needing to write a single line of code or by scripting anything. Out of the box OAM 11g ships with a bunch of sensible Authentication Schemes prewired for you which you can change or adjust to suit your needs. OAM also allows you to add additional Schemes or even upload your own code to do authentication your own special way.

To help you understand the process and terminology I'm going to start at the bottom and work my way up.

The lowest level component of the process is an Authentication Plug-in. An Authentication Plug-in encapsulates a single chunk of work, for example looking up a user based on their username, or checking the user's password against an LDAP directory.

Each plug-in does one very small thing, so you string some set of Authentication Plug-ins together to create an Authentication Module. The Authentication Module allows you to select one or more Authentication Plug-ins, each of which becomes a "Step". Then you configure Step Orchestration which is where you tell OAM which order to call those steps and what to do if each of those steps succeeds or fails.

For example the LDAP Authentication Module (the one used when you enter a username and password) has two steps:

StepUI is an abbreviation for User Identification (not User Interface!)
StepUA is an abbreviation for User Authentication.

And they are Orchestrated so that StepUI goes first and if that succeeds then StepUA follows. Here's what that looks like in the GUI:

Since a picture is worth a thousand words let's translate that into a flow chart:

OK, so what do we have so far?

A Plug-in does some work.
A Mechanism strings those Plug-ins together as steps and defines how they work together.
All that's left is a way to actually get the credentials from the user. To do that you have to define an Authentication Scheme. An Authentication Scheme has a few settings:

  • Name and description
  • Authentication Level - a number used to sort the schemes in order of most secure to least secure
  • Challenge method - what kind of credentials and how does OAM collect them?
  • Authentication Module - which authentication module is used to authenticate the credentials?
  • a few other scheme-specific fields

This is what the Authentication Scheme looks like for LDAP:

And that's it!

When a user tries to access something protected with this scheme they'll have to enter their username and password into an HTML form. That data goes into OAM which calls the User Identification plug-in to locate the user in the directory, then the User Authentication plug-in to check their password against the one in the directory. If both of those steps succeed then they get an authentication session (for their DN) with a level 2.

I tried to draw a picture showing the relationship between these constructs. This is the best I could do:

Did this help?


  1. Hi Chris,

    Thanks for the post. I have a question. Is it possible to prevent the authentication using OAM 11g for disabled users in OID 11g? I could not find it anywhere in the documentation.

    Please help.


  2. Hi Mahendra. Yes, out of the box OAM will block disabled users from logging in. In fact OAM didn't technically need to do anything special to do that since OID will reject any ldap_bind requests for a user that is disabled.

    OAM does have special logic embedded so that it can detect when a user's account is disabled in order to display a friendly error message to the end user.

  3. Hi Chris,

    Can we change the Authentication level for LDAP Scheme from 2 to 1. What will be the implications if we change it from default 2 to 1.

    Thanks in advance.


  4. Nagesh: You can change any of the levels of any of the schemes. The levels simply tell OAM which schemes you trust more than the other schemes. For example you might configure x.509 certificate as level 5 and LDAPScheme (normal username and password) as level 2. If a user were to access the x.509-protected resource first and then go to the LDAPScheme-protected resource OAM would not prompt them for their password. But if they went the other way around (LDAP first, x.509 second) they would be prompted for the higher level credential when they tried to switch.

    Hope this helps


Note: Only a member of this blog may post a comment.