Using a custom login module with JDev 10.1.3

There's been a lot of traffic on the JDeveloper Forum in the past few days about custom LoginModule's both inside of JDeveloper's embedded OC4J and in OC4J standalone. After trials and tribulations, I've got it working in both places, and wanted to share the "how to" with others, so here goes...

What is a LoginModule?

A LoginModule is a class specified in the Java security specification that can be used to authenticate users and to assign roles to those users. In my case, I have user/role information stored in a database, so neither of the two Oracle-supplied LoginModule configurations (file-based or LDAP-based) would work for me. So, using the information in this article by Frank Nimphius and Duncan Mills for guidance, I developed my own LoginModule that would use a stored procedure to authenticate against the database. Now, the "fun" stuff starts... how to get this working in the embedded OC4J that comes with JDeveloper 10.1.3?

JDeveloper 10.1.3 Configuration for Custom Login Modules

Please note to replace brackets [ and ] with less-than and greater-than symbols in the following examples

Basically, there's a few simple steps that need to be done:

1. Package your login module up into a jar file. I'm not going to go into any details here, but it's pretty straightforward to use a deployment profile to create a jar file with your login module and all of its dependent classes.
   
   
2. Put the jar file containing your login module into [jdeveloper_home_directory]/jdev/lib. I suppose it could be anywhere, but this is a pretty convenient place for it.
   
   
3. Make sure the embedded oc4j is shut down (go to the "Run" menu, and use the terminate option to shut it down if it's running.
   
   
4. The next thing to do is to ensure that your login module JAR file is visible to the embedded oc4j. The configuration files for the embedded oc4j are in [jdeveloper_home_directory]/jdev/system/oracle.j2ee.10.1.3.36.73/embedded-oc4j/config (at least for the current version as of the date I'm writing this). You need to add a line to the application.xml using your favorite text editor that looks like this:
   
   [library path="C:\o\jdev1013\jdev\lib\TestLogin.jar"/]
   
   (my login module was in a JAR called TestLogin.jar)
   
   
5. The next thing to do is to tell the embedded OC4J to use a custom login module and dynamic roles. In the same application.xml, locate the line that looks like this:
   
   
   [jazn provider="XML"/]
   
   
   and replace it with this:
   
   [jazn provider="XML"]
   [property name="custom.loginmodule.provider" value="true"/]
   [property name="role.mapping.dynamic" value="true"/]
   [/jazn]
   
   
6. The next thing you need to do is to configure the application to use a custom login module. This configuration is done in the system-jazn-data.xml file in the same directory. One thing to note is that the J2EE application name is ALWAYS "current-workspace-app" in the embedded OC4J. Here is the relevant section from my system-jazn-data.xml:
   
   
   [application]
   [name]current-workspace-app[/name]
   [login-modules]
   [login-module]
   [class]john.TestLogin[/class]
   [control-flag]required[/control-flag]
   [options]
   [option]
   [name]application_realm[/name]
   [value]test[/value]
   [/option]
   [option]
   [name]jdbcUrl[/name]
   [value]jdbc:oracle:thin:un/pw@localhost:1521:ORCL[/value]
   [/option]
   [/options]
   [/login-module]
   [/login-modules]
   [/application]
   
   Your login module may have other options, so configure as necessary. My custom LoginModule was "john.TestLogin" and had 2 options: jdbcUrl and application_realm
   
   
7. Configure your application for security as per the J2EE spec. In my case, it was simply adding some stuff to web.xml for my project in JDev.
   
   
   
8. That's it! Now when you run your application from within JDeveloper, it should prompt for a login (you can change the config to use a form instead of the default BASIC authentication)

OC4J Standalone and Oracle AS 10.1.3 Configuration

Fortunately, the configuration with OC4J standalone and Application Server 10.1.3 is much simpler. The enterprise manager deployment wizard actually has some screens to allow you to configure the login module. This process is documented pretty well, but here's a short synopsis:

1. Make your login module JAR file available in the classpath. I did this by editing application.xml (in [oc4j_home]/j2ee/home/config) to include a [library] element (just like for the embedded configuration above.
   
   
2. Deploy your application using the OC4J/AS enterprise manager. When you get to step 3, (Deployment Settings), look what you've got:
   
   
   
   
   
   
   
   
   
   
   
3. Now, you can click to "Select Security Provider" and "Map Security Roles"

I hope this helps those who are struggling with this, as I was.