Securing a Web Application in JBoss AS using Form authentication

Securing web resources basically involves setting some stuff in the web deployment descriptor, and in jboss-web.xml.  You also have to do a little prep work to the server itself to configure a security domain for JBoss SX.  These instructions assume that you have JBoss AS installed, and you have a server instance created with at least Tomcat included.  The "default" instance is a good choice here.  The variable ${jboss.dist} refers to the location you extracted/installed JBoss AS to, and ${server.name} cooresponds to the name of the server instance you are configuring for security.  The first part of these instructions refers to setting up JBoss SX for security, and the second part deals with setting up the web application for security using a custom form based authentication.  Form based authentication allows you to customize how the authentication pages look in a web application.

CreateASimpleSecurityDomainForJBossSX

Securing the Web Application with Form Based Authentication

Note:

Attached is a sample application that can be used to test out securing a web application.  There are two files that need to be added/modified in your web application to attach it to the security domain we defined in the previous steps.  The web.xml and jboss-web.xml file contain commented out versions of the text to add to a web application that are covered in the next two steps.  Also included, is a simple index.jsp that outputs the name of the authenticated JAAS Subject via HttpServletRequest.getRemoteUser().  Finally, two resources are included to implement the form based authentication example.  The login page is /login.html, and the login errors page is /error.html.

1. Configure the web application for security by adding constraints to the web deployment descriptor.

You need to modify the web.xml in the WEB-INF directory of the web application you are securing to add in the following:

     <security-constraint>
          <web-resource-collection>
               <web-resource-name>All resources</web-resource-name>
               <description>Protects all resources</description>
               <url-pattern>/*</url-pattern>
          </web-resource-collection>
          <auth-constraint>
               <role-name>WebAppUser</role-name>
          </auth-constraint>
     </security-constraint>
   
     <security-role>
          <role-name>WebAppUser</role-name>
     </security-role>
      
     <login-config>
          <auth-method>FORM</auth-method>
               <form-login-config>
                    <form-login-page>/login.html</form-login-page>
                    <form-error-page>/errors.html</form-error-page>
               </form-login-config>
     </login-config>

The "security-constraint" section is what is used to define what resources in the web application are protected.  You can have multiple security-constraint elements in the web.xml that have different protections for different resources.  You have to have at least on web-resource-collection element to specify what this constraint it protecting.  The "url-pattern" element specifies the URL pattern to protect.  The example above protects all resources in the web application.  The auth-contstraint element specifies which roles have access to the protected resource.  The example just specifies one role, but multiple roles can be included by specifying additional role-name elements.  This role name needs to match the name of the role you specified in the my-web-roles.properties file.  There are ways to have a level of indirection with this role name by using the "security-role-ref" element instead.  Finally, the "login-config" element specifies how authentication occurs with the web application.  The "auth-method" element specifies how the browser gets credentials from the user.  The spec defines "BASIC", "DIGEST", "FORM", and "CLIENT-CERT" as the possible methods to retrieve data from the browser user.  The "FORM" option allows an application developer to control the look and feel of the credential request page and login error page.  Page is probably not the right term because really these two resources can be URIs to any resource in the web application you are securing.  This means that a JSP, HTML page, servlet, or some other resource get's presented when authentication is needed.   You can specify the resources to present for login requests, and login errors, via the form-login-page and form-error-page elements, respectivly.  The login page needs to pass some specific parameters to a specific URI to send the user's credentials to the server.  Make sure to use SSL/TLS since, without it, you are transmitting usernames and passwords in clear text over the network.

1.5 Create a login and error page for the form based authentication.

The web application needs to contain some resources for presenting an authentication form to the user.  In this example, we'll use a simple set of HTML pages to present a login form, and an authentication error page.

The login resource needs to pass two parameters to a resource called "j_security_check".  The two parameters to be passed in are "j_username" and "j_password" for the user id and password of the user authenticating with the application.  So, one could get by with a simple HTML form like the following:

<form method="POST" action="j_security_check">
  User Name: <input type="text" name="j_username" /><br />
  Password: <input type="password" name="j_password" /><br />
  <input type="submit" value="Login" />
</form>

The login errors page can contain any content you like.  You should probably let the user know that they passed in some bad credentials and that they should either try to authenticate again, or perhaps try to contact someone to get the password reset.

Create these two resources and place them in the web application archive at the locations you defined in the deployment descriptor above.

2. Configure the jboss-web.xml file to point to the "my-web" application.

Add/edit the jboss-web.xml in the WEB-INF directory of the web application you are securing to add the following in the "jboss-web" element:

<security-domain>java:/jaas/my-web</security-domain>

This element tells JBoss AS to connect the web application to the "my-web" security domain we defined in the login-config.xml file earlier.  JBoss AS exposes security domains via JNDI by prepending "java:/jaas/" to the name element in the application-policy element in the login-config.xml file.

3. Start up the application server, navigate to your application.

The browser should prompt you for username and password.  Enter "chris" for the username, and "secure" for the password.  You should then be allowed access to the web application.  You can verify this by closing the browser, opening it back up and navigating back to your protected application.  When the browser prompts you, you can either enter no credentials, or use the "admin" user account that was in the file originally (password: admin), and see that the web application won't be presented because you didn't log in with a user that had the "WebAppUser" role.

Referenced by: