Using Deadbolt

To make use of Deadbolt, there are two things you need to do. One, make changes to your security scheme using the deadbolt-config.xml file. Two, write one or more custom handlers to handle incoming requests. If you decide to use one or more of the built-in Deadbolt handlers, this second step isn't neccessary.

Before you start implementing Deadbolt, it is recommended that you read the introduction to get an overall idea of how Deadbolt works. This will give you the concepts behind Deadbolt and make it easy for you to write your own custom handlers and to understand how the deadbolt-config.xml file is put together.

Configuring the Deadbolt descriptor

Below is a simple Deadbolt descriptor: 

						
<?xml version="1.0"?>
<deadbolt-config>
	<!-- Configure the handlers -->
	<handler>
		<handler-name>MyHandler</handler-name>
		<handler-class>com.mycompany.MyHandler</handler-class>
	</handler>
	<handler>
		<handler-name>MyHandler2</handler-name>
		<handler-class>com.mycompany.MyHandler2</handler-class>
	</hander>
	
	<!-- Configure the rooms to be protected -->
	<room>
		<handler>
			<handler-name>MyHandler</handler-name>
			<execution-order>1</execution-order>
		</handler>
		<handler>
			<handler-name>MyHandler2</handler-name>			
			<execution-order>2</execution-order>
		</handler>
		<init-param>
			<param-name>Param1</param-name>
			<param-value>Hello world!</param-value>
		</init-param>
		<url-pattern>/admin/*</url-pattern>
		<error-page>/admin_forbidden.html</error-page>
	</room>
	<room>
		<handler-name>MyHandler</handler-name>
		<url-pattern>/*</url-pattern>
	</room>
	
	<!-- Configure error information -->
	<global-error-page>/forbidden.jsp</global-error-page>
	<error-messages>
		<error-message>
			<message-key>invalid.username</message-key>
			<message-content>Your username was not valid</message-content>
		</error-message>
		<error-message>
			<message-key>invalid.password</message-key>
			<message-content>Your password was not valid</message-content>
		</error-message>
	</error-messages>
</deadbolt-config>
There are three main parts to a Deadbolt descriptor:
  • Handler definitions
  • Room definitions
  • Global definitions

For each custom or built-in handler that you'll be using in your application, you only need to define it once. Once you've specified the name and class, you can now simply refer to the handler's name throughout the rest of the Deadbolt descriptor.

A "Room" in Deadbolt is a logical chunk of an application that shares attributes of some kind. For example, you may have an entire section of your application designated as an administration area that is only viewable by certain people within your company. You could define an "administration" room that would have it's own handler and is protected. Rooms can have their own chain of handlers, error pages, initial parameters, and URL pattern(s). A Room can have multiple URL pattern elements. Just be aware that the first match wins, so be more restrictive first, then have broader URL patterns that cover entire directories.

Global definitions are just that, global to your application. This includes any predefined error keys that you can use in your handlers. Also, you can specify a global error page here. While each Room can have it's own error page, if you define a global error page and not one on a Room, the global error page will apply to that Room.

Writing custom Deadbolt handlers

Writing custom Deadbolt handlers is easy. Put simply, create a new class extending the DeadboltHandler object. Override the authenticate method, and you have your handler.

The authenticate method of DeadboltHandler looks like this: 

						
public boolean authenticate(HttpServletRequest request,
            HttpServletResponse response, Room room) {
    return false;
}
The method takes three parameters: HttpServletRequest, HttpServletResponse, and Room. We assume you know what to do with the first two. The last however, is Deadbolt specific. When your handler's authenticate method is called by Deadbolt, a Room object will be passed to it. In that object you'll be able to access the various attributes of that Room from within your code. For more on this, see the Deadbolt JavaDocs.

Below is an example of a basic custom handler: 

						
public class MyHandler extends DeadBoltHandler {
	public boolean authenticate(HttpServletRequest request,
            HttpServletResponse response, Room room) {
    	if("johndoe".equals(request.getParameter("username")) &&
    	   "password".equals(request.getParameter("password"))) {
    		return true;
    	} else {
    		return false;
    	}
	}
}
This very basic handler is telling Deadbolt that if the username and password entered meet the entry criteria, let the user enter. Otherwise, kick the user out to the error page.

Where to get more information

This Quick Start Guide was meant to get you familiar with Deadbolt within a few minutes. For more detailed documentation, see the reference.