Document CSRF handler

gitblit · gitblit · commit f2d16bdb2a4f · 2015-05-22T10:50:07.000-04:00
diff --git a/_posts/2015-03-17-security.md b/_posts/2015-03-17-security.md
@@ -6,8 +6,8 @@ date: 2015-03-17 17:29:19
 order: 130
 ---
 
-You can secure your application or only some parts using a filter (a RouteHandler). Remember that routes are matched 
-in the order they are added/defined so put your security filter in front of regular routes (regular routes are 
+You can secure your application or only some parts using a filter (a RouteHandler). Remember that routes are matched
+in the order they are added/defined so put your security filter in front of regular routes (regular routes are
 endpoint routes for a request).
 
 I will show you a simple implementation for a security filter.
@@ -26,12 +26,12 @@ GET("/contact.*", (routeContext) -> {
 // show contacts page
 GET("/contacts", (routeContext) -> routeContext.render("contacts"));
 
-// show contact page for the contact with id specified as path parameter 
+// show contact page for the contact with id specified as path parameter
 GET("/contact/{id}", (routeContext) -> {
 	int id = routeContext.getParameter("id").toInt(0);
 	Contact contact = (id > 0) ? contactService.getContact(id) : new Contact();
-    routeContext.setLocal("contact", contact);	
-    
+    routeContext.setLocal("contact", contact);
+
 	routeContext.render("contact")
 });
 
@@ -73,7 +73,7 @@ The content for login (freemarker engine) can be:
         <#if flash.hasError()>
             ${flash.getError()}
         </#if>
-        
+
         <form method="post" action="/login">
             <input placeholder="Username" name="username">
             <input placeholder="Password" name="password" type="password">
@@ -86,4 +86,31 @@ The content for login (freemarker engine) can be:
 In above code I want to protect all pages (contacts, contact) for the Contact domain entity.  
 The authentication tests to see if the 'username' attribute is present in the session object. If 'username' is present
 than call the regular route with `routeContext.next()` else redirect to the login page.  
-I added `originalDestination` attribute because after authentication process I want to continue with the original destination (original url). 
+I added `originalDestination` attribute because after authentication process I want to continue with the original destination (original url).
+
+### Cross-Site Request Forgery (CSRF) Protection
+
+Pippo includes a simple CSRF handler which will automatically generate a CSRF token on GET requests, if there is no token in the current session, and verify that POST requests include the session's CSRF token.
+
+Using this handler is straight-forward.
+
+**1.** Add an `ALL` filter for the protected path expression with the `CSRFHandler`.
+
+```java
+// add a CSRF token generator and validator
+ALL("/books.*", new CSRFHandler());
+```
+
+**2.** Add a `${csrfToken}` hidden input value on all forms that are POSTed to this protected path expression
+
+```html
+<html>
+	<body>
+		<form method="post" action="/books/5/rename">
+			<input type="hidden" value="${csrfToken}" name="csrfToken" >
+			<input placeholder="Enter a new book title" name="bookTitle">
+			<input type="submit" value="Rename">
+		</form>
+	</body>
+</html>
+```
