Form-based Authentication Sample Application

> Form-based Authentication Sample Application
> This document describes how to use the Form-based Authentication sample application in conjunction with Sun ONE Web Server.

> This sample application document contains the following sections:

> Overview

> - Compiling and Assembling the Sample Application

> - Deploying the Sample Application

> - Running the Sample Application

> - Troubleshooting

> Overview

> The following instructions describe how to manually deploy the application. You may want to experiment by modifying and redeploying the sample.

> Precompilation Tasks
> Before you begin to compile and deploy the code, there are some housekeeping tasks that must be performed.

> You must add user names in the keyfile. To do so:

> 1. Log in as administrator through the Administration GUI.
> 2. (a) Select 'Global Settings.' Available directory services will be displayed.
>    (b) Determine the directory service pointing to <instance_root>/config/keyfile.
>    If no service is available for that keyfile, you must create a new directory service.
>    (c) Select the 'Key File' as the option for 'Create New Service of type' and click the 'New' button.
>    (d) Enter the 'Directory Service ID' and the 'File Name.'
>    NOTE: If no directory service is available, the system assigns the name 'default' for the 'Directory Service ID.'
>    In that case, you only need to enter the 'File Name.'
>    For example, if the instance_root is c:\ws61\https-samples and 'Directory Service ID' is security_samples,
>    then for 'Directory Service ID' enter security_samples, and for 'File Name' enter c:/ws61/https-samples/config/keyfile.
>    (e) Click the 'Save Changes' button. You will be prompted to restart the server.
>    (f) Select 'Users and Groups,' click 'New Users' and select the newly created directory service from step (d).
>    (g) Create the following users (use 'secret' as the password and 'staff,engineer' as the groups for all of the users):
>    (i) j2ee
>    (ii) ws
> 3. Apply changes and restart the instance.
> 4. Verify that the entries have been added in the <instance_root>/config/keyfile.

> Compiling and Assembling the Sample Application

> To compile and assemble the sample application:
> 1. Go to <install_root>/plugins/java/samples/webapps/security/form-auth/src/ and execute the following command:
>    ant
>    The default target 'default' will be executed to build the WAR file.
> 2. Deploy the application.
>    After you have created the sample application from scratch, you can proceed to Deploying the Sample Application. Step 3 is optional.
> 3. To clean the web application project area (optional), execute the following command:
>    ant clean

> Deploying the Sample Application

> To deploy the form-based security web sample application:
> 1. Go to the src directory of the sample:
>    <install_root>/plugins/java/samples/webapps/security/form-auth/src
> 2. Run ant using the deploy task:
>    ant deploy
> If you want to verify registration of the application, proceed to Verifying Deployment. Otherwise, proceed to Running the Sample Application.

> Verifying Deployment

> > - Go to the src directory of the sample:
> >   <install_root>/plugins/java/samples/webapps/security/form-auth/src
> > - Execute the following command:
> >   ant list_apps
> >   You will see the webapps-formbased-security module displayed as one of the listed components.

> Running the Sample Application

> You can run the application through the following URL:

> http://<Web_Server_hostname>:<port>/webapps-formbased-security

> Log on as "j2ee" with password "secret."
> It will display the message "You are Authenticated Successfully!"

> Troubleshooting

> Close all browser instances before you try to log in again; if you are using Netscape, you must also close the email session. Otherwise, it will pick up the session information from the previous logins and grant you access.

> - While appending data to the keyfile, make sure that the user names entered are unique.

> - If you encounter problems when running the application, review the log files at <instance_root>/logs/errors to determine what went wrong.

> Copyright © 2003 Sun Microsystems, Inc. All rights reserved.