Converted petclinic tutorial file to apt.

src/site/apt/petclinic-tutorial.apt

@@ -0,0 +1,225 @@
+                                ---------------------------------------------
+                                Tutorial: Adding Security to Spring Petclinic
+                                ---------------------------------------------
+
+
+Tutorial: Adding Security to Spring Petclinic
+
+
+
+* Preparation
+
+    To complete this tutorial, you will require a servlet container (such as Tomcat)
+    and a general understanding of using Spring without Acegi Security. The Petclinic
+    sample itself is part of Spring and should help you learn Spring. We suggest you
+    only try to learn one thing at a time, and start with Spring/Petclinic before
+    Acegi Security.
+
+
+
+    You will also need to download:
+
+    * Spring 2.0 M4 with dependencies ZIP file
+    
+    * Acegi Security 1.0.2
+
+
+    Unzip both files. After unzipping Acegi Security, you'll need to unzip the
+    acegi-security-sample-tutorial.war file, because we need some files that are
+    included within it. In the code below, we'll refer to the respective unzipped
+    locations as %spring% and %acegi% (with the latter variable referring to the
+    unzipped WAR, not the original ZIP). There is no need to setup any environment
+    variables to complete the tutorial.
+
+
+* Add required Acegi Security files to Petclinic
+
+
+    We now need to put some extra files into Petclinic. The following commands should work:
+
++------------------------------------------------------
+mkdir %spring%\samples\petclinic\war\WEB-INF\lib
+copy %acegi%\acegilogin.jsp %spring%\samples\petclinic\war
+copy %acegi%\accessDenied.jsp %spring%\samples\petclinic\war
+copy %acegi%\WEB-INF\users.properties %spring%\samples\petclinic\war\WEB-INF
+copy %acegi%\WEB-INF\applicationContext-acegi-security.xml %spring%\samples\petclinic\war\WEB-INF
+copy %acegi%\WEB-INF\lib\acegi-security-1.0.0.jar %spring%\samples\petclinic\war\WEB-INF\lib
+copy %acegi%\WEB-INF\lib\oro-2.0.8.jar %spring%\samples\petclinic\war\WEB-INF\lib
+copy %acegi%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\petclinic\war\WEB-INF\lib
++------------------------------------------------------
+
+
+* Configure Petclinic's files
+
+    Edit %spring%\samples\petclinic\war\WEB-INF\web.xml and insert the following block of code.
+
++------------------------------------------------------
+
+<filter>
+  <filter-name>Acegi Filter Chain Proxy</filter-name>
+  <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
+  <init-param>
+    <param-name>targetClass</param-name>
+    <param-value>org.acegisecurity.util.FilterChainProxy</param-value>
+  </init-param>
+</filter>
+
+<filter-mapping>
+  <filter-name>Acegi Filter Chain Proxy</filter-name>
+  <url-pattern>/*</url-pattern>
+</filter-mapping>
+
++------------------------------------------------------
+
+    Next, locate the "contextConfigLocation" parameter, and add a new line into the existing param-value.
+    The resulting block will look like this:
+
++------------------------------------------------------
+
+<context-param>
+  <param-name>contextConfigLocation</param-name>
+  <param-value>
+      /WEB-INF/applicationContext-jdbc.xml
+      /WEB-INF/applicationContext-acegi-security.xml
+  </param-value>
+</context-param>
+
++------------------------------------------------------
+
+    To make it easier to experiment with the application, now edit
+    %spring%\samples\petclinic\war\WEB-INF\jsp\footer.jsp. Add a new "logout" link, as shown:
+
++------------------------------------------------------
+<table style="width:100%">
+  <tr>
+    <td><a href="<c:url value="/welcome.htm"/>">Home</a></td>
+    <td><a href="<c:url value="/j_acegi_logout"/>">Logout</a></td>
+    <td style="text-align:right;color:silver">PetClinic :: a Spring Framework demonstration</td>
+  </tr>
+</table>
++------------------------------------------------------
+
+    Our last step is to specify which URLs require authorization and which do not. Let's
+    edit %spring%\samples\petclinic\war\WEB-INF\applicationContext-acegi-security.xml.
+    Locate the bean definition for FilterSecurityInterceptor. Edit its objectDefinitionSource
+    property so that it reflects the following:
+
++------------------------------------------------------
+<property name="objectDefinitionSource">
+  <value>
+  CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+  PATTERN_TYPE_APACHE_ANT
+  /acegilogin.jsp=IS_AUTHENTICATED_ANONYMOUSLY
+  /**=IS_AUTHENTICATED_REMEMBERED
+  </value>
+</property>
++------------------------------------------------------
+
+* Start Petclinic's database
+
+    Start the Hypersonic server (this is just normal Petclinic configuration):
+    
++------------------------------------------------------
+cd %spring%\samples\petclinic\db\hsqldb
+server
++------------------------------------------------------
+
+    Insert some data (again, normal Petclinic configuration):
+
++------------------------------------------------------
+cd %spring%\samples\petclinic
+build setupDB
++------------------------------------------------------
+
+* Build and deploy the Petclinic WAR file
+
+
+    Use Petclinic's Ant build script and deploy to your servlet container:
+
++------------------------------------------------------
+cd %spring%\samples\petclinic
+build warfile
+copy dist\petclinic.war %TOMCAT_HOME%\webapps
++------------------------------------------------------
+
+    Finally, start your container and try to visit the home page.
+    Your request should be intercepted and you will be forced to login.</p>
+
+* Optional Bonus: Securing the Middle Tier
+
+    Whilst you've now secured your web requests, you might want to stop users
+    from being able to add clinic visits unless authorized. We'll make it so
+    you need to hold ROLE_SUPERVISOR to add a clinic visit.
+
+    In %spring%\samples\petclinic\war\WEB-INF\applicationContext-jdbc.xml, locate
+    the TransactionProxyFactoryBean definition. Add an additional property after
+    the existing "preInterceptors" property:
+
++------------------------------------------------------
+<property name="postInterceptors" ref="methodSecurityInterceptor"/>
++------------------------------------------------------
+
+    Finally, we need to add in the referred-to "methodSecurityInterceptor" bean definition.
+    So pop an extra bean definition in, as shown below:
+
++------------------------------------------------------
+
+<bean id="methodSecurityInterceptor" class="org.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor">
+  <property name="authenticationManager" ref bean="authenticationManager"/>
+  <property name="accessDecisionManager">
+    <bean class="org.acegisecurity.vote.AffirmativeBased">
+      <property name="allowIfAllAbstainDecisions" value="false"/>
+      <property name="decisionVoters">
+        <list>
+          <bean class="org.acegisecurity.vote.RoleVoter"/>
+          <bean class="org.acegisecurity.vote.AuthenticatedVoter"/>
+        </list>
+      </property>
+    </bean>
+  </property>
+  <property name="objectDefinitionSource">
+    <value>
+      org.springframework.samples.petclinic.Clinic.*=IS_AUTHENTICATED_REMEMBERED
+      org.springframework.samples.petclinic.Clinic.storeVisit=ROLE_SUPERVISOR
+    </value>
+  </property>
+</bean>
+
++------------------------------------------------------
+
+    Redeploy your web application. Use the earlier process to do that. Be careful to
+    ensure that the old Petclinic WAR is replaced by the new Petclinic WAR in your
+    servlet container. Login as "marissa", who has ROLE_SUPERVISOR. You will be able to
+    then view a customer and add a visit. Logout, then login as anyone other than Marissa.
+    You will receive an access denied error when you attempt to add a visit.
+
+    To clean things up a bit, you might want to wrap up by hiding the "add visit" link
+    unless you are authorized to use it. Acegi Security provides a tag library to help
+    you do that. Edit %spring%\samples\petclinic\war\WEB-INF\jsp\owner.jsp. Add
+    the following line to the top of the file:
+
++------------------------------------------------------
+<%@ taglib prefix="authz" uri="http://acegisecurity.org/authz" %>
++------------------------------------------------------
+
+    Next, scroll down and find the link to "add visit". Modify it as follows:
+    
++------------------------------------------------------
+
+<authz:authorize ifAllGranted="ROLE_SUPERVISOR">
+  <form method=GET action="<c:url value="/addVisit.htm"/>" name="formVisitPet<c:out value="${pet.id}"/>">
+    <input type="hidden" name="petId" value="<c:out value="${pet.id}"/>"/>
+      <input type="submit" value="Add Visit"/>
+  </form>
+</authz:authorize>
+
++------------------------------------------------------
+
+* What now?
+
+    These steps can be applied to your own application. Although we do suggest
+    that you visit <a href="http://acegisecurity.org">http://acegisecurity.org</a>
+    and in particular review the "Suggested Steps" for getting started with Acegi
+    Security. The suggested steps are optimized for learning Acegi Security quickly
+    and applying it to your own projects. It also includes realistic time estimates
+    for each step so you can plan your integration activities.</p>