public String getPrompt Return the prompt to be displayed to the user. The prompt is set by the login module when it
constructs the callback.
public String[] getChoices Return the list of choices that the user should be presented with.
public int getDefaultChoice Return the index of whichever choice in the array of choices is the default.
public boolean allowMultipleSelections If this method returns
true , allow the user to make multiple selections. If it returns
false , allow
only a single selection. public void setSelectedIndexint selection
Call this to indicate that the given selection in the array of choices has been selected. This method should be used only when the
allowMultiple−Selections method returns
false .
public void setSelectedIndexesint[] selections Call this method with an array; each element in the array represents an item that was selected e.g., if
item 3 is selected, put the number 3 into the array; dont set selections[3]
to some value. If multiple selections are not allowed, this method throws an
UnsupportedOperationException .
public int[] getSelectedIndexes Return an array of the currently selected choices. If multiple selections are not allowed, return an
array of length 1.
15.4.1.6 The confirmation callback
The ConfirmationCallback
class javax.security.auth.callback.ConfirmationCallback
allows the login module to ask the user a confirmation question that is answered with a yesno, yesnocancel, okcancel, or a similar answer. It
has the following API:
public String getPrompt Return the prompt that should be displayed to the user.
public int getMessageType Return the message type
INFORMATION ,
WARNING , or
ERROR .
public int getOptionType The type of callback. This will be either:
YES_NO_OPTION Present the user with a yesno option
YES_NO_CANCEL_OPTION Present the user with a yesnocancel option
OK_CANCEL_OPTION Present the user with an okcancel option
UNSPECIFIED_OPTION Use the
getOptions method to determine what the options are
public String[] getOptions Retrieve the text for each of the possible options as well as the number of options, based on the
length of the returned array when the option type is UNSPECIFIED_OPTION
. public int getDefaultOption
Get the default option. This will be YES
, NO
, OK
, or CANCEL
, unless the options are unspecified, in which case it will be the index into the array returned by the
getOptions method.
public void setSelectedIndexint selection Set the selected confirmation option. This will be
YES ,
NO ,
OK ,
CANCEL , or, in the case of
unspecified options, the index into the array of options. This is the value you are responsible for setting when you process the callback method.
public int getSelectedIndex Get the currently selected option. This will be
YES ,
NO ,
OK ,
CANCEL , or the index into the array of
unspecified options.
15.4.1.7 The language callback
If the login module needs to determine which locale the user should be authenticated for, it will provide a language callback object. The
LanguageCallback class has a very simple API:
public Locale getLocale Return the locale currently stored in the object.
public void setLocaleLocale l Set the locale in the object. You are responsible for determining the appropriate locale usually just
the current locale and using this method to set it. If you know your application will use login modules that do not need callbacks, you can specify
null as the
callback handler as we did in our first example. If the login modules will use only a few specific callbacks, you can use a limited callback handler. This is particularly relevant for server applications with no user to
interact with: you can program name and password callback handlers to return a particular name and password, but you cannot hardwire the arbitrary information for other callbacks. On the other hand, for an
interactive application, implementing a callback handler that understands all the possible callbacks gives you the most flexibility.
15.4.2 Writing a Login Module
Say you have a set of IDs and passwords stored in a database somewhere. You could use a proprietary authentication system, but if youre really ambitious you might want to write a login module to authenticate
users based on their Java Cards. In this section, well show you how to write your own login module.
Our rationale other than pedagogical for writing a login module is that we want a simple module that will ease testing and can be used on all platforms. So were going to write a module that always authenticates a
user named defaultUser. We used this module in our example earlier.
Writing a login module requires implementing the LoginModule
interface javax.security.auth.spi.LoginModule
, which means writing an object with the following methods:
public void initializeSubject s, CallbackHandler ch, Map sharedState, Map options Initialize the login module. The subject should be saved; the login module will store one or more
principals in it, perhaps using the callback handler to obtain authentication information. The shared state map can be used to cache results; the options map contains the options read from the login
configuration file.
public boolean login Authenticate a user. Information about the user may be obtained from the environment or by using the
callbacks. If authentication succeeds, return true
; otherwise return false
. If you invoke a callback that throws an exception or otherwise encounter a problem, this method should throw a
LoginException .
public boolean commit Indicates that this user will be accepted. This method is called only if the user is authenticated by all
modules in the login configuration file. At this point, the login module must add the appropriate principal objects to the stored subject.
If for some reason the user principal objects cannot be stored, this method should return false
. Otherwise, it should return
true . A
LoginException should be thrown for unrecoverable
exceptions. If this module was configured as optional and it was unable to authenticate the user i.e., the
login method returned
false , this method will still be called if other modules authenticated the user. In
that case, this method should not store any information into the subject, and it should clean up any saved state.
public boolean abort Indicates that the user will not be accepted. This method is called if the user cannot be authenticated
e.g., a required module failed or no optional module succeeded. The module should clean up any saved state. It may throw a
LoginException if it encounters an error.
public boolean logout Log the user out; this entails cleaning up any state and removing from the saved subject any principals
