Sun Java System Identity Server 2004Q2 
Sample
 
Main Page

Login Module Sample

This file explains how to write, compile, deploy and run the Login Module Sample program.

How to Write Sample Login Module using  AMLoginModule SPI (Service Provider Interface):

  • Create Module Properties File 
  • Create Module properties XML file with the same name of the class (no package name) and have the extension .xml. Based on this configuration file, Authentication UI will dynamically generate page. 

    Note : create XML file with above naming convention even if no states required 

    Page states can be defined in module properties file as shown below, each Callbacks Element corresponds to one login page state When an authentication process is invoked, there will be Callback[] generated from user's Login Module for each state. All login state starts with 1, then module control the login process, and decides what's the next state to go. 

    Sample Module Properties file file : 
    To know how to define , construct and initiate  callback , refer Auth_Module_Properties.dtd which can be found at <install-root>/SUNWam/dtd

    <ModuleProperties moduleName="LoginModuleSample" version="1.0" >
        <Callbacks length="2" order="1" timeout="60"
            header="This is a sample login page" >
        <NameCallback>
            <Prompt> User Name </Prompt>
        </NameCallback>
        <NameCallback>
            <Prompt> Last Name </Prompt>
        </NameCallback>
        </Callbacks>
        <Callbacks length="1" order="2" timeout="60"
            header="You made it to page 2" >
            <PasswordCallback echoPassword="false" >
                <Prompt> Just enter any password </Prompt>
            </PasswordCallback>
        </Callbacks>
    </ModuleProperties>
    In the sample module configuration shown above, page state one has two Callbacks, first callback is for user ID and second is for Last Name. When the user fills in the Callbacks, those Callback[] will be sent to the module, where the module writer gets the submitted Callbacks, validates them and returns . module writer will set the next page state to 2. Page state two has one Callback to request user to enter password. The process() routine is again called after user submits the Callback[]. If the module writer throws an LoginException, an 'authentication failed' page will be sent to the user. If no exception is thrown, the user will be redirected to their default page.
  • Write SamplePrincipal.java 
  • After creating module configuration xml file next step is to write a Sample Principal class which implements java.security.Principal and the constructor takes username of the user as an argument. If authentication is successful, module will return this principal to Authentication framework which will populate a Subject with a SamplePrincipal representing the user. 
  • Write Sample LoginModule 
  • Login Module writers must subclass and implement init(), process(), getPrincipal() methods. To the AMLoginModule class. AMLoginModule is an abstract class which implements JAAS LoginModule, it provides methods to access Sun Java System Identity Server services and the module XML configuration.  Refer javadocs for
    complete list of methods.
    public void init(Subject subject,Map sharedState, Map options);
    This is an abstract method, Module writer should implemet to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, they can be ignored. This method is called by a AMLoginModule after this SampleLoginModule has been instantiated, and prior to any calls to its other public methods. The method implementation should store away the provided arguments for future use. The init method may additionally peruse the provided sharedState to determine what additional authentication state it was provided by other LoginModules, and may also traverse through the provided options to determine what configuration options were specified to affect the LoginModule's behavior. It may save option values in variables for future use. 
    public int process(javax.security.auth.callback.Callback[] callbacks, int state)
        throws LoginException;
    The process method is called to authenticate a Subject. This method implementation should perform the actual authentication. For example, it may cause prompting for a user name and password, and then attempt to verify the password against a password database. If your LoginModule requires some form of user interaction (retrieving a user name and password, for example), it should not do so directly. That is because there are various ways of communicating with a user, and it is desirable for LoginModules to remain independent of the different types of user interaction. Rather, the LoginModule's process method should invoke the handle method of the the CallbackHandler passed to this method to perform the user interaction and set appropriate results, such as the user name and password and the AMLoginModule internally passes the UI an array of appropriate Callbacks, for example a NameCallback for the user name and a PasswordCallback for the password, and the UI performs the requested user interaction and sets appropriate values in the Callbacks. 

    Consider following steps while writing preocess() method. 

    1. Perform the authentication. 
    2. If Authentication succeeded, save the principal who has successfully authenticated. 
    3. Return -1 if authentication succeeds, or throw a LoginException such as AuthLoginException if authentication fails or return relevant state specified in module configuration XML file 
    4. If multiple states are available to the user, the Callback array from a previous state may be retrieved by using the getCallbak(int state) methods. The underlying login module keeps the Callback[] from the previous states until the login process is completed. 
    5. If a module writer need to substitute dynamic text in next state, the writer could use the getCallback() method to get the Callback[] for the next state, modify the output text or prompt, then call replaceCallback() to update the Callback array. This allows a module writer to dynamically generate challenges, passwords or user IDs. 
    Note: Each authentication session will create a new instance of your Login Module Java class. The reference to the class will be released once the authentication session has either succeeded or failed. It is important to note that any static data or reference to any static data in your Login module must be thread-safe. 
    public Principal getPrincipal();
    This method should be called once at the end of a successful authentication session. A login session is deemed successful when all pages in the Module properties XML file have been sent and the module has not thrown an exception. The method retrieves the authenticated token string that the authenticated user will be known by in the Identity Server environment. 

How to Compile and Run the Sample:

On Solaris

Steps to compile the Login Module Sample program on Solaris 

Follow the steps given below to compile the sample found under  <install-root>/SUNWam/samples/authentication/spi/providers.skip this
step if you are writing your own Custom Authentication module based on AMLoginModule SPI or Pure JAAS module.
  • Set the following environment variables. These variables will be used to run the gmake command. You can also set these variables in the Makefile. This Makefile is in the same directory (<install-root>/SUNWam/samples/authentication/spi/providers) as the Login Module Sample program files. 
    • JAVA_HOME

    • Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher. 
    • CLASSPATH

    • Set this variable to refer to am_services.jar which can be found in the <install-root>/SUNWam/lib directory. (Note: Include jaas.jar in your classpath if you are using JDK version less than JDK1.4) 
    • BASE_DIR

    • Set this variable to the directory where the Identity Server is installed. 
    • BASE_CLASS_DIR

    • Set this variable to the directory where all the Sample compiled classes are located. 
    • JAR_DIR

    • Set this variable to the directory where the JAR files of the Sample compiled classes will be created. 
  • Go to the <install-root>/SUNWam/samples/authentication/spi/providers directory and run gmake.

Steps to "deploy" the Login Module Sample program

  • Copy LoginModuleSample.jar from JAR_DIR to <install-root>/SUNWam/web-src/services/WEB-INF/lib.
  • Update classpath with  LoginModuleSample.jar  in the Web Container  from which this sample has to run. For use with Sun ONE Webserver, go to server instance's config directory  /<WS-home-dir>/https-<WS-instance-name>/config/. For Sun ONE App Server <AS-home-dir>/domain/domain1/server1/config/ and update server.xml with new classpath.for all other containers consult their documentation.
  • Copy LoginModuleSample.xml from <install-root>/SUNWam/samples/authentication/spi/providers to <install-root>/SUNWam/web-src/services/config/auth/default.
  • Redeploy servies war file by running corresponding install script depending upon the web container on which these samples are deployed. for example if samples are deployed on Sun(tm) ONE App Server7.0, run amas70config, for Sun(tm) ONE Web Server run amws61config script found under <install-root>/SUNWam/bin
  • Restart web container (e.g  /<WS-home-dir>/https-<WS-instance-name>/start, /<AS-home-dir>/domains/domain1/server1/bin/start for Web Server and App server respectively)
Steps to load Login Module Sample into Identity Server
  • Using IS Admin Console.
    • Login to Identity Server Console as amadmin, using the URL: http://<host>.<domain>:<port>/<Console-Deploy-URL>
    • Select "Service Configuration" frame
    • In "Service Configuration" frame select "Core" within "Authentication"
    • Add class file name com.iplanet.am.samples.authentication.spi.providers.LoginModuleSample to "Pluggable Auth Modules Classes"
    • Click on save button to save the changes in console.
  • Using Commandline (amadmin)
    • Write a sample.xml file as shown below, which will add LoginModuleSample auth module entry into allowed modules, anauthenticators list.
      • <!--
              Copyright (c) 2003 Sun Microsystems, Inc. All rights reserved
             Use is subject to license terms.
        -->
         
         

         <!DOCTYPE Requests
              PUBLIC "-//iPlanet//iDSAME 5.0 Admin CLI DTD//EN"
             "jar://com/iplanet/am/admin/cli/amAdmin.dtd"
         >

        <Requests>
            <SchemaRequests serviceName="iPlanetAMAuthService"
         SchemaType="Organization">
              <AddChoiceValues>
                <AttributeValuePair>
                  <Attribute name="iplanet-am-auth-allowed-modules"/>
                  <Value>LoginModuleSample</Value>
                </AttributeValuePair>
              </AddChoiceValues>
            </SchemaRequests>

            <SchemaRequests serviceName="iPlanetAMAuthService" SchemaType="Global">
              <AddDefaultValues>
               <AttributeValuePair>
                  <Attribute name="iplanet-am-auth-authenticators"/>

         <Value>com.iplanet.am.samples.authentication.spi.providers.LoginModuleSample</Value>
                </AttributeValuePair>
              </AddDefaultValues>

            </SchemaRequests>
        </Requests>

  • Load sample.xml via amadmin 
    • cd <install-root>/SUNWam/bin.
    • /amadmin --runasdn uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --data sample.xml

Steps to run the Login Module Sample program

  • Log in to Identity Server console as amAdminhttp://<host>.<domain>:<port>/<Console-Deploy-URI>.
  • Select the "Identity Management" tab view and select your organization.
  • Select "Services" from the "View" menu.
  • Click on "Core" in the navigation frame under "Authentication".
  • Add "LoginModuleSample" to the list of highlighted modules in "Organization Authentication Modules".
  • Make sure "LDAP" module is also selected, if not you will not be able to login to Identity Server Console. (Use Control + mouse click to add additional modules).
  • Click on "Save" to save the changes.
  • Log out
  • Enter URL http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/Login?module=LoginModuleSample. (If you choose to use an organization other than the default, please specify that in the URL using the 'org' parameter.)

On Windows2000

Steps to compile the Login Module Sample program on Windows2000

  • Set the following environment variables. These variables will be used to run the make command. You can also set these variables in the Makefile. This Makefile is in the same directory (<install-root>\samples\authentication\spi\providers) as the Login Module Sample program files.
    • JAVA_HOME

    • Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.
    • BASE

    • Set this variable to <install-root>
    • CLASSPATH

    • Set this variable to refer to am_services.jar which can be found in the <install-root>\lib directory. (Note: Include jaas.jar in your classpath if you are using JDK version less than JDK1.4)
    • BASE_CLASS_DIR

    • Set this variable to the directory where all the Sample compiled classes are located.
    • JAR_DIR

    • Set this variable to the directory where the JAR files of the Sample compiled classes will be created.
  • Go to the <install-root>\samples\authentication\spi\providers directory and run make.

Steps to deploy the Login Module Sample program

  • Copy LoginModuleSample.jar from JAR_DIR to <install-root>\web-src\services\WEB-INF\lib
  • update classpath with LoginModuleSample.jar in the Web Container  from which this sample has to run. For use with Sun ONE Webserver, go to server instance's config directory  <WS-home-dir>\https-<WS-instance-name>\config\. and update server.xml with new classpath.
  • Copy LoginModuleSample.xml from <install-root>\samples\authentication\spi\providers to <install-root>\web-src\services\config\auth\default.
  • Restart web container (e.g  /<WS-home-dir>/https-<WS-instance-name>/start)
Steps to load Login Module Sample into Identity Server
    • Using IS Admin Console.
      • Login to Identity Server Console as amadmin, using the URL: http://<host>.<domain>:<port>/<Console-Deploy-URL>
      • Select "Service Configuration" frame
      • In "Service Configuration" frame select "Core" within "Authentication"
      • Add class file name com.iplanet.am.samples.authentication.spi.providers.LoginModuleSample to "Pluggable Auth Modules Classes"
      • Click on save button to save the changes in console.
    • Using Commandline (amadmin)
      • Write a sample.xml file as shown below, which will add LoginModuleSample auth module entry into allowed modules, anauthenticators list.
        • <!--
                Copyright (c) 2003 Sun Microsystems, Inc. All rights reserved
               Use is subject to license terms.
          -->
           
           

           <!DOCTYPE Requests
                PUBLIC "-//iPlanet//iDSAME 5.0 Admin CLI DTD//EN"
               "jar://com/iplanet/am/admin/cli/amAdmin.dtd"
           >

          <Requests>
              <SchemaRequests serviceName="iPlanetAMAuthService"
           SchemaType="Organization">
                <AddChoiceValues>
                  <AttributeValuePair>
                    <Attribute name="iplanet-am-auth-allowed-modules"/>
                    <Value>LoginModuleSample</Value>
                  </AttributeValuePair>
                </AddChoiceValues>
              </SchemaRequests>

              <SchemaRequests serviceName="iPlanetAMAuthService" SchemaType="Global">
                <AddDefaultValues>
                 <AttributeValuePair>
                    <Attribute name="iplanet-am-auth-authenticators"/>

           <Value>com.iplanet.am.samples.authentication.spi.providers.LoginModuleSample</Value>
                  </AttributeValuePair>
                </AddDefaultValues>

              </SchemaRequests>
          </Requests>

    • Load sample.xml via amadmin 
      • cd <install-root>/SUNWam/bin.
      • /amadmin --runasdn uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --data sample.xml

Steps to "run" the Login Module Sample program

  • Log in to Identity Server console as amAdmin, enter URL http://<host>.<domain>:<port>/<Console-Deploy-URI>.
  • Select the "Identity Management" tab view and select your organization.
  • Select "Services" from the "View" menu.
  • Click on "Core" in the navigation frame under "Authentication".
  • Add "LoginModuleSample" to the list of highlighted modules in "Organization Authentication Modules".
  • Make sure "LDAP" module is also selected, if not you will not be able to login to Identity Server Console. (Use Control + mouse click to add additional modules).
  • Click on "Save" to save the changes.
  • Log out
  • Enter URL http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/Login?module=LoginModuleSample. (If you choose to use an organization other than the default, please specify that in the URL using the "org" parameter.)