The LoginContext class describes the basic methods used
* to authenticate Subjects and provides a way to develop an
* application independent of the underlying authentication technology.
* A Configuration specifies the authentication technology, or
* LoginModule, to be used with a particular application.
* Therefore, different LoginModules can be plugged in under an application
* without requiring any modifications to the application itself.
*
*
In addition to supporting pluggable authentication, this class
* also supports the notion of stacked authentication. In other words,
* an application may be configured to use more than one
* LoginModule. For example, one could
* configure both a Kerberos LoginModule and a smart card
* LoginModule under an application.
*
*
A typical caller instantiates this class and passes in
* a name and a CallbackHandler.
* LoginContext uses the name as the index into the
* Configuration to determine which LoginModules should be used,
* and which ones must succeed in order for the overall authentication to
* succeed. The CallbackHandler is passed to the underlying
* LoginModules so they may communicate and interact with users
* (prompting for a username and password via a graphical user interface,
* for example).
*
*
Once the caller has instantiated a LoginContext,
* it invokes the login method to authenticate
* a Subject. This login method invokes the
* login method from each of the LoginModules configured for
* the name specified by the caller. Each LoginModule
* then performs its respective type of authentication (username/password,
* smart card pin verification, etc.). Note that the LoginModules will not
* attempt authentication retries or introduce delays if the authentication
* fails. Such tasks belong to the caller.
*
*
Regardless of whether or not the overall authentication succeeded,
* this login method completes a 2-phase authentication process
* by then calling either the commit method or the
* abort method for each of the configured LoginModules.
* The commit method for each LoginModule
* gets invoked if the overall authentication succeeded,
* whereas the abort method for each LoginModule
* gets invoked if the overall authentication failed.
* Each successful LoginModule's commit
* method associates the relevant Principals (authenticated identities)
* and Credentials (authentication data such as cryptographic keys)
* with the Subject. Each LoginModule's abort
* method cleans up or removes/destroys any previously stored authentication
* state.
*
*
If the login method returns without
* throwing an exception, then the overall authentication succeeded.
* The caller can then retrieve
* the newly authenticated Subject by invoking the
* getSubject method. Principals and Credentials associated
* with the Subject may be retrieved by invoking the Subject's
* respective getPrincipals, getPublicCredentials,
* and getPrivateCredentials methods.
*
*
To logout the Subject, the caller simply needs to
* invoke the logout method. As with the login
* method, this logout method invokes the logout
* method for each LoginModule configured for this
* LoginContext. Each LoginModule's logout
* method cleans up state and removes/destroys Principals and Credentials
* from the Subject as appropriate.
*
*
Each of the configured LoginModules invoked by the
* LoginContext is initialized with a
* Subject to be authenticated, a CallbackHandler
* used to communicate with users, shared LoginModule state,
* and LoginModule-specific options. If the LoginContext
* was not provided a Subject then it instantiates one itself.
*
*
Each LoginModule
* which successfully authenticates a user updates the Subject
* with the relevant user information (Principals and Credentials).
* This Subject can then be returned via the
* getSubject method from the LoginContext class
* if the overall authentication succeeds. Note that LoginModules are always
* invoked from within an AccessController.doPrivileged call.
* Therefore, although LoginModules that perform security-sensitive tasks
* (such as connecting to remote hosts) need to be granted the relevant
* Permissions in the security Policy, the callers of the
* LoginModules do not require those Permissions.
*
*
A LoginContext supports authentication retries
* by the calling application. For example, a LoginContext's
* login method may be invoked multiple times
* if the user incorrectly types in a password. However, a
* LoginContext should not be used to authenticate
* more than one Subject. A separate LoginContext
* should be used to authenticate each different Subject.
*
*
Multiple calls into the same LoginContext
* do not affect the LoginModule state, or the
* LoginModule-specific options.
*
* @version 1.88, 12/06/00
* @see javax.security.auth.Subject
* @see javax.security.auth.callback.CallbackHandler
* @see javax.security.auth.login.Configuration
* @see javax.security.auth.spi.LoginModule
*/
public class LoginContext {
private static final String INIT_METHOD = "initialize";
private static final String LOGIN_METHOD = "login";
private static final String COMMIT_METHOD = "commit";
private static final String ABORT_METHOD = "abort";
private static final String LOGOUT_METHOD = "logout";
private static final String OTHER = "other";
private static final String DEFAULT_HANDLER =
"auth.login.defaultCallbackHandler";
private Subject subject = null;
private boolean subjectProvided = false;
private boolean loginSucceeded = false;
private CallbackHandler callbackHandler;
private Map state = new HashMap();
private Configuration config;
private AppConfigurationEntry[] moduleStack;
private ClassLoader contextClassLoader = null;
private static final Class[] PARAMS = { };
private static final Debug debug = Debug.getInstance("logincontext",
"\t[LoginContext]");
private void init(String name) throws LoginException {
java.lang.SecurityManager sm = System.getSecurityManager();
if (sm != null) {
sm.checkPermission(new AuthPermission
("createLoginContext." + name));
}
if (name == null)
throw new LoginException
("Invalid null input: name");
// get the Configuration
if (config == null) {
config = (Configuration)java.security.AccessController.doPrivileged
(new java.security.PrivilegedAction() {
public Object run() {
return Configuration.getConfiguration();
}
});
}
// get the LoginModules configured for this application
moduleStack = config.getAppConfigurationEntry(name);
if (moduleStack == null) {
if (sm != null) {
sm.checkPermission(new AuthPermission
("createLoginContext." + OTHER));
}
moduleStack = config.getAppConfigurationEntry(OTHER);
if (moduleStack == null) {
MessageFormat form = new MessageFormat(
"No LoginModules configured for name");
Object[] source = {name};
throw new LoginException(form.format(source));
}
}
contextClassLoader =
(ClassLoader)java.security.AccessController.doPrivileged
(new java.security.PrivilegedAction() {
public Object run() {
return Thread.currentThread().getContextClassLoader();
}
});
}
private void loadDefaultCallbackHandler() throws LoginException {
// get the default handler class
try {
final ClassLoader finalLoader = contextClassLoader;
this.callbackHandler = (CallbackHandler)
java.security.AccessController.doPrivileged
(new java.security.PrivilegedExceptionAction() {
public Object run() throws Exception {
String defaultHandler = java.security.Security.getProperty
("auth.login.defaultCallbackHandler");
if (defaultHandler == null || defaultHandler.length() == 0)
return null;
Class c = Class.forName(defaultHandler,
true,
finalLoader);
return c.newInstance();
}
});
} catch (java.security.PrivilegedActionException pae) {
throw new LoginException(pae.getException().toString());
}
// secure it with the caller's ACC
if (this.callbackHandler != null) {
this.callbackHandler = new SecureCallbackHandler
(java.security.AccessController.getContext(),
this.callbackHandler);
}
}
/**
* Constructor for the LoginContext class.
*
*
Initialize the new LoginContext object with a name.
* LoginContext uses the specified name as the index
* into the Configuration to determine which LoginModules
* should be used. If the provided name does not match any in the
* Configuration, then the LoginContext
* uses the default Configuration entry, "other".
* If there is no Configuration entry for "other",
* then a LoginException is thrown.
*
*
This constructor does not allow for a CallbackHandler.
* If the auth.login.defaultCallbackHandler security property
* is set to the fully qualified name of a default
* CallbackHandler implementation class,
* then that CallbackHandler will be loaded and
* passed to the underlying LoginModules. If the security property
* is not set, then the underlying LoginModules
* will not have a CallbackHandler for use in communicating
* with users. The caller thus assumes that the configured
* LoginModules have alternative means for authenticating the user.
*
*
The auth.login.defaultCallbackHandler security property * can be set in the Java security properties file located in the * file named %lt;JAVA_HOME%gt;/lib/security/java.security, * where %lt;JAVA_HOME%gt; refers to the directory where the SDK * was installed. * *
Since no Subject can be specified to this constructor,
* it instantiates a Subject itself.
*
*
*
* @param name the name used as the index into the
* Configuration.
*
* @exception LoginException if the specified name
* does not appear in the Configuration
* and there is no Configuration entry
* for "other", or if the
* auth.login.defaultCallbackHandler
* security property was set, but the implementation
* class could not be loaded.
*/
public LoginContext(String name) throws LoginException {
init(name);
loadDefaultCallbackHandler();
}
/**
* Constructor for the LoginContext class.
*
*
Initialize the new LoginContext object with a name
* and a Subject object.
*
*
LoginContext uses the name as the index
* into the Configuration to determine which LoginModules
* should be used. If the provided name does not match any in the
* Configuration, then the LoginContext
* uses the default Configuration entry, "other".
* If there is no Configuration entry for "other",
* then a LoginException is thrown.
*
*
This constructor does not allow for a CallbackHandler.
* If the auth.login.defaultCallbackHandler security property
* is set to the fully qualified name of a default
* CallbackHandler implementation class,
* then that CallbackHandler will be loaded and
* passed to the underlying LoginModules. If the security property
* is not set, then the underlying LoginModules
* will not have a CallbackHandler for use in communicating
* with users. The caller thus assumes that the configured
* LoginModules have alternative means for authenticating the user.
*
*
The auth.login.defaultCallbackHandler security property * can be set in the Java security properties file located in the * file named %lt;JAVA_HOME%gt;/lib/security/java.security, * where %lt;JAVA_HOME%gt; refers to the directory where the SDK * was installed. * *
LoginContext passes the Subject
* object to configured LoginModules so they may perform additional
* authentication and update the Subject with new
* Principals and Credentials.
*
*
*
* @param name the name used as the index into the
* Configuration.
*
* @param subject the Subject to authenticate.
*
* @exception LoginException if the specified name
* does not appear in the Configuration
* and there is no Configuration entry
* for "other", if the specified subject
* is null, or if the
* auth.login.defaultCallbackHandler
* security property was set, but the implementation
* class could not be loaded.
*/
public LoginContext(String name, Subject subject)
throws LoginException {
init(name);
if (subject == null)
throw new LoginException
("invalid null Subject provided");
this.subject = subject;
subjectProvided = true;
loadDefaultCallbackHandler();
}
/**
* Constructor for the LoginContext class.
*
*
Initialize the new LoginContext object with a name
* and a CallbackHandler object.
*
*
LoginContext uses the name as the index
* into the Configuration to determine which LoginModules
* should be used. If the provided name does not match any in the
* Configuration, then the LoginContext
* uses the default Configuration entry, "other".
* If there is no Configuration entry for "other",
* then a LoginException is thrown.
*
*
LoginContext passes the CallbackHandler
* object to configured LoginModules so they may communicate with the user.
* The CallbackHandler object therefore allows LoginModules to
* remain independent of the different ways applications interact with
* users. This LoginContext must wrap the
* application-provided CallbackHandler in a new
* CallbackHandler implementation, whose handle
* method implementation invokes the application-provided
* CallbackHandler's handle method in a
* java.security.AccessController.doPrivileged call
* constrained by the caller's current AccessControlContext.
*
*
Since no Subject can be specified to this constructor,
* it instantiates a Subject itself.
*
*
*
* @param name the name used as the index into the
* Configuration.
*
* @param callbackHandler the CallbackHandler object used by
* LoginModules to communicate with the user.
*
* @exception LoginException if the specified name
* does not appear in the Configuration
* and there is no Configuration entry
* for "other", or if the specified
* callbackHandler is null.
*/
public LoginContext(String name, CallbackHandler callbackHandler)
throws LoginException {
init(name);
if (callbackHandler == null)
throw new LoginException(
"invalid null CallbackHandler provided");
this.callbackHandler = new SecureCallbackHandler
(java.security.AccessController.getContext(),
callbackHandler);
}
/**
* Constructor for the LoginContext class.
*
*
Initialize the new LoginContext object with a name,
* a Subject to be authenticated, and a
* CallbackHandler object.
*
*
LoginContext uses the name as the index
* into the Configuration to determine which LoginModules
* should be used. If the provided name does not match any in the
* Configuration, then the LoginContext
* uses the default Configuration entry, "other".
* If there is no Configuration entry for "other",
* then a LoginException is thrown.
*
*
LoginContext passes the Subject
* object to configured LoginModules so they may perform additional
* authentication and update the Subject with new
* Principals and Credentials.
*
*
LoginContext passes the CallbackHandler
* object to configured LoginModules so they may communicate with the user.
* The CallbackHandler object therefore allows LoginModules to
* remain independent of the different ways applications interact with
* users. This LoginContext must wrap the
* application-provided CallbackHandler in a new
* CallbackHandler implementation, whose handle
* method implementation invokes the application-provided
* CallbackHandler's handle method in a
* java.security.AccessController.doPrivileged call
* constrained by the caller's current AccessControlContext.
*
*
*
*
* @param name the name used as the index into the
* Configuration.
*
* @param subject the Subject to authenticate.
*
* @param callbackHandler the CallbackHandler object used by
* LoginModules to communicate with the user.
*
* @exception LoginException if the specified name
* does not appear in the Configuration
* and there is no Configuration entry
* for "other", or if the specified subject
* is null, or if the specified
* callbackHandler is null.
*/
public LoginContext(String name, Subject subject,
CallbackHandler callbackHandler) throws LoginException {
this(name, subject);
if (callbackHandler == null)
throw new LoginException(
"invalid null CallbackHandler provided");
this.callbackHandler = new SecureCallbackHandler
(java.security.AccessController.getContext(),
callbackHandler);
}
/**
* Perform the authentication and, if successful,
* associate Principals and Credentials with the authenticated
* Subject.
*
*
This method invokes the login method for each
* LoginModule configured for the name provided to the
* LoginContext constructor, as determined by the login
* Configuration. Each LoginModule
* then performs its respective type of authentication
* (username/password, smart card pin verification, etc.).
*
*
This method completes a 2-phase authentication process by
* calling each configured LoginModule's commit method
* if the overall authentication succeeded (the relevant REQUIRED,
* REQUISITE, SUFFICIENT, and OPTIONAL LoginModules succeeded),
* or by calling each configured LoginModule's abort method
* if the overall authentication failed. If authentication succeeded,
* each successful LoginModule's commit method associates
* the relevant Principals and Credentials with the Subject.
* If authentication failed, each LoginModule's abort method
* removes/destroys any previously stored state.
*
*
If the commit phase of the authentication process
* fails, then the overall authentication fails and this method
* invokes the abort method for each configured
* LoginModule.
*
*
If the abort phase
* fails for any reason, then this method propagates the
* original exception thrown either during the login phase
* or the commit phase. In either case, the overall
* authentication fails.
*
*
In the case where multiple LoginModules fail,
* this method propagates the exception raised by the first
* LoginModule which failed.
*
*
Note that if this method enters the abort phase
* (either the login or commit phase failed),
* this method invokes all LoginModules configured for the specified
* application regardless of their respective Configuration
* flag parameters. Essentially this means that Requisite
* and Sufficient semantics are ignored during the
* abort phase. This guarantees that proper cleanup
* and state restoration can take place.
*
*
*
* @exception LoginException if the authentication fails.
*/
public void login() throws LoginException {
loginSucceeded = false;
if (subject == null) {
subject = new Subject();
}
try {
invokeModule(LOGIN_METHOD);
invokeModule(COMMIT_METHOD);
loginSucceeded = true;
} catch (LoginException le) {
try {
invokeModule(ABORT_METHOD);
} catch (LoginException le2) {
throw le;
}
throw le;
}
}
/**
* Logout the Subject.
*
*
This method invokes the logout method for each
* LoginModule configured for this LoginContext.
* Each LoginModule performs its respective logout procedure
* which may include removing/destroying
* Principal and Credential information
* from the Subject and state cleanup.
*
*
Note that this method invokes all LoginModules configured for the
* specified application regardless of their respective
* Configuration flag parameters. Essentially this means
* that Requisite and Sufficient semantics are
* ignored for this method. This guarantees that proper cleanup
* and state restoration can take place.
*
*
* * @exception LoginException if the logout fails. */ public void logout() throws LoginException { if (subject == null) { throw new LoginException( "null subject - logout called before login"); } invokeModule(LOGOUT_METHOD); } /** * Return the authenticated Subject. * *
*
* @return the authenticated Subject. If authentication fails
* and a Subject was not provided to this LoginContext's
* constructor, this method returns null.
* Otherwise, this method returns the provided Subject.
*/
public Subject getSubject() {
if (!loginSucceeded && !subjectProvided)
return null;
return subject;
}
private void throwException(LoginException originalError, LoginException le)
throws LoginException {
LoginException error = (originalError != null) ? originalError : le;
throw error;
}
/**
* Invokes the login, commit, and logout methods
* from a LoginModule inside a doPrivileged block.
*/
private void invokeModule(String methodName) throws LoginException {
try {
final String finalName = methodName;
java.security.AccessController.doPrivileged
(new java.security.PrivilegedExceptionAction() {
public Object run() throws LoginException {
invoke(finalName);
return null;
}
});
} catch (java.security.PrivilegedActionException pae) {
throw (LoginException)pae.getException();
}
}
private void invoke(String methodName) throws LoginException {
LoginException firstError = null;
LoginException firstRequiredError = null;
boolean success = false;
for (int i = 0; i < moduleStack.length; i++) {
try {
int mIndex = 0;
Method[] methods = null;
// instantiate the LoginModule
Class c = Class.forName
(moduleStack[i].getLoginModuleName(),
true,
contextClassLoader);
Constructor constructor = c.getConstructor(PARAMS);
Object[] args = { };
// allow any object to be a LoginModule
// as long as it conforms to the interface
Object module = constructor.newInstance(args);
methods = module.getClass().getMethods();
// call the LoginModule's initialize method
for (mIndex = 0; mIndex < methods.length; mIndex++) {
if (methods[mIndex].getName().equals(INIT_METHOD))
break;
}
Object[] initArgs = { subject,
callbackHandler,
state,
moduleStack[i].getOptions() };
// invoke the LoginModule initialize method
methods[mIndex].invoke(module, initArgs);
// find the requested method in the LoginModule
for (mIndex = 0; mIndex < methods.length; mIndex++) {
if (methods[mIndex].getName().equals(methodName))
break;
}
// set up the arguments to be passed to the LoginModule method
Object[] args2 = { };
// invoke the LoginModule method
boolean status = ((Boolean)methods[mIndex].invoke
(module, args2)).booleanValue();
if (status == true) {
// if SUFFICIENT, return if no prior REQUIRED errors
if (!methodName.equals(ABORT_METHOD) &&
!methodName.equals(LOGOUT_METHOD) &&
moduleStack[i].getControlFlag() ==
AppConfigurationEntry.LoginModuleControlFlag.SUFFICIENT &&
firstRequiredError == null) {
if (debug != null)
debug.println(methodName + " SUFFICIENT success");
return;
}
if (debug != null)
debug.println(methodName + " success");
success = true;
} else {
if (debug != null)
debug.println(methodName + " ignored");
}
} catch (NoSuchMethodException nsme) {
MessageFormat form = new MessageFormat(
"unable to instantiate LoginModule, module, because " +
"it does not provide a no-argument constructor");
Object[] source = {moduleStack[i].getLoginModuleName()};
throw new LoginException(form.format(source));
} catch (InstantiationException ie) {
throw new LoginException(
"unable to instantiate LoginModule: " +
ie.getMessage());
} catch (ClassNotFoundException cnfe) {
throw new LoginException(
"unable to find LoginModule class: " +
cnfe.getMessage());
} catch (IllegalAccessException iae) {
throw new LoginException(
"unable to access LoginModule: " +
iae.getMessage());
} catch (InvocationTargetException ite) {
// failure cases
LoginException le;
if (ite.getTargetException() instanceof LoginException) {
le = (LoginException)ite.getTargetException();
} else {
// capture an unexpected LoginModule exception
java.io.StringWriter sw = new java.io.StringWriter();
ite.getTargetException().printStackTrace
(new java.io.PrintWriter(sw));
sw.flush();
le = new LoginException(sw.toString());
}
if (moduleStack[i].getControlFlag() ==
AppConfigurationEntry.LoginModuleControlFlag.REQUISITE) {
if (debug != null)
debug.println(methodName + " REQUISITE failure");
// if REQUISITE, then immediately throw an exception
if (methodName.equals(ABORT_METHOD) ||
methodName.equals(LOGOUT_METHOD)) {
if (firstRequiredError == null)
firstRequiredError = le;
} else {
throwException(firstRequiredError, le);
}
} else if (moduleStack[i].getControlFlag() ==
AppConfigurationEntry.LoginModuleControlFlag.REQUIRED) {
if (debug != null)
debug.println(methodName + " REQUIRED failure");
// mark down that a REQUIRED module failed
if (firstRequiredError == null)
firstRequiredError = le;
} else {
if (debug != null)
debug.println(methodName + " OPTIONAL failure");
// mark down that an OPTIONAL module failed
if (firstError == null)
firstError = le;
}
}
}
// we went thru all the LoginModules.
if (firstRequiredError != null) {
// a REQUIRED module failed -- return the error
throwException(firstRequiredError, null);
} else if (success == false && firstError != null) {
// no module succeeded -- return the first error
throwException(firstError, null);
} else if (success == false) {
// no module succeeded -- all modules were IGNORED
throwException(new LoginException
("Login Failure: all modules ignored"),
null);
} else {
// success
return;
}
}
/**
* Wrap the application-provided CallbackHandler in our own
* and invoke it within a privileged block, constrained by
* the caller's AccessControlContext.
*/
private class SecureCallbackHandler implements CallbackHandler {
private final java.security.AccessControlContext acc;
private final CallbackHandler ch;
SecureCallbackHandler(java.security.AccessControlContext acc,
CallbackHandler ch) {
this.acc = acc;
this.ch = ch;
}
public void handle(Callback[] callbacks) throws java.io.IOException,
UnsupportedCallbackException {
try {
final Callback[] finalCallbacks = callbacks;
java.security.AccessController.doPrivileged
(new java.security.PrivilegedExceptionAction() {
public Object run() throws java.io.IOException,
UnsupportedCallbackException {
ch.handle(finalCallbacks);
return null;
}
}, acc);
} catch (java.security.PrivilegedActionException pae) {
if (pae.getException() instanceof java.io.IOException) {
throw (java.io.IOException)pae.getException();
} else {
throw (UnsupportedCallbackException)pae.getException();
}
}
}
}
}