Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼

Web Development

An Introduction to jGuard

Configuring jGuard to Work with Databases

For this part of the discussion, we'll explain jGuard usage in conjunction with a database using MySQL server. jGuard authenticates and authorizes database users with the following tables: jg_permission, jg_domain, jg_principal_domain, jg_principal_permisison, jg_app_principal, jg_credential, jg_principal, jg_principal_hierarchy, jg_st_principal, jg_st_user, jg_user, jg_user_principal, jg_st_credential.

You need to create one empty database and specify it as part of the jGuard config files. jGuard creates these tables by itself and populates them by using data in jGuardUsersPrincipals.xml and jGuardPrincipalsPermissions.xml. The purpose of these important tables in jGuard is as follows:

  • jg_app_principal: This table contains the principals or roles that are defined for the application. It maps the principals to their respective IDs.
  • )jg_credential: This table contains the concrete credentials of the user. It also maps the credentials of the user to their user_id.
  • jg_domain: This table contains the domains defined in the application. It maps these domains to their IDs. The concept of domains can be understood by referring to jGuardPrincipalsPermissions.xml.
  • jg_permission: This table contains information about all the permissions defined for the application and the actions permitted for them.
  • jg_principal_domain: This table maps the domains defined for the application to the principals that have access to them.
  • jg_principal_permission: This table maps the principals to the permissions they have.
  • jg_user_principal: This table maps the users to the principals they have.

Other important files are authentication.mysql.properties and authorization.mysql.properties, which contain SQL commands to connect and execute for jGuard in MySQL database.

Note that you must ensure the JARs required to connect to the MySQL database have been downloaded (i.e. the mysql-connector JAR).

A potential problem that can arise in getting jGuard to work with databases is the repeated creation of tables every time you start the application. This can be fixed by setting the lower_case_table_names variable to "1" in the my.ini file. So, the following line should be added in the [mysqld] section of my.ini file: lower_case_table_names=1.

In jGuardAuthentication.xml, specify JdbcAuthenticationManager as the authentication manager, and set the login module to be JdbcLoginModule. In addtition, mention the database connection details under the <authenticaitonManagerOptions> element: databaseDriver; databaseDriverUrl; databaseDriverLogin; databaseDriverPassword; authenticationXmlFileLocation; and authenticationDatabaseFileLocation.

The Authentication.mysql.properties file is specified under authenticationDatabaseFileLocation and the JGuardUsersPrincipes file is specified under the authenticationXmlFileLocation as in the following code:

	<name>databaseDriverUrl</name>	<value>jdbc:mysql://icode:3306/mydb</value>
	<name>databaseDriverLogin</name> <value>user1</value>

jGuardAuthorization XML also has to be configured accordingly to work with databases. The authorization manager has to be specified as JdbcAuthorizationManager and the database URL, login and password, authorizationXMLfilelocation and authorizationDatabaseFilelocation have to be provided under authorizationManagerOptions, just as in the process used for the authentication XML.


jGuard has a CAPTCHA module implementation, which helps secure applications against bots. To include a CAPTCHA module, first configure jGuardAuthentication.xml to include the JCaptchaLoginModule. The code to achieve this follows:


Next, update the login page to include code for the generation of the CAPTCHA image and a text field that allows the user to input an answer. The subtle point to note here is that the text field must be named captchaAnswer. The code for this follows:

<img id="captcha" src="/jGuard/Captcha.do"/> 

Captcha: <input type="text" name="captchaAnswer"/>

The primary complication that can arise while using the CAPTCHA module stems from authorization issues. When we specify the source of the image to be /<projectName>/<CaptchaUrl>.do, jGuard begins an authorization process and checks whether we have the privileges to access the URL. By default, if you try to access an URL without authenticating first, jGuard will allow access it only if the “guest” principal has access. Thus, to successfully run the CAPTCHA module, we have to provide the “guest” principal the rights to access the CAPTCHA URL.

Another important point to note is that we will need to write a servlet to aid in image generation. The following lines of code should be added in the doGet() method:

		try {
			CaptchaChallengeBuilder.buildCaptchaChallenge(request, response);
		} catch (Exception e) {
			// TODO Auto-generated catch block

The CAPTCHA URL should then map to this servlet.

Digest Algorithms

To use a digest algorithm for password encryption, we have to declare the algorithm we wish to use in jGuardAuthentication.xml . This can be done using the following code:


The catch here is that jGuard goes into an infinite loop if no user exists in the datasource and the login page will keep on refreshing indefinitely. To solve this problem, you should ensure that at least one user exists. Furthermore, while using a digest algorithm, you have to take care that the password is stored in an encrypted form, not in its original form (for instance, if the user “guest” has the password “guest,” then it should be stored in its MD5 digested form, “21232F297A57A5A743894A0E4A801FC3.”) A good applet that helps us do these conversions can be found at http://www.jensign.com/JavaScience/www/messagedigestj2/index.html.


As we have shown, jGuard is a straightforward library for easy Java web app authentication and authorization. If you are interested in learning more, visit the jGuard wiki at http://jguard.xwiki.com/xwiki/bin/view/Main/WebHome, where you can also find the latest downloads and documentation.

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.