Best Practices from Oracle Development's A‑Team

Multiple authentication mechanism chaining in OAM

Kiran Thakkar
Consulting Solutions Architect

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.

Join the discussion

Comments ( 1 )
  • Manish Friday, May 10, 2019
    Hi Kiran- Thanks for excellent article! It really helped us a lot in our project.

    How should we set X509 certificate the OAM Credential Param object. Can you share code snippet on how you are setting PluginConstants.KEY_CERTIFICATE
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content