How to develop custom auth module

Jun 2

NOTE: if you’re looking for a quick way to learn how to develop auth modules, then you may want to read this or this instead.

In the OpenAM world an authentication module is responsible for authenticating a user, but sometimes the method of authentication is not that simple, as we think. For example the OpenAM gives out-of-the-box support for LDAP, Cert, SPNEGO token, etc. based authentication, but what happens if you need to authenticate (for some reason) from a WebService, this is when you’re probably going to end up developing a custom authentication module.

OpenAM is using JAAS, so if you don’t know what JAAS is, probably you need to read this, this is going to help you understand the basic concepts of the Auth API.

To create an authentication module, you’re going to need the followings:

Configuration-UI descriptor XML with localization
Callback-descriptor XML for login page UI
Some java code for authentication logic
maybe some JSP
and lot’s of lot’s of OpenAM container restarts

So based on these needs I’m going to write a few more posts in this area, probably in the following structure:

Configuration basics
- Config UI elements
- Validation of configuration
Login UI basics
- Callbacks
- Dynamic Callback-handling
How to write the Java code
Gotcha’s, best practices
How to install auth module

I hope you will find these articles useful, some of them are new stuff for me too, so it may going to need some time to write them, but they’re going to (Forge)ROCK!

auth module, jaas, tutorial

Comments

SW

February 1st, 2011 at 8:21 PM

Is there any concise documentation for creating a custom auth module? I went to the links, but they don’t describe as much as I think I need.

I know I have to implement AMLoginModule, but what happens in each method? And what is the thread of execution to call my implementation?

I’m sure the docs exist, I’m just having trouble finding them.

Thanks.
aldaris

February 2nd, 2011 at 1:03 AM

Yes, there is such documentation, the OpenSSO developers guide covers it the best:
http://download.oracle.com/docs/cd/E19681-01/index.html
Mark

March 2nd, 2011 at 9:55 PM

So I’ve been over and over all this documentation, both FR and Oracle, but I don’t see the answer that I’m looking for. I have OpenSSO set up performing CAC Auth. The customer is requiring a usage agreement page with each successful authentication. Basically a “Here’s the proper use of this data” check box. If the user doesn’t agree, then they are NOT authenticated, if they agree they are good to go. Am I building a “Agreement” authentication module and adding it to the chain, or should I approach this in some other way? Best practices are a bit lacking in this area. – Thanks
aldaris

March 3rd, 2011 at 9:49 PM

The problem with the authentication module is, that it’s not going to be displayed again after the user is logged in and the user goes to other applications. But if you have to get the user agreement after the first successful authentication then a custom module should do the trick.
Ruwei Liu

March 9th, 2011 at 4:12 AM

I’m trying to figure out a solution that can invoke my custom PAP with additional parameters via an API call. The custom PAP will need those parameters to do its tricks. The problem here is that it seems if I invoke the PAP via OpenAM RESTFul API, no matter how many query parameters I set, it won’t get passed to the PAP. Any idea?

I’m now writing a custom authentication module, and hope the custom authentication module could save the API call’s query string. Will it serve my purpose and how does it work? i.e, what should I do to get it done? Please kindly shed some light. I’m new to this area and J2EE.
aldaris

March 9th, 2011 at 11:52 AM

If you try to log in with the REST API, then the HttpServletRequest/Response objects will be null. What you can do is you can call AMLoginModule#setUserSessionProperty(String, String) and you can access those Session properties from your PAP with SSOToken#getProperty.
Hope this helps.
Ruwei Liu

March 10th, 2011 at 12:15 AM

Thanks a lot, this really helps. There’s just one more question: How can I invoke my custom authentication module by a straightforward Http request, just like the REST api? I tried this:

http://:/opensso/identity/authenticate?username=u1&password=Pass123&uri=realm%3D%2F%26service%3DmyService&additionalParam=value1

after deployed my custom authentication module and created a service that use the module to authenticate. And it simply returns:

================================================================
HTTP Status 401 – exception.name=com.sun.identity.idsvcs.InvalidCredentials

type Status report

message exception.name=com.sun.identity.idsvcs.InvalidCredentials

description This request requires HTTP authentication (exception.name=com.sun.identity.idsvcs.InvalidCredentials ).
===================================================================

I’d like to see that my custom authentication can interact with a remote client application without UI…

Appreciate your help very much.
aldaris

March 18th, 2011 at 4:46 PM

This extra parameter will not work with the REST API nor with a DAS setup, I think you should find another way to pass extra parameters to authentication modules.

aldaris' blog