Sun GlassFish Enterprise Server

Samples Main Page

# Servlet 3.0 Programmatic Security

This is a simple web application that demonstrates the programmatic security (login/logout) feature in Servlets 3.0

## Programmatic Security

Programmatic security is used by security aware applications when declarative security alone is not sufficient to express the security model of the application. Programmatic security consists of the following methods of the `HttpServletRequest` interface:

- `login`
- `logout`
- `getRemoteUser`
- `isUserInRole`
- `getUserPrincipal`

The login methods allow an application to perform username and password collection (as an alternative to Form-Based Login), and to instigate authentication of the request caller by the container from within an unconstrained request context. The logout method is provided to allow an application to reset the caller identity of a request.

The `getRemoteUser` method returns the name of the remote user (that is, the caller) associated, by the container, with the request.

The `isUserInRole` method determines if the remote user (that is, the caller) associated with the request is in a specified security role.

The `getUserPrincipal` method determines the principal name of the remote user (that is, the caller) and returns a `java.security.Principal` object corresponding to the remote user. Calling the getName method on the Principal returned by `getUserPrincipal` returns the name of the remote user. These APIs allow servlets to make business logic decisions based on the information obtained.

## LoginServlet

The servlet performs a programmatic login, providing the username and password obtained from the user. This is an alternative to form-based-login in previous versions of servlets. Calls are made to `getRemoteUser(), getUserPrincipal()` and `isUserInRole()`, before login, after login, and after logout. Only when logged in (as javaee6user - the configured user), the calls return non-null values.

## Building, Deploying, and Running the Application

Following are the instructions for building, deploying, and running this sample application.

1. Setup your build environment and Configure the application server with which the build system has to work by following the common build instructions.
2. `app_dir` is the sample application base directory: `samples_install_dir/javaee6/security/programmatic-login`.
3. ````Change directory to `app_dir.
   `
4. Open the browser and clear the browser cache.
5. Build, deploy, and run the sample application:``

`app_dir> ant`

6. The launch target opens the browser. Enter the username/password (javaee6user/abc123 - the configured file user/password) and check the displayed values. It can be observed that before calling `login()` and after calling `logout()`, the values for `isUserInRole` is false,`getRemoteUser` returns null, while after calling `login()`, the methods return proper values.

7. Use the target `clean` to undeploy the sample application and to remove the temporary directories like build and dist.

   `app_dir> ant clean`

## Building, Deploying, and Running the Application in NetBeans IDE

Perform the following steps to build, deploy, and run the application using NetBeans IDE:

1. Refer to the common build instructions for setting up NetBeans IDE and Sun GlassFish Enterprise Server.
2. In the NetBeans IDE, choose File → Open Project (Ctrl-Shift-O), navigate to the `samples_install_dir/javaee6/security/` directory, select `programmatic-login`, and click Open Project.
3. In the Projects tab, right click `programmtic-login` and select Run to build, deploy, and run the project.

## Troubleshooting

If you have problems when running the application, refer the troubleshooting document.

Copyright 2009 Sun Microsystems, Inc. All rights reserved.