Monday, January 25, 2010

Integrating Oracle Access Manager with Kerberos authentication with fallback to an HTML form

Seems like it's the month of Kerberos.

We often see customers wanting authenticate users to Oracle Access Manager (OAM) with Kerberos, and fall back to HTML forms if the Kerberos authentication fails. There's an easy way to set this up, but it's not obvious how to do it.

I'm just going to describe the flow here, but that should be enough to help you figure out how to do the actual knob turning yourself. If you run into trouble feel free to ask a question here.

  1. user accesses
  2. OAM redirects the user to
  3. on trustedmachine the virtual directory /oamauthenticator/ is protected by IIS' built in Kerberos functionality, and only Kerberos. In other words you should uncheck the Basic, Digest and Anonymous checkboxes in the IIS console.
    If the user's workstation is in the domain and they are signed in then their identity will be passed to IIS via Kerberos. If the user's worksation is not in the domain or something goes wrong they will be presented with the 401 error page (see below)
  4. the OAM WebGate will consume the identity from IIS and pass that identity to the Access Server
  5. the OAM Access Server will search LDAP for the user
  6. once the user's OAM session has been established they will be redirected back to along with the ObSSO cookie.

alternative flow for workstations not in a domain or if Kerberos fails:
In step 3 if the Kerberos authentication fails IIS will send the HTML file configured as the 401 page

You can create a plain HTML page that

  • contains a conventional OAM login form - prompting the user for their username and password.
  • submits to an URL on trustedmachine
  • that URL will be associated with a conventional OAM HTML forms login authentication scheme

When the user fills in the form and hits submit:

  1. the credentials will be passed to the Access Server
  2. the Access Server will search LDAP for the user and bind to the directory to authenticate them
  3. if the credentials are correct the user will get an OAM session cookie
  4. the user will be redirected back to the original resource as in the normal flow above.

The only real trick here is using the custom error page in IIS. Remember that you have to use a plain HTML file for that file - you can't use an ASP/ASPX. That also means that you have to do anything dynamic in JavaScript.

Update: I fleshed this out some more in a newer post.


  1. Chris,
    Thanks for this - just what I was looking for however....
    I have an existing authentication scheme that uses forms auth and would like to add Kerberos in front of this. If I follow your steps above then I still get the Form login page even when I have a valid ticket and have added the login URL to my trusted sites.

    Any further help would be greatly appreciated.



  2. Bernie:

    Your use case is a little harder to do automatically. The problem you're facing is one of the limitations of the HTTP specification.

    Basically what happens when you access a URL that is protected by Kerberos is that your browser says "please give me this file" and in response the server says "No (401). Try again with a Kerberos ticket". If your browser knows how to 'do' Kerberos it automatically resubmits the request with the Kerberos ticket and everything proceeds as normal.

    Which suggests that it can't be done.

    But it CAN.

    What you do is tweak the 401 error page that goes back to the browser when the server says "gimme a Keberos token". IIS normally sends a really simple page back that just says something like "authentication required". If you customize that page you can use JavaScript to kick off an OAM HTML forms login or even turn it into an OAM HTML forms login page itself. I'd lean towards the former since you probably already have the HTML login pages setup somewhere else.

    Hope this helps!

  3. Bernie,

    I recently had cause to set this up and the instructions above are incomplete. There's a new post up at that goes into more detail and covers the problems I had.

  4. Have you done this on 11g OAM? I am trying on windows 2003 server with AD but it prompts for basic authentication. Any doucumnet to do this.
    Ofcourse the document in the oracle documents is not good enough. I tried the steps in that and ended up with username password basic auth prompt.


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