A CallbackHandler
is responsible for communication between the end-user of an
application and the
javax.security.auth.spi.LoginModule that is
performing authentication of that user on behalf of the
javax.security.auth.login.LoginContext
instantiated by the application. When an application needs to
authenticate a user, it creates a LoginContext and
specifies a CallbackHandler object for that
context. The underlying LoginModule uses the
CallbackHandler to communicate with the end
userfor example prompting them to enter a name and password.
The LoginModule passes an array of objects that
implement the Callback interface to the
handle( ) method of
CallbackHandler. The handle( )
method must determine the type of Callback object,
and display the information and/or prompt for the input it
represents. Different Callback classes have
different purposes and must be handled differently.
NameCallback and
PasswordCallback are two of the most commonly
used: they represent requests for the user's name
and password. TextOutputCallback is also common:
it represents a request to display a message (such as
"Authentication Failed") to the
user. See the descriptions of the individual
Callback classes for information on how a
CallbackHandler should handle them.
CallbackHandler implementations are not required
to support every type of Callback and my throw an
UnsupportedCallbackException if passed a
Callback object of a type they do not recognize or
do not support.
The handle( ) method is passed an array of
Callback objects. A
CallbackHandler (such as a typical console-based
handler) may choose to handle the Callback objects
one at a time, prompting for and returning the
user's input before moving on to the next. Or (for
example in GUI-based handlers) it may choose to present all of the
callbacks in a single unified "login dialog
box". LoginModule implementations
may, of course, call the handle( ) method more
than once. Note, finally, that if a
CallbackHandler implementation has knowledge of
the user from some other source, it is allowed to handle certain
callbacks automatically, such as automatically providing the
user's name for a NameCallback.
Java installations may have a default
CallbackHandler registered by setting the
auth.login.defaultCallbackHandler security
property to the name of the implementing class. No such default is
defined by the default security policy that ships with
Sun's distribution of Java 1.4.
Sun's Java 1.4 SDK does include
CallbackHandler implementations to perform
text-based and GUI-based communication in the classes
TextCallbackHandler and
DialogCallbackHandler in the
com.sun.security.auth.callback package. Note that
these are part of Sun's implementation, and are not
part of the specification; they are not guaranteed to exist in all
releases.
public interface CallbackHandler {
// Public Instance Methods
void handle(Callback[ ] callbacks)
throws java.io.IOException, UnsupportedCallbackException;
}
