Appendix B: Login Configuration Files

A login configuration file contains one or more LoginContext application names which have the following form:

Application {
    LoginModule Flag ModuleOptions;
    /* more LoginModule entries */
    LoginModule Flag ModuleOptions;
};

The Flag value controls the overall behavior as authentication proceeds down the stack. The following represents a description of the valid values for Flag and their respective semantics:

Required: The LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
Requisite: The LoginModule is required to succeed. If it succeeds, authentication continues down the LoginModule list. If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule list).
Sufficient: The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the LoginModule list). If it fails, authentication continues down the LoginModule list.
Optional: The LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.

The overall authentication succeeds only if all Required and Requisite LoginModules succeed. If a SufficientLoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules are configured for an application, then at least one Sufficient or OptionalLoginModule must succeed.

Sample Configuration File:

/*  Sample Configuration File  */

Login1 {
   com.ibm.security.auth.module.SampleLoginModule required debug=true;
};

Login2 {
   com.ibm.security.auth.module.SampleLoginModule required;
   com.ibm.security.auth.module.JAASLoginModule sufficient;
   ibm.loginModules.SmartCard requisite debug=true;
   ibm.loginModules.Kerberos optional debug=true;
};

Note: the Flags are not case sensitive. REQUISITE = requisite = Requisite.

Login1 only has one LoginModule which is an instance of the class com.ibm.security.auth.module.SampleLoginModule. Therfore, a LoginContext associated with Login1 will have a successful authentication if and only if its lone module successfully authenticates. The Required flag is trivial in this example; flag values have a relevant effect on authentication when two or more modules are present.

Login2 is easier to explain with a table.

Table 1. Login2 authentication status
Login class	Flag value	Authentication status
SampleLoginModule	required	pass	pass	pass	pass	fail	fail	fail	fail
JAASLoginModule	sufficient	pass	fail	fail	fail	pass	fail	fail	fail
SmartCard	requisite	*	pass	pass	fail	*	pass	pass	fail
Kerberos	optional	*	pass	fail	*	*	pass	fail	*
Overall authentication status		pass	pass	pass	fail	fail	fail	fail	fail

* = trivial value due to control returning to the application because a previous REQUISITE module failed or a previous SUFFICIENT module passed.