FileDocCategorySizeDatePackage
ProgrammaticLogin.javaAPI DocGlassfish v2 API17708Fri May 04 22:32:54 BST 2007com.sun.appserv.security

ProgrammaticLogin

public class ProgrammaticLogin extends Object
Implement programmatic login.

This class allows deployed applications to supply a name and password directly to the security service. This info will be used to attempt to login to the current realm. If authentication succeeds, a security context is established as this user.

This allows applications to programmatically handle authentication. The use of this mechanism is not recommended since it bypasses the standard J2EE mechanisms and places all burden on the application developer.

Invoking this method requires the permission ProgrammaticLoginPermission with the method name being invoked.

There are two forms of the login method, one which includes the HTTP request and response objects for use by servlets and one which can be used by EJBs.

Fields Summary
private static Logger
logger
private static ProgrammaticLoginPermission
plLogin
private static ProgrammaticLoginPermission
plLogout
private static boolean
isServer
private static CallbackHandler
handler
Constructors Summary
Methods Summary
private voidcheckLoginPermission(java.lang.String user)
Check whether caller has login permission.

        try {
            if(logger.isLoggable(Level.FINE)){
                logger.log(Level.FINE, "ProgrammaticLogin.login() called for user: " 
                    + user);
            }
            SecurityManager sm = System.getSecurityManager();
            if (sm != null) {
                sm.checkPermission(plLogin);
            }

        } catch (Exception e) {
            logger.warning("proglogin.noperm");
            throw e;
        }
private voidcheckLogoutPermission()
Check if caller has logout permission.

        try {
            if(logger.isLoggable(Level.FINE)){
                logger.log(Level.FINE, "ProgrammaticLogin.logout() called.");
            }
            SecurityManager sm = System.getSecurityManager();
            if (sm != null) {
                sm.checkPermission(plLogout);
            }
            
        } catch (Exception e) {
            logger.warning("prologout.noperm");
            throw e;
        }
public java.lang.Booleanlogin(java.lang.String user, java.lang.String password, java.lang.String realm, boolean errors)
Attempt to login.

Upon successful return from this method the SecurityContext will be set in the name of the given user as its Subject.

On client side, realm and errors parameters will be ignored and the actual login will not occur until we actually access a resource requiring a login. And a java.rmi.AccessException with COBRA NO_PERMISSION will occur when actual login is failed.

This method is intented primarily for EJBs wishing to do programmatic login. If servlet code used this method the established identity will be propagated to EJB calls but will not be used for web container manager authorization. In general servlets should use the servlet-specific version of login instead.

param
user User name.
param
password Password for user.
param
realm the realm name in which the user should be logged in.
param
errors errors=true, propagate any exception encountered to the user errors=false, no exceptions are propagated.
return
Boolean containing true or false to indicate success or failure of login.
throws
Exception any exception encountered during Login.

    
                                                                                                                                                                                       
            
              
    
        Boolean authenticated = null;
        // check permission to login
        try {

            // exception thrown on failure
            checkLoginPermission(user); 

            // try to login. doPrivileged is used since application code does
            // not have permissions to process the jaas login.
            authenticated = (Boolean)
                AccessController.doPrivileged(new PrivilegedAction() {
                    public java.lang.Object run() {
                    // if realm is null, LCD will log into the default realm
                        if (isServer) {
                            LoginContextDriver.login(user, password, realm);
                        } else {
                            int type = AppContainer.USERNAME_PASSWORD;
                            //should not set realm here

                            // Bugfix# 6387278. The UsernamePasswordStore 
                            // abstracts the thread-local/global details
                            UsernamePasswordStore.set(user, password);

                            try {
                                LoginContextDriver.doClientLogin(type, handler);
                            } finally {
                                // For security, if thread-local no need to 
                                // save the username/password state
                                UsernamePasswordStore.resetThreadLocalOnly();
                            }
                        }
                        return Boolean.valueOf(true);
                    }
                });
        } catch (Exception e) {
            logger.severe("Programmatic login failed: "+e.toString());
            if(errors == true){ // propagate the exception ahead
                throw e;    
            } else{
                authenticated = Boolean.valueOf(false);
            }
        }        
        return authenticated;
public java.lang.Booleanlogin(java.lang.String user, java.lang.String password)
Attempt to login.

Upon successful return from this method the SecurityContext will be set in the name of the given user as its Subject.

On client side, the actual login will not occur until we actually access a resource requiring a login. And a java.rmi.AccessException with COBRA NO_PERMISSION will occur when actual login is failed.

This method is intented primarily for EJBs wishing to do programmatic login. If servlet code used this method the established identity will be propagated to EJB calls but will not be used for web container manager authorization. In general servlets should use the servlet-specific version of login instead.

param
user User name.
param
password Password for user.
return
Boolean containing true or false to indicate success or failure of login.

        // call login with realm-name = null and request for errors = false
        Boolean authenticated = null;
        try{
            authenticated = login(user, password, null, false);
        } catch(Exception e){
            // sanity checking, will never come here
            authenticated = Boolean.valueOf(false); 
        }
        return authenticated;
public java.lang.Booleanlogin(java.lang.String user, java.lang.String password, java.lang.String realm, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, boolean errors)
Attempt to login. This method is specific to servlets (and JSPs).

Upon successful return from this method the SecurityContext will be set in the name of the given user as its Subject. In addition, the principal stored in the request is set to the user name. If a session is available, its principal is also set to the user provided.

returns
Boolean containing true or false to indicate success or failure of login.
param
realm
param
errors
param
user User name.
param
password Password for user.
param
request HTTP request object provided by caller application. It should be an instance of HttpRequestFacade.
param
response HTTP response object provided by called application. It should be an instance of HttpServletResponse.
throws
Exception any exceptions encountered during login
return
Boolean indicating true for successful login and false otherwise

        Boolean authenticated = null;
        try{
            // check permission to login        
            checkLoginPermission(user);
            // try to login. doPrivileged is used since application code does
            // not have permissions to process the jaas login.
            authenticated = (Boolean)
                AccessController.doPrivileged(new PrivilegedAction() {
                    public java.lang.Object run() {
                        return WebProgrammaticLogin.login(user, password, realm,
                                                          request, response);
                    }
                });
        } catch(Exception e){
            if(errors != true){
                authenticated = Boolean.valueOf(false);
            } else{
                throw e;
            }
        }            
        return authenticated;
public java.lang.Booleanlogin(java.lang.String user, java.lang.String password, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Attempt to login. This method is specific to servlets (and JSPs).

Upon successful return from this method the SecurityContext will be set in the name of the given user as its Subject. In addition, the principal stored in the request is set to the user name. If a session is available, its principal is also set to the user provided.

param
user User name.
param
password Password for user.
param
request HTTP request object provided by caller application. It should be an instance of HttpRequestFacade.
param
response HTTP response object provided by called application. It should be an instance of HttpServletResponse.
return
Boolean containing true or false to indicate success or failure of login.

        Boolean authenticated = null;    
        try{
            // pass a null realmname and errors=false
            authenticated = login(user, password, null, request, response, false);
        }catch (Exception e){
            // sanity check will never come here
            authenticated = Boolean.valueOf(false);
        }
        return authenticated;
public java.lang.Booleanlogout()
Attempt to logout.

returns
Boolean containing true or false to indicate success or failure of logout.

        Boolean loggedout = null;
        try{
           loggedout = logout(false);
        } catch(Exception e){
            // sanity check will never come here
            loggedout = Boolean.valueOf(false);
        }
        return loggedout;
public java.lang.Booleanlogout(boolean errors)
Attempt to logout.

param
errors, errors = true, the method will propagate the exceptions encountered while logging out, errors=false will return a Boolean value of false indicating failure of logout
return
Boolean containing true or false to indicate success or failure of logout.
throws
Exception encountered while logging out, if errors==false

        Boolean loggedout = null;
        // check logout permission
        try{
            checkLogoutPermission();
            AccessController.doPrivileged(new PrivilegedAction() {
                public java.lang.Object run() {
                    if (isServer) {
                        LoginContextDriver.logout();
                    } else {
                        // Reset the username/password state on logout
                        UsernamePasswordStore.reset();

                        LoginContextDriver.doClientLogout();
                        //If user try to access a protected resource after here
                        //then it will prompt for password in appclient or
                        //just fail in standalone client.
                    }
                    return null;
                }
            });
            loggedout = Boolean.valueOf(true);
        } catch (Exception e) {
            logger.log(Level.WARNING, "Programmatic logout failed: "+e.toString());
            if(errors){
                throw e;
            } else{
                loggedout = Boolean.valueOf(false);
            }
        }
        return loggedout;
public java.lang.Booleanlogout(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Attempt to logout. Also removes principal from request (and session if available).

returns
Boolean containing true or false to indicate success or failure of logout.

        Boolean loggedout = null;
        try{
            loggedout = logout(request, response, false);
        }catch(Exception e){
            // sanity check, will never come here
            loggedout = Boolean.valueOf(false);
        }
        return loggedout;
public java.lang.Booleanlogout(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, boolean errors)
Attempt to logout. Also removes principal from request (and session if available).

param
errors, errors = true, the method will propagate the exceptions encountered while logging out, errors=false will return a Boolean value of false indicating failure of logout
return
Boolean containing true or false to indicate success or failure of logout.
throws
Exception, exception encountered while logging out and if errors == true

        // check logout permission
        Boolean loggedout = null;
        try{
            checkLogoutPermission();
            loggedout = (Boolean)
                AccessController.doPrivileged(new PrivilegedExceptionAction() {
                public java.lang.Object run() throws Exception{
                    return WebProgrammaticLogin.logout(request, response);
                }
            });
        }catch(Exception e){
            if(errors){
                throw e;
            }else{
                loggedout = Boolean.valueOf(false);
            }
        }
        return loggedout;