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.
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>
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 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; }
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 Quick Start Guide was meant to get you familiar with Deadbolt within a few minutes. For more detailed documentation, see the reference.