Programmatic Login

Programmatic login allows a deployed J2EE application to invoke a login method. If the login is successful, a SecurityContext is established as if the client had authenticated using any of the conventional J2EE mechanisms.

Programmatic login is useful for an application that has special needs which cannot be accommodated by any of the J2EE standard authentication mechanisms.

Programmatic login is specific to the Application Server and not portable to other application servers.

This section contains the following topics:

• Precautions

• Granting Programmatic Login Permission

• The ProgrammaticLogin Class

Precautions

The Application Server is not involved in how the login information (user, password) is obtained by the deployed application. Programmatic login places the burden on the application developer with respect to assuring that the resulting system meets their security requirements. If the application code reads the authentication information across the network, it is up to the application to determine whether to trust the user.

Programmatic login allows the application developer to bypass the application server-supported authentication mechanisms and feed authentication data directly to the security service. While flexible, this capability should not be used without some understanding of security issues.

Since this mechanism bypasses the container-managed authentication process and sequence, the application developer must be very careful in making sure that authentication is established before accessing any restricted resources or methods. It is also the application developer’s responsibility to verify the status of the login attempt and to alter the behavior of the application accordingly.

The programmatic login state does not necessarily persist in sessions or participate in single sign-on.

Lazy authentication is not supported for programmatic login. If an access check is reached and the deployed application has not properly authenticated via the programmatic login method, access is denied immediately and the application might fail if not properly coded to account for this occurrence.

Granting Programmatic Login Permission

The ProgrammaticLoginPermission permission is required to invoke the programmatic login mechanism for an application. This permission is not granted by default to deployed applications because this is not a standard J2EE mechanism.

To grant the required permission to the application, add the following to the domain-dir/config/server.policy file:

grant codeBase "file:jar-file-path" {
     permission com.sun.appserv.security.ProgrammaticLoginPermission
     "login";
 };

The jar-file-path is the path to the application’s JAR file.

For more information about the server.policy file, see The server.policy File

The ProgrammaticLogin Class

The com.sun.appserv.security.ProgrammaticLogin class enables a user to perform login programmatically. This class has four login methods, two for servlets or JSP files and two for EJB components.

The login methods for servlets or JSP files have the following signatures:

public java.lang.Boolean login(String user, String password, 
javax.servlet.http.HttpServletRequest request, 
javax.servlet.http.HttpServletResponse response)

public java.lang.Boolean login(String user, String password, 
String realm, javax.servlet.http.HttpServletRequest request, 
javax.servlet.http.HttpServletResponse response, boolean errors) 
throws java.lang.Exception

The login methods for EJB components have the following signatures:

public java.lang.Boolean login(String user, String password)

public java.lang.Boolean login(String user, String password, 
String realm, boolean errors) throws java.lang.Exception

All of theselogin methods:

• Perform the authentication

• Return true if login succeeded, false if login failed

The login occurs on the realm specified unless it is null, in which case the domain’s default realm is used. The methods with no realm parameter use the domain’s default realm.

If the errors flag is set to true, any exceptions encountered during the logout are propagated to the caller. If set to false, exceptions are thrown.

The logout methods for servlets or JSP files have the following signatures:

public java.lang.Boolean logout(HttpServletRequest request, 
HttpServletResponse response)

public java.lang.Boolean logout(HttpServletRequest request, 
HttpServletResponse response, boolean errors) 
throws java.lang.Exception

The logout methods for EJB components have the following signatures:

public java.lang.Boolean logout()

public java.lang.Boolean logout(boolean errors) 
throws java.lang.Exception

All of theselogout methods return true if logout succeeded, false if logout failed.

If the errors flag is set to true, any exceptions encountered during the logout are propagated to the caller. If set to false, exceptions are thrown.