Skip to end of metadata
Go to start of metadata

There's a more up-to-date version of this page in Chapter 16 of the OpenAM Developer's Guide.

Creating a Custom Authentication Module

Custom Authentication Modules

OpenAM comes complete with a wide variety of built-in custom authentication modules, but sometimes customer requirements step outside the functionality provided by the built-in modules. In these instances, it is time to consider writing your own custom authentication module. The OpenAM developer can use the source of the built-in modules as their starting point or start from scratch. If the customer requirement is a very close match to existing functionality then using a built-in module as a starting point will be a good idea. The OpenAM developer should start from scratch if the customer requirements does not match any of the built-in modules.

In this HowTo we look at how to create and configure custom authentication modules.

Requirements for Sample Authentication module

Our sample authentication module takes username and password as input from the user. This data along with a service specific attribute and the program logic is used to authenticate the user. During this process some errors can occur which will be shown to user in detail. All texts displayed during the authentication must be easily configurable and translatable.

In short - we have following requirements

  • User will be asked for name and password
  • Module has one specific attribute which needs to be configured via OpenAM web-interface
  • The authentication UI is configurable and translatable
  • Some errors have to be displayed to user in detail

Prepare your development environment

We will stick with using the basic complier in this HowTo to keep things simple. In order to compile your custom authentication module either on the command line or in your favourite IDE you will need the following OpenAM jar files.

  • amserver.jar
  • opensso-sharedlib.jar

In addition you will also require the J2EE Servlet API, you can obtain these from within your favourite container or here.

If you are using tomcat

If you use tomcat then you can find the Servlet API files in the TOMCAT_HOME/lib/servlet-api.jar file.

Design your custom authentication module

First important decision is to pick a name for our authentication module. We decide to call our module SampleAuth.

An OpenAM custom authentication module is comprised of the following components:

  • Authentication logic ( which extends the com.sun.identity.authentication.spi.AMLoginModule abstract class
  • Principal ( which implements the interface
  • Callbacks XML file (SampleAuth.xml) which describes the states of authentication logic and the user input needed during those states
  • Service configuration XML file (amAuthSampleAuth.xml) which defines how service is configured on OpenAM side
  • Authentication module properties file (
The Callbacks XML file

The custom authentication module is designed to ask the user a series of questions in order assert their identity. The order and detail of these questions is set out in the Callbacks XML file. The structure of the XML file is defined in the OPENAM_WAR/WEB-INF/Auth_Module_Properties.dtd file.

Re-use, don't reinvent

All of the built-in modules XML files are located in the OPENAM_WAR/config/auth/default directory. The OpenAM developer can use these as a starting point for their own callback XML file.

The custom authentication module

All custom authentication modules must extend from the com.sun.identity.authentication.spi.AMLoginModule abstract class. The abstract methods that must be implemented in the custom authentication module are listed below and the OpenAM Javadoc provides useful reference information.

The init method is called once by OpenAM when the module is created. The process method is called into when the user submits callbacks back via the Authentication interface. The process method determines what happens next in the authentication process; success, failure or the next state (order) in the XML file. The getPrincipal method is called by OpenAM and must return an implementation of the interface.

Authentication Module Life-cycle

OpenAM does not reuse authentication module instances. This means that we can store information specific to the authentication process in the instance.

OpenAM Service and Properties file

The OpenAM administration will require a way to configure any custom authentication modules. OpenAM mandates that all authentication modules; built-in or custom are configured in the same way by means of an OpenAM service. At the bare minimum the service should contain an authentication level attribute.

Configuration Attributes

The module can find the value of these attributes in the options Map passed as a parameter to the init method.

The properties file is a standard Java properties file that contains the description of the attributes that will be displayed in the console.

Implement your custom authentication module

Sample Callback XML file

Simple callbacks file might look like:

This file defines authentication module SampleAuth with one possible state (order 1) in which 2 pieces of information are asked from the user. All strings that are used to draw the UI are typed into this file.

According to our requirements we need a little-bit more sophisticated callbacks file. We need dynamic text and we need error state. Following callbacks file achieves this:

Few comments:

  • We need order 1 with 0 callbacks to change all UI strings for following orders. The trial-and-error shows that this dummy state is necessary to achieve dynamic UI-strings.
  • The placeholders '#FOO BAR#' have no real meaning, this is just to show that those texts get replaced.
  • The order 3 has attribute error set to "true". If the authentication module state machine reaches this order then the authentication has failed. The NameCallback is actually not used and not displayed to user, but the callbacks with length at least 1 is necessary, otherwise the OpenAM won't let us to substitute the header. So it's yet another hack forced upon us.
Sample Module Code

You will notice the code above allows the user "test" to log in with a password of "password".  In order for this to work you will need to create a user called test in the OpenAM administration pages.  This is because the code goes on to retrieve the user profile for the user, and if one doesn't exist, it will be this subsequent step that will fail and prevent you from logging in.   In the OpenAM console, logged in as amadmin, select "Access Control", Top Level Realm, "Subjects" and click "New..."

Here is the code for the principal implementation

Service configuration XML
  • The service must have a name: 'iPlanetAMAuth' + modulename + 'Service'
  • The service must have a description
  • i18nFileName refers to the properties file and i18nKey to the key in the properties file
  • sampleauth-service-specific-attribute configurable via OpenAM is defined here

The 'iplanet-am-auth-sampleauth-auth-level' is the obligatory authentication level attribute. Here naming is very important. The name of the attribute must be: 'iplanet-am-auth-' + lowercase(modulename) + '-auth-level'. If the attribute name does not follow the pattern your authentication module will not function the way you want it to. (There is also a second naming convention - please refer to the source code (wink) )

Properties file

It's a simple properties file. Be careful to match all the identifier.

Compile your custom authentication module

Next we need to compile the custom authentication module.

This will create our class file that we need to install into OpenAM. Next we should package the classes files up into a jar file.

Install your custom authentication module

Copy the jar file

We copy the jar file into the WEB-INF/lib directory within the openam web application deployed into Tomcat.

Copy the service properties file

We copy the properties file into the WEB-INF/classes directory within the openam web application deployed into Tomcat.

Copy the authentication module XML file

We copy the properties file into the config/auth/default directory within the openam web application deployed into Tomcat.

Register the module and the service with OpenAM

Use the ssoadm command to register the service and the module with OpenAM. The service can only be registered with OpenAM using ssoadm.

Note the service definition file is only needed for creating the service. When calling ssoadm create-svc, be sure to pass the full path to your service definition file.

Also following subcommands might be useful to you during the testing: delete-auth-cfgs, delete-auth-instances, delete-svc, list-auth-cfgs, list-auth-instances, remove-svc-realm, show-auth-modules, show-realm-svcs, unregister-auth-module, update-svc

Restart Tomcat

It is a good idea at this point to restart Tomcat (or whatever container you are using) to ensure the Authentication Module and service definition can be loaded.

Configure your custom Authentication module

Log into the Console and navigate to Access Control >> Realm >> Authentication and click New under Authentication modules. Name your module and select the custom authentication module type from the list. Click OK. You should now see your custom module listed, you can select it and configure it as appropriate.

Test your custom module

The final step is to test out your custom authentication module. To do this you just need to login successfully to the realm where the custom authentication module is configured. This URL should do the trick:


You should be presented with the login screen and asked for the credentials required by your custom authentication module.

  • None
  1. Jan 15, 2016

    Updated the Service Configuration XML part as the schema has changed