Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Configuring Message Security
- Next: User Authentication for Single Sign-on

# 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.

Note –

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 these`login` 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 these`logout` 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.

- Previous: Configuring Message Security
- Next: User Authentication for Single Sign-on

- © 2010, Oracle Corporation and/or its affiliates