jGuard is an open source library that provides easy authentication and authorization for Java web and desktop applications. It is built on JAAS framework, which is part of the Java J2SE API. The primary advantage of jGuard is that it allows the security system to be independent of the way the credentials of the user are stored; thus, the credentials may be stored in relational databases, XML files, or accessed through LDAP servers. This opens up the possibility of shifting from one data source to another easily.

In this article, we'll explore jGuard installation, and configuring the library to work with XML files and with databases.

All the jGuard related JARs should be placed in the lib folder of your project. You also need to create a conf folder under WEB-INF to store the configuration files. The conf folder, in turn, contains the jGuard subfolder, which holds the necessary jGuard configuration files.

Configuring jGuard to Work with XML

jGuard works in very simple way, needing just a few XML files to be configured for the right authentication and authorization mechanisms. As you are probably aware, "authentication" checks whether the logged-in user is a valid user and "authorization" checks whether the logged-in user has the necessary permissions on the accessed URL as intended.

For jGuard, the following files have to be configured (either as a datastore or in XML files):

web.xml

jGuardAuthentication.xml

jGuardAuthorization.xml

jGuardUsersPrincipals.xml

jGuardPrincipalsPermissions.xml

jGuardFilter.xml

index.jsp

Let's step through each file for explanation. In general, web.xml is used to specify the servlet and JSP mappings. For jGuard, it is also modified to specify the locations of other jGuard config XML files for authentication and authorization. Here is an example of specifying file locations and URL mappings:

In the next file, jGuardAuthentication.xml, we specify which Authentication Manager to use, the location of the data source that contains the credentials of the users, and the login module to use.
In the case of XML authentication, the authentication manager is XmlAuthenticationManager, and the login module is XmlLoginModule. The following code shows a snippet of jGuardAuthentcation.xml configured for XML authentication:

jGuardAuthorization.xml contains the specification for the authorization manager to use and the location of the datasource that maps the principals/roles to the permissions. Principals are used by jGuard to determine whether a user has access rights to a particular resource. The term "principal" is used interchangeably with "roles."

In cases of XML authorization, the authorization manager is XmlAuthorizationManager and the datasource is jGuardPrincipalsPermissions.xml:

Now that we have talked about a couple of datasource XML files, let's briefly discuss the relationship between them. The UsersPriniciples XML file defines the roles, the User Definition Templates, and also the concrete users. Hence, it is the datasource for authentication purposes. And the PriniciplesPermissions XML file maps the roles and the respective URLs available to those roles so that the authorization can be taken care of appropriately.

To define a role, we configure jGuardUsersPrincipals.xml as follows:

<principal>
<name>admin</name>
<class>net.sf.jGuard.core.principals.RolePrincipal</class>
<applicationName>Basic1</applicationName>
<!-- this value must be exacly the same as web.xml´s display-name-->
</principal>

Similarly, the following is the code to first define the user template and then create a user:

The file jGuardPrincipalsPermissions.xml declares which resources (JSP files, servlets) a particular role can access. The most important XML element in this file is <domain>. The <domain> element gives us an elegant way to group a number of permissions under a common name. The idea can be best understood by examining the following code snippet:

In the XML code above, we declare permissions called LoginForm and LogonProcess; and all these permissions are grouped under the domain name "public." Thus, if we want the user to have access to all the aforementioned mentioned resources, we can just give access to the domain named "public." Moreover, if we want fine-grained control, we can give a user access to particular permissions; for example, LoginForm. The method used to assign permissions to a particular role is shown in the following code:

Next on the list, jGuardFilter.xml is an important file for jGuard to decide where the user should be directed after a certain event; for example, if the user is authenticated or wants to register himself. The important elements in this are:

<logonURI>, which specifies the URI where the login form is present

<logonProcessURI>, which specifies the URI that processes the credentials obtained in <logonURI>

<registerURI>, which specifies the URI that contains the registration form

<indexURI>, which specifies the URI where the user should be directed if he is authenticated.

<authenticationFailedURI>, which specifies the URI where the user should be directed if authentication fails

<accessDeniedURI>, which specifies the URI where the user should be directed if he does not have the rights to access the page.

Note that the jGuardFilter.xml present on the official website is not well formed. The following line of code needs to be changed: from <logoffURI>/Logoff.do</logoffURI> to: <logoffURIs><logoffURI>/LogOff.do</logoffURI></logoffURIs>.

In regard to the last file on our configuration list, Index.jsp, JGuard has the filter class AccessFilter, which takes care of logon and logoff processes per your jGuard configuration. In your web application, you simply need to define an Index.jsp in which you do response.redirect to Logon.do, which in turn is mapped to WEB-INF/jsp/ loginForm.jsp. The LoginForm.jsp is to have the following contents:

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Video

This month's Dr. Dobb's Journal

This month,
Dr. Dobb's Journal is devoted to mobile programming. We introduce you to Apple's new Swift programming language, discuss the perils of being the third-most-popular mobile platform, revisit SQLite on Android
, and much more!