Multiple authentication mechanism chaining in OAM

Authentication mechanism chaining

Since the inception of OAM 11g, we have been talking about authentication scheme chaining and being able to invoke multiple authentication schemes in sequence or invoke an authentication scheme based on some condition. This has been made possible since OAM R2PS2 release with the introduction of authentication status. You can PAUSE authentication process to interact with the user and resume authentication once the interaction is over. However this is all done from within one authentication module by chaining multiple authentication plug-ins instead of chaining authentication schemes. post I use this technique to implement a “user chooses the authentication method” use case described below.

Use case

When user accesses a protected resource, user should get a drop down box with all the authentication mechanisms supported. The user will choose one of the authentication mechanisms depending on user’s convenience of using certain authentication mechanism.  Here is the request flow.

  1. 1. User accesses a protected resource.
  1. 2. The user is redirected to authentication mechanism chooser page where he will get a drop down box with all the authentication mechanisms supported. The user will choose one of the authentication mechanisms from the drop down box and submit the choice.
  1. 3. A custom authentication plug-in (Authentication Chooser plug-in) reads user choice and depending on authentication mechanism chosen, the user is redirected to respective credential collector page by credential collector plug-in. Each authentication mechanism has to invoke different credential collector plug-in. This is accomplished by authentication plug-in orchestration in the authentication module. Ex: If user chooses FORM based login, then the custom plug-in will return SUCCESS otherwise it will return FAILURE. Based on SUCCESS and FAILURE, you can orchestrate respective credential collector plug-in. This works fine when there are just two authentication mechanisms supported. If there are more, then FAILURE has to invoke one other custom authentication plug-in. You will need N-1 (‘N’ is the number of authentication mechanisms that are supported) custom authentication plug-ins to redirect user to respective credential collector plug-ins.
  1. 4. User is now challenged for chosen credentials by credential collector plug-in. When user is challenged for credentials, Authentication context status is set to PAUSE.
  1. 5. When user submits credentials with authentication context (OAM_REQ cookie), OAM resumes authentication from the next plug-in in sequence. The next plug-in in sequence has to process those credentials.
  1. 6. If those credentials are correct, then a credentials processing plug-in returns SUCCESS and user is redirected to protected resource that the user intended to access.

There are two aspects of the implementation that are different than just FORM or Kerberos authentication process. One of them is the need of custom authentication plug-in and the second one is plug-in orchestration in authentication module.

Authentication plug-in orchestration

Here are all the steps involved in authentication in sequence along with some description, plug-in name, Is it custom plug-in or Out-Of the Box plug-in. Diagram below the table shows orchestration of the plug-ins.


Step Name

Plug-In Name (OOB/Custom)


ChallengeChoice CredentialsChallengePlugin (OOB) This plug-in will forward Authentication request to Authentication chooser page that shows drop down box with all the authentication mechanisms supported.
AuthSelector (Authentication chooser plug-in) CustomAuthSelector (Custom) This plug-in will read user choice and return SUCCESS or FAILURE as described in the last section.
ChallengeForCreds CredentialsChallengePlugin (OOB) This plug-in will forward the request to login form.
ValidateUser UserIdentificationPlugin (OOB) This is UserIdentificationPlugin to search the user
ValidatePassword UserAuthenticationPlugin (OOB) This is UserAuthenticationPlugin that validates the password
ChallengeForToken CredentialsChallengePlugin (OOB) This plug-in is invoked when user chooses Kerberos authentication. It redirects user to Kerberos credentials collector page.
ReadKerberos KerberosTokenReader (Custom) This plug-in reads Kerberos token from HTTP header and adds it to OAM credentials object.
ValidateToken KerberosTokenAuthenticator (OOB) This plug-in reads Kerberos token from OAM credentials object and validates it.
KerberosUserIdentification UserIdentificationPlugin (OOB) This is UserIdentificationPlugin to search for the logged in user in LDAP.




As I mentioned before, if there are N authentication methods to support, you will need N-1 custom authentication plug-ins to process user choice and route to respective credential collection URL. Below example shows authentication plug-in orchestration to support 3 authentication methods using two custom authentication plug-ins as highlighted. One other interesting observation or guideline so to say is, there are three successful orchestration completions one for each authentication method supported.



Authentication plug-ins used

Credentials challenge plug-ins

CredentialsChallengePlugin is Out-Of the Box plug-in used by ChallengeforCreds, challengeForToken and challengeChoice steps in the flow. challengeforCreds and challengeChoice steps forward the request to respective login pages as shown in the screen shot below. However challengeForToken step redirects the request to Kerberos challenge URI. Kerberos challenge URI is,


/oam/CredCollectServlet/WNA is OAM Out-Of the Box Servlet that challenges user for Kerberos token.

Please note that URI contains request_id query parameter. The value is {KEY_REQUEST_ID}. This is required to carry forward same authentication context. I have to pass this on because this is HTTP redirect request and HTTP being state less protocol, will lose that information if I do not pass it. However in case of challengeForCreds, because it is HTTP forward request, the login page will get it without me passing it as query parameter.

One other credentials collector supported by OAM is, x509Certificate. Below is the URL for x509 certificate credentials collector if you need to support that authentication mechanism as well.








Authentication chooser plug-in

You have to read authentication method chosen and return either success or failure as shown in the sample code below. Please note that I am also reading for request_id and returning error if I do not find it. What that also tells you is, authentication chooser login page should read request_id and pass it as hidden FORM parameter just like you do in the custom FORM login pages.


KerberosTokenAuthenticator plug-in

KerberosTokenAuthenticator plug-in validates Kerberos token. It is Out-Of the Box plug-in. It reads Kerberos token from OAM credentials object and validates that using keytab.


KerberosTokenReader plug-in

KerberosTokenReader is one other custom plug-in in the sequence. When user submits Kerberos token, the next step is to validate token. KerberosTokenAuthenticator is Out-Of the Box plug-in that can validate the token. However it looks for Kerberos token in OAM credentials object while user submits the token as Authorization HTTP header. So KerberosTokenReader reads Kerberos token from HTTP request and adds that into OAM credentials object as shown below.


Similarly X509CredentialExtractor looks for X509 certificate in OAM credentials object. If you are planning to use that within the flow, you will have to write X509CertReader plug-in that reads certificate from HTTP request and adds that into OAM credentials object with “PluginConstants.KEY_CERTIFICATE” as the key. Or you can make generic plug-in to read source (HTTP Request), destination (OAM Credentials) and object (Negotiate header) from plug-in configuration and moves the object from source to the destination.

User Identification Plugin

This is again Out-Of the Box plug-in that reads user information and searches for the user in LDAP.

User Authentication Plugin

This plug-in is used for FORM based login. The plug-in validates user password by binding to LDAP with user DN that it gets from previous plug-in in the sequence (UserIdentificationPlugin) and user password.


There are many more such use cases that can be solved with this approach. In this case, we relied on end user to choose what authentication mechanism (s)he wants to use. We could as well read whether or not user is in the domain and challenge for kerberos else challenge for FORM login. One other use case is to check if user is using mobile device or desktop and change authentication mechanism based on that. FIDO is gaining popularity. We can check if device supports FIDO authentication. If it does then challenge for FIDO authentication, else challenge with login FORM.


  1. ravikishore dammalpati says:

    Hi Team,

    I am protecting multiple resource with OAM11g webgates, for the resource protection we are using WNA. I am able to all the operations when I try to access the individual application, But if I try to access the 2 application at time in IE browser my both application sessions are closed at time.

    Can you please help on this, how to resolve this issue.


  2. Does the Authentication Choser plugin work through DCC

    • Kiran Thakkar says:

      Hi Paresh

      Authentication chooser is not a plug-in in itself. It is use case implemented using multiple plugins as mentioned in the blog post. Yes, the use case works with DCC as well. Authentication scheme and module would look different in case of DCC though.

      Kiran Thakkar

  3. Kiran Thakkar says:

    Hi Aakash

    Yes you can use OOB TAP* plug-ins to create DAP authentication module. That is what one of the client I worked with used when they had to delegate authentication to third party service.

    On your second question, WNA servlet only challenges the user and collects kerberos token from the user. After that, OAM controller should have read authorization header and added that into credentials context. That is what happens in case of OOB kerberos scheme or when you create custom kerberos authentication module using KTI (KerberosTokenIdentifier) , KTA (KerberosTokenAuthenticator), and UserIdentificationPlugin (UI) authentication plug-ins. However it did not work in this use case and I think that is because my authentication scheme is of type FORM and not WNA.

    Kiran Thakkar

  4. Aakash Wasnik says:

    Hi Kiran

    Thanks for informative blog. I have couple of follow up questions

    1. TAP Authentication scheme uses “DAP” authentication module. Can we use OOB TAP* plugins to create DAP authentication module using orchestration flow (LDAP module can be created using UserIdentification & UserAuthentication Or Kerberos module as combination of KTI,KTA & UserIdentification )

    2. In above example for kerberos authentication WNA servlet is invoked to collect Kerberos token / Authorization header Would WNA servlet not set kerberos token / authorization header in credential context for KTA plugin to pick up If OOB KerberosPlugin (with orchestration flow) is used for kerberos authentication only KTI (KerberosTokenIdentifier) , KTA (KerberosTokenAuthenticator) , UserIdentificationPlugin (UI) is needed , custom plugin such as KerberosTokenReader is not needed


Add Your Comment