Creating an Authentication Module Callback Requirement File

The authentication module's callback requirements file is XML that 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, providing the means to initiate, construct and send the credential requests to the Distributed Authentication User Interface. Auth_Module_Properties.dtd defines the data structure of the file.

When an authentication process is invoked, the values nested in the Callbacks element of the module's callback requirements file are used to generate login screens. The module controls the login process, and determines each concurring screen. LDAP.xml, the callback requirements file for the LDAP authentication module, illustrates this concept.

Example 1–2 LDAP Authentication Module Callback Requirements File

<ModuleProperties moduleName="LDAP" version="1.0" >

    <Callbacks length="2" order="1" timeout="120" 
     header="This server uses LDAP Authentication" >
        <NameCallback>
            <Prompt> User Name: </Prompt>
        </NameCallback>
        <PasswordCallback echoPassword="false" >
            <Prompt> Password: </Prompt>
        </PasswordCallback>
    </Callbacks>

    <Callbacks length="4" order="2" timeout="120" 
     header="Change Password&lt;BR&gt;&lt;/BR&gt;#REPLACE#&lt;BR&gt;&lt;/BR&gt;" >
        <PasswordCallback echoPassword="false" >
            <Prompt>Old Password </Prompt>
        </PasswordCallback>
        <PasswordCallback echoPassword="false" >
            <Prompt> New Password </Prompt>
        </PasswordCallback>
        <PasswordCallback echoPassword="false" >
            <Prompt> Confirm Password </Prompt>
        </PasswordCallback>
        <ConfirmationCallback>
            <OptionValues>
                <OptionValue>
                    <Value> Submit </Value>
                </OptionValue>
                <OptionValue>
                    <Value> Cancel </Value>
                </OptionValue>
            </OptionValues>
        </ConfirmationCallback>
    </Callbacks>

    <Callbacks length="0" order="3" timeout="120" 
     header=" Your password has expired. Please contact service desk to 
     reset your password" error="true" />

    <Callbacks length="0" order="4" timeout="120" template="user_inactive.jsp" 
     error="true"/>

</ModuleProperties>

The initial interface has two Callback elements corresponding to requests for the user identifier and password. When the user enters values, the following events occur:

• The values are sent to the module.

• The process() routine validates the values.

  If the module writer throws a LoginException, an Authentication Failed page will be sent to the user. If no exception is thrown, the user is redirected to his or her default page.

• If the user's password is expiring, the module writer sets the next page state to 2.

  Page state 2 requires the user to change a password. The process() routine is again called after the user submits the appropriate values.

Name the authentication module's callback requirements file using the same name as that of the authentication module's class (no package information) and use the extension .xml. Create the file and use this naming convention even if no states are required for the module.

The file is located in the appropriate localized directory in the OpenSSO-Deploy-base/config/auth directory. Use one of the provided files as a template for creating the file and copy it to the aforementioned directory when finished.