More, More, More Custom OpenSSO Authentication Modules

OpenSSO Enterprise provides the com.sun.identity.authentication.spi package to write Java-based authentication modules and plug them into the Authentication Service framework, allowing proprietary authentication providers to be managed using the OpenSSO Enterprise console. The authentication module is created using the abstract com.sun.identity.authentication.spi.AMLoginModule class which implements the JAAS LoginModule class.

com.sun.identity.authentication.spi.AMLoginModule provides methods to access the Authentication Service and the authentication module's callback requirements file. Once created, a custom authentication module can be added to the list of authentication modules displayed by the OpenSSO Enterprise console. Use the following list of procedures as a checklist to create and integrate a custom authentication odule into OpenSSO.

  1. Create a callback requirements file for the new authentication module.
    The authentication module's callback requirements file is written in XML and defines the module's authentication requirements and login state information. The parameters in this file automatically and dynamically customize the authentication module's user interface in the form of login pages that provide the means to initiate, construct and send credential requests to the Distributed Authentication User Interface. When an authentication process is invoked, the values nested in the Callbacks element of the module's configuration properties file are used to generate login screens. The module controls the login process, and determines each concurring screen. The callback requirements file included with OpenSSO and the corresponding DTD (Auth_Module_Properties.dtd) can be found in the source code and used as a template for creating a new one.
  2. Implement a Principal class.
    Write a class which implements java.security.Principal to represent the entity requesting authentication. For example, the constructor takes the username as an argument. If authentication is successful, the module will return this principal to the Authentication Service which populates the login state and session token with the information representing the user.
  3. Create a service file for the new authentication module.
    The authentication module's service file is written in XML and imported to OpenSSO to allow the management of its attributes using the OpenSSO console. The name of the service file follows the format amAuthmodulename.xml (for example, amAuthSafeWord.xml or amAuthLDAP.xml). The service files included with OpenSSO and the corresponding DTD (sms.dtd) can be found in the source code and used as a template for creating a new one. You can also cut, paste and modify the following template.
  4. <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE ServicesConfiguration
    PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"
    "jar://com/sun/identity/sm/sms.dtd">
    <ServicesConfiguration>
    <Service name="iPlanetAMAuthMYMODULEAuthService" version="1.0">
    <Schema
    serviceHierarchy="/DSAMEConfig/authentication/iPlanetAMAuthMYMODULEAuthService"
    i18nFileName="mymoduleauth"
    revisionNumber="1"
    i18nKey="iplanet-am-auth-mymoduleauth-service-description">
    <Organization>
    <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-server"
    type="single"
    syntax="string"
    i18nKey="a102">
    <DefaultValues>
    <Value>msg1dev.ec-lille.fr:1389</Value>
    </DefaultValues>
    </AttributeSchema>
    <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-base-dn"
    type="single"
    syntax="dn"
    i18nKey="a103">
    <DefaultValues>
    <Value>dc=ec-lille,dc=fr</Value>
    </DefaultValues>
    </AttributeSchema>
    <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-search-base-dn"
    type="single"
    syntax="dn"
    i18nKey="a104">
    <DefaultValues>
    <Value>ou=people,dc=ec-lille,dc=fr</Value>
    </DefaultValues>
    </AttributeSchema>
    <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-bind-dn"
    type="single"
    syntax="dn"
    i18nKey="a105">
    <DefaultValues>
    <Value>cn=Directory Manager</Value>
    </DefaultValues>
    </AttributeSchema>
    <AttributeSchema name="iplanet-am-auth-mymoduleauth-primary-bind-passwd"
    type="single"
    syntax="password"
    i18nKey="a106">
    </AttributeSchema>
    <AttributeSchema name="iplanet-am-auth-mymoduleauth-auth-level"
    type="single"
    syntax="number"
    i18nKey="a500">
    <DefaultValues>
    <Value>0</Value>
    </DefaultValues>
    </AttributeSchema>
    </Organization>
    </Schema>
    <Configuration>
    <OrganizationConfiguration name="/">
    <AttributeValuePair>
    <Attribute name=
    "iplanet-am-auth-mymoduleauth-primary-bind-passwd"/>
    <Value>adminadmin</Value>
    </AttributeValuePair>
    </OrganizationConfiguration>
    </Configuration>
    </Service>
    </ServicesConfiguration>
  5. (OPTIONAL) Create a localization properties file for the new authentication module.
    A localization properties file specifies the screen text that an administrator will see when directed to an authentication module's service page in the OpenSSO console, as well as messages (error or otherwise) displayed by the module. Here are some concepts behind the creation of this file.

    • The data following the equal (=) sign in each key/value pair could be translated to a specific language as necessary.
    • The alphanumeric keys (a1, a2, etc.) map to fields defined by the i18nKey attribute in the corresponding amAuthmodulename.xml service file.
    • The alphanumeric keys also determine the order in which the fields are displayed in the OpenSSO console. The keys are taken in the order of their ASCII characters (a1 is followed by a10, followed by a2, followed by b1). For example, if an attribute needs to be displayed at the top of the service attribute page, the alphanumeric key should have a value of a1. The second attribute could then have a value of either a10, a2 or b1, and so forth. The files are located in OpenSSO-Deploy-base/WEB-INF/classes and follows the naming format amAuthmodulename.properties; for example, amAuthLDAP.properties.

    Use one of the provided authentication module localization properties files in the source code as a template for creating the file and copy it to the aforementioned directory when complete.
  6. Develop the custom authentication module.
    Custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class and must implement the init(), process() and getPrincipal() methods. The module should also invoke the setAuthLevel() method. Other methods that can be implemented include setLoginFailureURL() and setLoginSuccessURL() which define URLs to which the user is sent based on a failed or successful authentication, respectively. To make use of the account locking feature with custom authentication modules, the InvalidPasswordException exception should be thrown when the password is invalid.
  7. (OPTIONAL) Add post processing features.
    The com.sun.identity.authentication.spi.AMPostAuthProcessInterface interface can be implemented for post processing tasks on authentication success, failure and logout using the methods onLoginSuccess(), onLoginFailure(), and onLogout(), respectively. The Authentication Post Processing Classes are defined in the Core Authentication Service and configurable at several levels such as at the realm or role levels.
  8. Access http://osso-host.osso-domain:osso-port/opensso/ssoadm.jsp from a browser and choose create-svc to create the service in OpenSSO.
    Copy the authentication module's service file to the text box.
  9. Choose the register-auth-module option (also on ssoadm.jsp) to register the custom authentication module with the Core Authentication framework.
    Enter the complete module name including the prepended package.
  10. Restart OpenSSO.
    The custom authentication module is now listed under the Configuration tab as an Authentication option.

NOTE: After deploying opensso.war, you can also point a browser to http://osso-host.osso-domain:osso-port/opensso/ samples/authentication/AuthSampleLoginModule to access the sample, How to Write Sample LoginModule using AMLoginModule SPI (Service Provider Interface).

Now enjoy the More, More, More, the Andrea True Connection's #1 hit from 1976. That's when sex stars had class! (But where's the Connection?)

Comments:

Now I saw the title, and was hoping to see http://www.youtube.com/watch?v=i0HYqnw-m_c at the end - disappointed! :-)

Posted by Pat Patterson on January 15, 2009 at 01:25 AM PST #

I didn't even know that Wonder Stuff song but it would've been an excellent (albeit longer) title. Loved Elizabeth Taylor's cameo but Cliff Richard?

Posted by Michael Teger on January 15, 2009 at 01:38 AM PST #

I was thinking something a little more modern... http://au.youtube.com/watch?v=ixzIDJdHVro :)

Posted by Lachlan Mulcahy on January 19, 2009 at 08:14 AM PST #

I thought for sure you were referring to Bananarama, Lachlan. I should've known with the au prepended to the URL it would be Kylie. ; >

Posted by DocTeger on January 20, 2009 at 12:25 AM PST #

Hi Doc,

I am trying to create a new service with my custom auth module.
I am create-svc successfully and is able to view the module under Access Control->Realm->Authentication.
Clicking the module instance shows the default values properly.
However when I am trying to create a new instance of this service I get an error saying Unable to add subConfig xyz.
Can you help me with this?
The debug log shows me exception:
WARNING: AuthPropertiesModelImpl.hasAuthAttributes
com.sun.identity.authentication.config.AMConfigurationException: Invalid parameters

also:
WARNING: AuthPropertiesModelImpl.createAuthInstance
com.sun.identity.authentication.config.AMConfigurationException: Unable to add subConfig xyz

Can you help me with this?

Posted by Debashis on April 02, 2009 at 03:54 PM PDT #

Post a Comment:
Comments are closed for this entry.
About

docteger

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today