Channels ▼
RSS

Web Development

An Introduction to jGuard



Allahbaksh can be contacted at Allahbaksh_asadullah@infosys.com and Shailendra can be contacted at shailendra511@yahoo.co.in.


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.

Installing jGuard

Figure 1 depicts how a Web application with jGuard will be configured. To run jGuard, download the necessary JARs from the http://jGuard.net/. Note that you need to have Apache Tomcat set up on your machine; see http://www.coreservlets.com/Apache-Tomcat-Tutorial/ for help there.

[Click image to view at full size]
Figure 1: A Web app with JGuard configured.

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:

<context-param>
	<param-name>authenticationConfigurationLocation</param-name>
	<param-value>/WEB-INF/conf/jGuard/jGuardAuthentication.xml</param-value>
</context-param>
	
<servlet>
	<servlet-name>LoginForm</servlet-name>
	<jsp-file>/WEB-INF/jsp/loginForm.jsp</jsp-file>
</servlet> 

<!—- the URL ‘/LoginForm.do’ is specified in jGuardFilter.xml--> 
<servlet-mapping>   
	<servlet-name>LoginForm</servlet-name>
	<url-pattern>/LoginForm.do</url-pattern>
</servlet-mapping>

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:

<authenticationManager>
net.sf.jGuard.ext.authentication.manager.XmlAuthenticationManager
</authenticationManager>
<authenticationManagerOptions>
	<option>
		<name>authenticationXmlFileLocation</name>
		<value>WEB-INF/conf/jGuard/jGuardUsersPrincipals.xml</value>
	</option>
</authenticationManagerOptions>
<loginModules>
	<loginModule>
	<name>net.sf.jGuard.ext.authentication.loginmodules.XmlLoginModule</name>
	<flag>REQUIRED</flag>
	</loginModule>
</loginModules>

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:

<authorizationManager>
net.sf.jGuard.ext.authorization.manager.XmlAuthorizationManager
</authorizationManager>
<authorizationManagerOptions>
	<option>
		<name>authorizationXmlFileLocation</name>
		<value>WEB-				   		                                                         			INF/conf/jGuard/jGuardPrincipalsPermissions.xml</value>              
	</option>
</authorizationManagerOptions>
</authorizationManager>

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:


<users>
	<userTemplate>
		<name>default</name>
		<privateRequiredCredentials>
			<credTemplateId identity="true">login</credTemplateId>
			<credTemplateId digestNeeded="true">password</credTemplateId>
		</privateRequiredCredentials>
			…
	</userTemplate>

	<user>
		<privateCredentials>
			<credential>
				<id>login</id>
				<value>admin</value>
			</credential>
			<credential>
				<id>password</id>
				<value>admin</value>
			</credential>
		</privateCredentials>
			…
		<principalsRef>
			<principalRef name="admin" applicationName="Basic1"
					definition="${subject.publicCredentials.location.contains('Paris')}"
					active="true" />
		</principalsRef>
</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:

<permissions>
	<domain>
		<name>public</name>
		<permission>
			<name>LoginForm</name>
             	            <class>net.sf.jGuard.core.authorization.permissions.URLPermission 				</class>
			<actions>
				<action>/LoginForm.do</action>
				<action>ANY</action>
			</actions>
		</permission>
		<permission>
			<name>LogonProcess</name>
 		   	 <class>net.sf.jGuard.core.authorization.permissions.URLPermission 				 </class>
			 <actions>
				<action>/LogonProcess.do</action>
				<action>ANY</action>
			</actions>
		</permission>
	</domain>
</permissions>

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:

<principal>
	<name>guest</name>
	<class>net.sf.jGuard.core.principals.RolePrincipal</class>
	<permissionsRef>
		<permissionRef name="LoginForm" />
		<permissionRef name="LogonProcess" />
	</permissionsRef>
</principal>

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.
<filter>
	<indexURI>/Authenticated.do</indexURI>
	<authenticationFailedURI>/AuthenticationFailed.do</authenticationFailedURI>
	<logonURI>/LoginForm.do</logonURI>
	<logonProcessURI>/LogonProcess.do</logonProcessURI>
	<registerURI>/Registration.do</registerURI>
	<registerProcessURI>/RegistrationProcess.do</registerProcessURI>
	<logoffURIs>
		<logoffURI>/LogOff.do</logoffURI>
	</logoffURIs>
	<accessDeniedURI>/AccessDenied.do</accessDeniedURI>
	<authScheme>FORM</authScheme>
	<loginField>login</loginField>
	<passwordField>password</passwordField>
	<goToLastAccessDeniedUriOnSuccess>true</goToLastAccessDeniedUriOnSuccess>
</filter>

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:

<form action="/jGuard/LogonProcess.do">
Login: <input type="text" name="login"/>
Password: <input type="password" name="password"/>
<input type="submit" value="submit"/>
</form>


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

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.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 
Dr. Dobb's TV