IBM Cloud Authors: Yeshim Deniz, Elizabeth White, Pat Romanski, Liz McMillan, Stefan Bernbo

Related Topics: IBM Cloud

IBM Cloud: Article

Implementing J2EE Form-Based Authentication

Implementing J2EE Form-Based Authentication

The J2EE security model provides a built-in security concept based on roles provided by deployment descriptors. The deployment descriptors contain elements that allow us to map users or groups of users to specific roles (this information is used to authenticate the user) - and to specify which roles are allowed access to which resources. All users mapped to a particular role are allowed access to a certain resource. (This information is used to determine if the user is authorized to access the resource or not.)

For purposes of discussion, let us consider a simple J2EE application that has a few Web pages and one Enterprise JavaBean (EJB), which is a simple session bean. The J2EE containers that house these two different types of J2EE application components are:
1.  Web container: Houses static HTML pages, servlets, JavaServer Pages, image files such as GIFs, etc.; its deployment descriptor is web.xml.
2.  EJB container: Houses EJB components; its deployment descriptor is ejb-jar.xml.

Web Container Authentication Mechanisms
Since this J2EE application has a Web component, it makes sense to authenticate users from a Web page. The Web container provides the following authentication mechanisms that can be applied to this situation:
1.  Basic: In this mechanism, when the user attempts to access a protected resource, the Web container checks whether the user has been authenticated. If not, the browser's built-in login screen pops up to prompt the user to enter the username and password for the Web container to perform authentication
2.  Form-based: In this mechanism, when the user attempts to access a protected resource, the Web container checks whether the user has been authenticated. If not, an application-specific login screen is displayed that prompts the user to enter the username and password for the Web container to perform authentication.
3.  HTTPS: This mechanism uses HTTP over Secure Sockets Layer (SSL).
4.  Hybrid: In basic and form-based authentication, passwords are not protected adequately. A hybrid mechanism overcomes this by running basic and form-based mechanisms over SSL.

From the above list of available mechanisms we are interested solely in the form-based authentication mechanism, since this best fits our requirement for an application-specific login screen to perform authentication.

User Registry
Having decided on the authentication mechanism, we need to determine where the user information is stored. We could use databases, Lightweight Directory Access Protocol (LDAP), or even the operating system to store user information. In this case, we'll use a relational database to store the user information. Since there is no industry-wide standard on the exact database schema of a custom user registry, WebSphere seeks to circumvent this problem by providing an interface (com.ibm.websphere.security.CustomRegistry) that can be implemented.

This article seeks to provide a step-by-step guide to implementing form-based authentication for a simple J2EE application using a custom user registry in WebSphere Studio Application Developer v5.

Writing the Simple J2EE Application

Start WebSphere Studio:
1.  Go to the Windows Start menu.
2.  Select Programs -> IBM WebSphere Studio -> Application Developer 5.0.

About the Application
We are about to create a simple J2EE application that manages the inventory for a retail store. Here we have two primary roles:
1.  Manager: Denotes the role of the inventory manager. A user assigned to this role is allowed to order and view inventory.
2.  Clerk: Denotes the role of inventory clerk. A user assigned to this role is allowed to view only inventory.

In order to illustrate these levels of security, we will implement the following:
1.  For the Web component, we will create two files, order.html and view.html. In the Web deployment descriptor we will allow the "Manager" to access both files. However, we will allow the "Clerk" access to only view.html.
2.  For the EJB component, we will create a session bean having two business methods, getOrder() and getView(). In the EJB deployment descriptor we will allow the "Manager" access to both of these business methods, but allow the "Clerk" access to only the getView() business method.

Custom User Registry Database
For implementing the custom user registry interface provided by WebSphere the database tables should follow a certain structure. The database scripts for Oracle are available in Listing 1. (All of the code listings for this article can be downloaded from www.sys-con.com/websphere/sourcec.cfm.) The CustomUserRegistry class described later in this article will access user information in these tables via JDBC to authenticate users.

Creating the Sample J2EE Application
Create a new J2EE 1.3 enterprise application project in the WebSphere Studio Workbench called FormAuthExample and click Finish (see Figure 1). Then perform the following steps:
1.  Right-click on FormAuthExampleWeb project.
2.  Select Properties.
3.  Click on Java Build Path.
4.  From the Java Build Path option, click on the Projects tab. Check the box next to FormAuthExampleEJB project.
5.  From the Java Build Path option, click on the Libraries tab. Click on the "Add External JARs" button.
6.  Browse and select the following file : C:\Program Files\IBM\WebSphere Studio\wstools\eclipse\plugins\com.ibm.websphere.aes.v4_4.0.4\lib\websphere.jar.
7.  Click OK.

Configuring the Web Application
In the Web Perspective (FormAuthExampleWeb project), create the login.html page:
1.  Right-click on /Web Content.
2.  Select New->HTML File.
3.  Enter login.html in the Name field.
4.  Click Finish.
5.  Modify the login.html file with the code in Listing 2.

Next, create the index.html page:
1.  Right-click on /Web Content.
2.  Select New->HTML File.
3.  Enter index.html in the Name field.
4.  Click Finish.
5.  Modify the index.html file with the code in Listing 3.

Then create the error.jsp page:
1.  Right-click on /Web Content.
2.  Select New->JSP File.
3.  Enter error.jsp in the Name field.
4.  Click Finish.
5.  Modify the error.jsp file with the following code:

Error Page Error Page

Next, create the result.jsp page:
1.  Right-click on /Web Content.
2.  Select New->JSP File.
3.  Enter result.jsp in the Name field.
4.  Click Finish.
5.  Modify the BODY section of the result.jsp file with the following code:

String result = (String) session.getAttribute("result");
if(result == null)
result = "Sorry, you do not have the necessary privileges to execute
this business method !";

Next, create a new folder in the Web Content directory named "secure":
1.  Right-click on /Web Content.
2.  Select New->Folder.
3.  Enter "secure" in the Folder Name field.
4.  Click Finish.

Within the "secure" folder, create the order.html page:
1.  Right-click on /Web Content/secure.
2.  Select New->HTML File.
3.  Enter order.html in the Name field.
4.  Click Finish.
5.  Modify the BODY section of the order.html file with the following code:

Order Inventory

Within the "secure" folder, create the view.html page:
1.  Right-click on /Web Content/ secure.
2.  Select New->HTML File.
3.  Enter view.html in the Name field.
4.  Click Finish.
5.  Modify the BODY section of the view.html file with the following code:

View Inventory

Next, create a new package named "com.form.auth.example".
1.  Right-click on /Java Source.
2.  Select New->Package.
3.  Enter com.form.auth.example in the Name field.
4.  Click Finish.

Within the com.form.auth.example package, create the FormAuthServlet.java class.
1.  Right-click on /Java Source/com.form.auth.example.
2.  Select New->Class.
3.  Enter FormAuthServlet in the Name field.
4.  Click Finish.
5.  Modify FormAuthServlet.java with the code in Listing 4.

Within the same package, create the CustomUserRegistry.java class.
1.  Right-click on /Java Source/com.form.auth.example.
2.  Select New->Class.
3.  Enter CustomUserRegistry in the Name field.
4.  Click Finish.
5.  Modify CustomUserRegistry.java with the code shown in Listing 5.

Next, open the Web deployment descriptor, web.xml, located in /Web content/WEB-INF directory, and do the following:
1.  Click on the Servlets tab. Add FormAuthServlet and its URL mapping (alias).
2.  Click on the Security tab.
3.  In the Security Roles section, add two roles, Manager and Clerk. Note: Role names are case sensitive. Also you must ensure that these role names are the same as those specified in the database table, GROUPS.
4.  In the Security Constraints section (of the same tab), add the following security constraints:
/secure/order.html is accessible by the Manager role only
/secure/view.html is accessible by roles - Manager and Clerk
/FormAuthServlet is accessible by roles - Manager and Clerk
5.  Click on the Pages tab of the deployment descriptor. Select FORM as the authentication mechanism and enter FormAuthRealm as the Realm name, /login.html as the Login page, and /error.jsp as the Error page.

The source code for web.xml is shown in Listing 6.

Configuring the EJB Application
From the J2EE Perspective, create a new package, com.form.auth.example.ejb, in the ejbModule folder of the FormAuthExampleEJB project.
1.  From the J2EE Navigator, right-click on /ejbModule/com.form.auth. example.ejb.
2.  Select New->Enterprise Bean. (EJB Type must be Session Bean.)
3.  Enter FormAuthExampleEJB in the Bean Name field.
4.  Click Finish.

Next, open FormAuthExampleEJBBean.java and add the following code:

public String getOrder() {
return "Order Inventory";

public String getView() {
return "View Inventory";

Promote these two business methods to the EJB's remote interface. After this, the FormAuthExampleEJB.java file should have the following signatures added to it:

public String getOrder() throws java.rmi.RemoteException;
public String getView() throws java.rmi.RemoteException;

Save and generate deployed code for the session EJB component.

Next, open the EJB deployment descriptor, ejb-jar.xml, which is located in the FormAuthExampleEJB/ejbModule/META-INF folder.
1.  Click on the Assembly Descriptor tab.
2.  Under Security Roles, add the two roles, Manager and Clerk.
3.  Under Method Permissions, set the following permissions. The getOrder() method will be accessible only to the Manager role. The getView() method will be accessible to both Manager and Clerk.
4.  Under Container Transactions, set the transaction type to Required for all the methods of the FormAuthExampleEJB bean.
5.  Next, click on the References tab of the deployment descriptor.
6.  Add a remote reference to FormAuthExampleEJB.
7.  Add the security role references for Manager and Clerk. Save the EJB deployment descriptor and generate deployed code.

Next, open the EAR deployment descriptor or application.xml located in the FormAuthExample/META-INF folder.
1.  Click on the Security tab.
2.  Click on Gather, which "gets" all the roles. This will be evident because the two created roles will appear in the list box on this tab.
3.  For each role, check the Users/Groups check box and enter the corresponding role's name as group name under the Groups list.

The source code for ejb-jar.xml is shown in Listing 7.

Configuring the WebSphere Studio Server Environment
1.  Create a new server project named FormAuthExampleServer.
2.  Within this project, create a new server and server configuration named FormAuthExampleServer for the test environment.
3.  Add the FormAuthExample EAR to the FormAuthExampleServer configuration.
4.  Double-click on the FormAuthExampleServer server configuration.
5.  In the server configuration, click on the Configuration tab. Check the Enable administrative console check box. Click on the Paths tab and add the following paths under ws.ext.dirs:

C:\Program Files\IBM\WebSphere Studio\workspace\FormAuthExampleWeb
\Web Content\WEB-INF\classes
C:\Program Files\IBM\WebSphere Studio\workspace\FormAuthExampleEJB

6.  Under Classpath, add:


7.  Click on the Environment tab. Under system properties, add the following:

driver = oracle.jdbc.pool.OracleConnectionPoolDataSource
url = jdbc:oracle:thin:@servername:1521:ORCL
user = sample (Name of the schema)
password = ****** (DB

These system properties are used by the com.form.auth.example.CustomUserRegistry class
8.  In the Security tab, check the Enforce Java 2 Security check box. Note: There are other settings in this tab that will need to be set after you complete the next section. Save the configuration.

Configuring the WebSphere Studio Admin Console
1.  Start the FormAuthExampleServer server.
2.  Once the server is started successfully, right-click on the server and select - Run administrative console. Note: Global Security must be disabled in order to run the administrative console. Therefore the Enable security check box in the Security tab of the server configuration must remain unchecked.
3.  Type in any user ID and log in to the admin console. This user ID is used only for logging purposes.
4.  Once logged in, using the left navigation tree of the admin console, click on Security->User Registries->Custom.
5.  Specify the Server User ID as "geethar".
6.  Specify the Server password as "pwd". (The user ID and password were inserted into the database tables as shown in Listing 1, which contains scripts to insert sample data after the tables are created.)
7.  Specify the Custom registry class name as com.form.auth.example.CustomUserRegistry.
8.  Click on the Custom Properties link on the same screen and enter the following values:

driver = oracle.jdbc.pool.OracleConnectionPoolDataSource
url = jdbc:oracle:thin:@servername:1521:ORCL
user = sample (Name of the schema)
password = ****** (DB

9.  Save the configuration
10.  Next, using the left navigation tree of the admin console, click on Security->Global Security.
11.  Check the Enable security check box.
12.  Check the Enable Java 2 security check box.
13.  Select Custom as the Active User Registry
14.  Save the configuration.
15.  Next, using the left navigation tree of the admin console, click on Security->JAAS->J2C Security.
16.  Add a new entry whose:

Alias = ORCL
User ID = sample
Password = ****** (DB Password)

17.  Save the master configuration.

Ensure that the module dependencies are specified correctly in the Properties->Project References for each project. For the FormAuthExampleWeb project, the projects FormAuthExample and FormAuthExampleEJB must be checked. For the FormAuthExample project, the projects FormAuthExampleWeb and FormAuthExampleEJB must be checked. For the FormAuthExampleEJB project, the project FormAuthExample must be checked.

Rebuild all three projects and publish to FormAuthExampleServer.

Restart the server. Test the application by running index.html on the server. When the user logs in as a Clerk, he or she can access only the View Inventory links, whereas when logging in as a Manager, the user can access all four links displayed on this page.

In this article, I have tried to demonstrate in a step-by-step manner how to implement form-based authentication using a custom user registry in WebSphere Studio Application Developer v5. This form of declarative security - being more flexible - is preferred over programming or encoding security directly into applications. However, in cases where a more fine-grained level of security is required, some programmatic security will need to be implemented in conjunction with declarative security to achieve the desired level of security.


  • Heijmans, M. (2003). "An LTPA Custom User Registry." WebSphere Developer's Journal. SYS-CON Media. Vol. 2, issue 2.
  • Subrahmanyam. (2000). "Java Servlets Advanced Features." Java Developer's Journal. Vol. 5, issue 2.
  • Mahapatra, S. (2001). "J2EE Application Security Model." Java Developer's Journal. Vol. 6, issue 8.
  • More Stories By Geetha Ramaswamy

    Geetha Ramaswamy is a technical architect at SBC Communications Inc. She holds a master's degree in computer science and has five years of experience working with Java and Web

    Comments (7) View Comments

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.

    Most Recent Comments
    Matt Boerger 12/04/07 02:59:06 PM EST

    Seemingly a nice, simple example - would be easier to use if the source listing contained the source for the following four pages: error.jsp, result.jsp, order.html, and view.html.

    Also, as others have noted, the address for the source that is given in the article text is out of date (BUT the link at the bottom of the article is correct), and the project creation instructions seem incomplete/out of order -- at least for WASD 6.

    Vivek P 07/27/07 03:44:36 PM EDT

    Where is the Listing that you refer to? Your article may be more readable with a clear indication of references to listings etc.

    William Widjaja 05/21/06 07:17:23 AM EDT

    This article is valuable. Thanks Geethar. Some minor clarification. The CustomUserRegistry should be in a different project, but it's not clearly stated. There is no need for the FormAuthExample project to depend on FormAuthExampleEJB and FormAuthExampleWeb projects. The creation of the EJB should be ahead of the Web, because in "Creating the Sample J2EE Application", the FormAuthExampleEJB does not exist yet, but we are asked to add external jar to the Java Build Path of the Web application.

    rajesh 06/23/05 02:08:32 AM EDT

    Dear All
    I had gone through the reading material for the implementation of the Form Authentication in Websphere using custom authentication. i had found a link
    which will direct to the source code
    but when i try to access the
    i am getting FileNotFound error
    Can i get the exact link for getting the source code
    Thanks in Advance
    Rajesh Kartha

    Rama 09/30/04 05:40:39 PM EDT

    I got a question:


    I am using form-based authentication.
    When I write j_security_check in the action attribute of the form tag of the login.jsp page the
    integrated WebShpere security mechanism is invoked
    (as I understand this mechanism is based on whether LocalOS or LDAP).
    But I want to use my own authentication schemas (for example, Form Filter authentication).
    What should I do in this case?

    When I write my FormFilter servlet and map the filter mapping with /j_security_check ,the control is
    going to FormFilter and validating but when I am trying to redirect the user to the
    target page after successful authentication the integrated security doesn't know about
    this user and doesn't allow enter the system. How can I combine the
    form-based authentication and my own authentication mechanism?

    Here is the entry in Web.xml:





    Thanks for help

    josh-jamaica 09/20/04 02:44:06 AM EDT

    Great Article ... this one and the ltpa one referred here are truly cool articles ..thanks

    Moe 05/17/04 10:50:25 PM EDT

    Good article. Life-saver:) The articles puts all the piecs of th puzzle together...

    IoT & Smart Cities Stories
    The deluge of IoT sensor data collected from connected devices and the powerful AI required to make that data actionable are giving rise to a hybrid ecosystem in which cloud, on-prem and edge processes become interweaved. Attendees will learn how emerging composable infrastructure solutions deliver the adaptive architecture needed to manage this new data reality. Machine learning algorithms can better anticipate data storms and automate resources to support surges, including fully scalable GPU-c...
    Machine learning has taken residence at our cities' cores and now we can finally have "smart cities." Cities are a collection of buildings made to provide the structure and safety necessary for people to function, create and survive. Buildings are a pool of ever-changing performance data from large automated systems such as heating and cooling to the people that live and work within them. Through machine learning, buildings can optimize performance, reduce costs, and improve occupant comfort by ...
    The explosion of new web/cloud/IoT-based applications and the data they generate are transforming our world right before our eyes. In this rush to adopt these new technologies, organizations are often ignoring fundamental questions concerning who owns the data and failing to ask for permission to conduct invasive surveillance of their customers. Organizations that are not transparent about how their systems gather data telemetry without offering shared data ownership risk product rejection, regu...
    René Bostic is the Technical VP of the IBM Cloud Unit in North America. Enjoying her career with IBM during the modern millennial technological era, she is an expert in cloud computing, DevOps and emerging cloud technologies such as Blockchain. Her strengths and core competencies include a proven record of accomplishments in consensus building at all levels to assess, plan, and implement enterprise and cloud computing solutions. René is a member of the Society of Women Engineers (SWE) and a m...
    Poor data quality and analytics drive down business value. In fact, Gartner estimated that the average financial impact of poor data quality on organizations is $9.7 million per year. But bad data is much more than a cost center. By eroding trust in information, analytics and the business decisions based on these, it is a serious impediment to digital transformation.
    Digital Transformation: Preparing Cloud & IoT Security for the Age of Artificial Intelligence. As automation and artificial intelligence (AI) power solution development and delivery, many businesses need to build backend cloud capabilities. Well-poised organizations, marketing smart devices with AI and BlockChain capabilities prepare to refine compliance and regulatory capabilities in 2018. Volumes of health, financial, technical and privacy data, along with tightening compliance requirements by...
    Predicting the future has never been more challenging - not because of the lack of data but because of the flood of ungoverned and risk laden information. Microsoft states that 2.5 exabytes of data are created every day. Expectations and reliance on data are being pushed to the limits, as demands around hybrid options continue to grow.
    Digital Transformation and Disruption, Amazon Style - What You Can Learn. Chris Kocher is a co-founder of Grey Heron, a management and strategic marketing consulting firm. He has 25+ years in both strategic and hands-on operating experience helping executives and investors build revenues and shareholder value. He has consulted with over 130 companies on innovating with new business models, product strategies and monetization. Chris has held management positions at HP and Symantec in addition to ...
    Enterprises have taken advantage of IoT to achieve important revenue and cost advantages. What is less apparent is how incumbent enterprises operating at scale have, following success with IoT, built analytic, operations management and software development capabilities - ranging from autonomous vehicles to manageable robotics installations. They have embraced these capabilities as if they were Silicon Valley startups.
    As IoT continues to increase momentum, so does the associated risk. Secure Device Lifecycle Management (DLM) is ranked as one of the most important technology areas of IoT. Driving this trend is the realization that secure support for IoT devices provides companies the ability to deliver high-quality, reliable, secure offerings faster, create new revenue streams, and reduce support costs, all while building a competitive advantage in their markets. In this session, we will use customer use cases...