0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Copyright (c) 2007 Sun Microsystems Inc. All Rights Reserved
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster The contents of this file are subject to the terms
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster of the Common Development and Distribution License
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster (the License). You may not use this file except in
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster compliance with the License.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster You can obtain a copy of the License at
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster https://opensso.dev.java.net/public/CDDLv1.0.html or
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster See the License for the specific language governing
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster permission and limitations under the License.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster When distributing Covered Code, include this CDDL
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Header Notice in each file and include the License file
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster If applicable, add the following below the CDDL Header,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster with the fields enclosed by brackets [] replaced by
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster your own identifying information:
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster "Portions Copyrighted [year] [name of copyright owner]"
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster $Id: AuthSampleLoginModule.html,v 1.6 2009/01/06 21:51:51 bigfatrat Exp $
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<link rel="stylesheet" type="text/css" href="/com_sun_web_ui/css/css_ns6up.css" />
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<link rel="shortcut icon" href="/com_sun_web_ui/images/favicon/favicon.ico" type="image/x-icon"></link>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<div class="SkpMedGry1"><a href="#SkipAnchor2019"><img src="/com_sun_web_ui/images/other/dot.gif" alt="Jump to End of Masthead" border="0" height="1" width="1" /></a></div>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<table width="100%" border="0" cellpadding="0" cellspacing="0" class="MstTblTop" title="">
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<table width="100%" border="0" cellpadding="0" cellspacing="0" class="MstTblBot" title="">
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<div class="MstDivTtl"><img src="/console/images/PrimaryProductName.png" alt="" /></div></td>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<td class="MstTdLogo" width="1%"><img src="/com_sun_web_ui/images/other/javalogo.gif" alt="Java(TM) Logo" border="0" height="55" width="31" /></td>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<table class="MstTblEnd" border="0" cellpadding="0" cellspacing="0" width="100%"><tbody><tr><td><img name="RMRealm.mhCommon.EndorserLogo" src="/com_sun_web_ui/images/masthead/masthead-sunname.gif" alt="Sun(TM) Microsystems, Inc." align="right" border="0" height="10" width="108" /></td></tr></tbody></table></div>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<div class="SkpMedGry1"><a name="SkipAnchor2019" id="SkipAnchor2019"></a></div>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<div class="SkpMedGry1"><a href="#SkipAnchor4161"><img src="/com_sun_web_ui/images/other/dot.gif" alt="Jump Over Tab Navigation Area. Current Selection is: Access Control" border="0" height="1" width="1" /></a></div>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<table bgcolor="#FFFFFF" cellspacing="8" cellpadding="4" border="0" width="100%">
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<b>How to Write Sample Login Module using AMLoginModule SPI (Service
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Provider Interface)?</b>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Create Module properties XML file with the same name of the class
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster (no package name) and have the extension .xml. Based on this configuration
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster file, Authentication UI will dynamically generate page.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Note : create XML file with above naming convention even if no states
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Page states can be defined in module properties file as shown below,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster each Callbacks Element corresponds to one login page state. When an
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster authentication process is invoked, there will be <code>Callback[]</code>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster generated from user's Login Module for each state. All login state starts
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster with 1, then module control the login process, and decides what's the next
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster state to go.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <ModuleProperties moduleName="LoginModuleSample" version="1.0" >
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <Callbacks length="2" order="1" timeout="60"
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster header="This is a sample login page" >
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <NameCallback>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <Prompt> User Name </Prompt>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster </NameCallback>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <NameCallback>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <Prompt> Last Name </Prompt>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster </NameCallback>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster </Callbacks>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <Callbacks length="1" order="2" timeout="60"
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster header="You made it to page 2" >
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <PasswordCallback echoPassword="false" >
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <Prompt> Just enter any password </Prompt>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster </PasswordCallback>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster </Callbacks>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster </ModuleProperties>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster In the sample module configuration shown above, page state one has two
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Callbacks, first callback is for user ID and second is for Last Name. When
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster the user fills in the Callbacks, those Callback[] will be sent to the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster module, where the module writer gets the submitted Callbacks, validates
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster them and returns. Module writer will set the next page state to 2. Page
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster state two has one Callback to request user to enter password. The
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <code>process()</code> routine is again called after user submits the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Callback[]. If the module writer throws an <code>LoginException</code>, an
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster 'authentication failed' page will be sent to the user. If no exception is
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster thrown, the user will be redirected to their default page.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Click <a href="/xml/LoginModuleSample.xml">here</a> to view XML.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster This object is created by the Authentication framework if authentication
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster succeeded. <a href="/source/com/sun/identity/samples/authentication/spi/providers/SamplePrincipal.java">Source code</a>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Login Module writers must subclass <code>AMLoginModule</code> class and
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster implement <code>init()</code>, <code>process()</code>,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <code>getPrincipal()</code> methods. <code>AMLoginModule</code> is an
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster abstract class which implements JAAS <code>LoginModule</code>, it provides
b93185b577f7150fec37f9999b95b246d73bf63cjeff.schenk methods to access OpenAM services and the module
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster XML configuration. Refer javadocs for complete list of methods.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster public void init(Subject subject,Map sharedState, Map options);
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster This method initializes the login module. If the module does not understand
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster any of the data stored in <code>sharedState</code> or options parameters,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster they can be ignored. This method is called by a <code>AMLoginModule</code>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster immediately after the login module is instantiated. This method may
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster additionally peruse the provided <code>sharedState</code> to determine
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster what are additional authentication state that was provided by other
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster login modules; and may also traverse through the provided options to
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster determine what configuration options were specified to affect the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster login module's behavior. It may save option values in variables for
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster public int process(
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster javax.security.auth.callback.Callback[] callbacks,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster ) throws LoginException;
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster This method is called to authenticate a subject. For example, it prompts
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster for a user name and password, and then attempt to verify the password
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster against a database. If the login module requires some form of user
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster interaction (e.g. retrieving a user name and password), it should not do
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster so directly. That is because there are various ways of communicating with
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster a user, and it is desirable for login module to remain independent of the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster different types of user interaction. Rather, this method should invoke
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster the handle method of the the <code>CallbackHandler</code> which deals with
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster user interaction; and then send the results back to this process method.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster For instance, user name and password are modeled as <code>NameCallback</code>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster and <code>PasswordCallback</code> respectively. The <code>CallbackHandler</code>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster then set the name and password values for these callbacks respectively; and
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster call this process method again to perform authentication.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Consider following steps while writing preocess() method.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>If Authentication succeeded, track the principal who has
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster successfully authenticated. </li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>Return -1 if authentication succeeds, or throw a login exception
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster such as <code>AuthLoginException</code> if authentication fails or
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster return relevant state specified in module configuration XML file.</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>If multiple states are available to the user, the Callback array
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster from a previous state may be retrieved by using the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <code>getCallbak(int state)</code> methods. The underlying login module
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster keeps the <code>Callback[]</code> from the previous states until thes
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster login process is completed. </li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>If a module writer need to substitute dynamic text in next state,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster the writer could use the <code>getCallback()</code> method to get the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster <code>Callback[]</code> for the next state, modify the output text or
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster prompt, then call <code>replaceCallback()</code> to update the Callback
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster array. This allows a module writer to dynamically generate challenges,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster passwords or user IDs. Note: Each authentication session will create a
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster new instance of your Login Module Java class. The reference to the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster class will be released once the authentication session has either
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster suceeded or failed. It is important to note that any static data or
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster reference to any static data in your Login module must be thread-safe.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster public Principal getPrincipal();
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster This method should be called once at the end of a successful
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster authentication session. A login session is deemed successful when all
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster pages in the Module properties XML file have been sent and the module
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster has not thrown an exception. The method retrieves the authenticated
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster token string that the authenticated user will be known by in the
b93185b577f7150fec37f9999b95b246d73bf63cjeff.schenk OpenAM environment.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<a href="/source/com/sun/identity/samples/authentication/spi/providers/LoginModuleSample.java">Source code</a>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Perform the following steps
b93185b577f7150fec37f9999b95b246d73bf63cjeff.schenk<li>Login to OpenAM Console as amadmin. [<a target="console" href="/UI/Login">here</a>]</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>Select "Core" under the Authentication table.</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>Add <code>com.sun.identity.samples.authentication.spi.providers.LoginModuleSample</code> to "Pluggable Auth Modules Classes" attribute.</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>Click on save button to save the changes</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Followings are already set up for you.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>Compile LoginModuleSample.java and SamplePrincipal.java</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>Copy the compiled classes to web application's WEB-INF/classes directory</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster<li>Copy this <a target="console" href="/xml/LoginModuleSample.xml">XML</a> to web application's config/auth/default directory.</li>
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Click <a target="console" href="/UI/Login?module=LoginModuleSample">here</a>.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster (If you choose to use a realm other than the root realm, add &org= and
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster the realm name to this URL).