FormBased authentication in JBoss

J2EE WebContainers provide authentication mechanism feature to protect the Web Resources. These are defined by <auth-method> attribute in the web.xml deployment descriptor. Different authentication mechanisms provided are:

FORM

BASIC

CLIENT-CERT

This post describes a sample example for the FORM Based Authentication in JBoss Application Server authenticating against the default JMX Console Security Domain.

However you can create your own security domain and authenticate the users against a data base or a LDAP server to provide more fine grained authentication.

Form-based authentication provides flexibility in defining a custom JSP/HTML page for login, and a separate page to which users are directed if an error occurs during login as compared to other authentication  mechanism.

With form-based authentication, the following things occur:

1. A client requests access to a protected resource.
2. If the client is unauthenticated, the server redirects the client to a login page.
3. The client submits the login form to the server.
4. If the login succeeds, the server redirects the client to the resource. If the login fails, the client is redirected to an error page.

NOTE: Form-based authentication is not particularly secure. In form-based authentication, the content of the user dialog box is sent as plain text, and the target server is not authenticated. This form of authentication can expose your user names and passwords unless all connections are over SSL. If someone can intercept the transmission, the user name and password information can easily be decoded.

Please follow the steps to implement FORM Based mechanism for your Web Resource.

1. Open web.xml file of your application, make an entry for the <login-config> element under the <security-constraints> tag.

The type of authentication mechanism used for the web application is defined by the <auth-method> attribute.

For FORM Based authentication mechanism, it is defined as below.

 

<login-config>

<auth-method>FORM</auth-method>

<form-login-config>

<form-login-page>/login.html</form-login-page>

<form-error-page>/error.html</form-error-page>

</form-login-config>

</login-config>

 

A sample web.xml should look like below.

********************************************************************

 

<?xml version='1.0' encoding='UTF-8'?>

<web-app>

<welcome-file-list>

<welcome-file>welcome.html</welcome-file>

</welcome-file-list>

<security-constraint>

<display-name>Constraint-0</display-name>

<web-resource-collection>

<web-resource-name>Constraint-0</web-resource-name>

<url-pattern>/*</url-pattern>

</web-resource-collection>

<auth-constraint>

<role-name>director</role-name>

</auth-constraint>

<user-data-constraint>

<transport-guarantee>NONE</transport-guarantee>

</user-data-constraint>

</security-constraint>

<login-config>

<auth-method>FORM</auth-method>

<realm-name>SecureRealm</realm-name>

<form-login-config>

<form-login-page>/login.jsp</form-login-page>

<form-error-page>/fail_login.html</form-error-page>

</form-login-config>

</login-config>

<security-role>

<role-name>JBossAdmin</role-name>

</security-role>

</web-app>

 

********************************************************************

2. Create a jboss-web.xml file with the corresponding mappings for the <security-domain> so that we can associate the J2EE authentication mechanism with the underlying JBoss Securty Extension framework.

A Sample jboss-web.xml would like below.

********************************************************************

<jboss>

<security-domain>java:/jaas/jmx-console</security-domain>

</jboss>

********************************************************************

NOTE:  <security-domain> element tells JBoss AS to connect the web application to the “jmx-console” security domain that is defined in the login-config.xml  file as application policy.  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. Specify the security domain entry defined by <application-policy>in the  $JBOSS_HOME/server/<server-profile>/conf/login-config.xml file.

A sample login-config.xml file with the mapping between <security-domain> of jboss-web.xml  and the <application-policy> is defined below.

********************************************************************

 

<application-policy>

<authentication>

<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"

flag="required">

<module-option name="usersProperties">props/jmx-console-users.properties</module-option>

<module-option name="rolesProperties">props/jmx-console-roles.properties</module-option>

</login-module>

</authentication>

</application-policy>

 

********************************************************************

NOTE: This is the out of the box security domain that comes with the JBoss and the default username and password combination is

Username : admin

Password: admin.

The username and password details for the JMX-console security domain  is defined in the “$JBOSS_HOME/server/<server-profile>/conf/ jmx-console-users.properties” file and the related role mapping is defined in “$JBOSS_HOME/server/<server-profile>/conf/ jmx-console-roles.properties”.

However you can program and specify your own custom <security-domain> entry and a mapping <application-policy> in the login-config.xml file.

4: Rename the application folder as WebApp.war and deploy it to the server by copying it to the $JBOSS_HOME/server/<server-profile>/deploy folder

5: Access the application, when you access a protected page then it prompts for the user credentials. Enter the credentials as admin/admin and if the user is authenticated you would be logged in, else you would be redirected to an error page.

For example,

When you access the application it opens the welcome page as below. If you try to open the protected page which requires manager level privileges it would open a login page which is configured in the web.xml and prompts for the user credentials.

Enter username : admin and password: admin, and you would be logged in.

 

If you enter an incorrect username/ password combination or if you don’t have access privileges. The web container redirects you to the fail_login.html page.

NOTE: Whenever the Web  Container receives an access request for a resource, it checks whether there are any already existing sessions associated.  If no session exists, a new session is created. Jboss FormAuthenticator then verifies the credentials of the session.

The sample application for demo can be downloaded from the below link. Just copy the file into the deploy folder of your server profile and access the application as  http://localhost:8080/Formbased/

http://www.4shared.com/file/WMqaLU6H/Formbased.html

References:

http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html/Security_Guide/Enabling_FORM_Authentication.html

http://download.oracle.com/javaee/1.4/tutorial/doc/Security5.html

Cheers,

Wonders Team. 🙂