spring-security/src/site/apt/petclinic-tutorial.apt

                                ---------------------------------------------
                                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 Spring 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
    Spring Security.



    You will also need to download:

    * {{{http://www.springframework.org/download}Spring 2.5.5 with dependencies ZIP file}}

    * {{{http://www.springframework.org/download}Spring Security 2.0.4}}


    Unzip both files. After unzipping Spring Security, you'll need to unzip the
    spring-security-sample-tutorial-2.0.4.war file, because we need some files that are
    included within it. After unzipping the war file, you will see a folder called 
    spring-security-samples-tutorial-2.0.4.

    In the code below, we'll refer to the respective unzipped
    locations as %spring% and %spring-sec-tutorial% (with the later variable 
    referring to the unzipped WAR, not the original ZIP). There is no need to setup 
    any environment variables to complete the tutorial.


* 1st part: Run the Petclinic application without Spring Security
	
	In order to make sure that you work in a stable environment, we will first
	set up the Petclinic application, without Spring Security.

** Start Petclinic's database

    Start the Hypersonic server:

+------------------------------------------------------
cd %spring%\samples\petclinic\db\hsqldb
server
+------------------------------------------------------

    Insert some data:

+------------------------------------------------------
cd %spring%\samples\petclinic
ant 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 petclinic home page.
    You are now able to browse the whole application without any authentication needed


* Second part: set up Spring security

** Add required Spring Security files to Petclinic


    We now need to put some extra files into Petclinic. 
    The following example is based on Windows MS-DOS. It only involves file copy. 
    We believe you can adapt it easily on any operating system.  

+------------------------------------------------------
copy %spring-sec-tutorial%\WEB-INF\applicationContext-security-ns.xml %spring%\samples\petclinic\war\WEB-INF
copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-core-2.0.4.jar %spring%\samples\petclinic\war\WEB-INF\lib
copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-core-tiger-2.0.4.jar %spring%\samples\petclinic\war\WEB-INF\lib
copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-acl-2.0.4.jar %spring%\samples\petclinic\war\WEB-INF\lib
copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-taglibs-2.0.4.jar %spring%\samples\petclinic\war\WEB-INF\lib
copy %spring-sec-tutorial%\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. The "contextConfigLocation" specifies Spring configuration files that should be used
    by the petclinic application. Locate the "contextConfigLocation" parameter and add a new line into 
    the existing param-value. Now that we are using Spring Security, It should also declare 
    applicationContext-security.xml (Spring config file for Spring Security).
    The resulting block will look like this:

+------------------------------------------------------

<context-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>
      /WEB-INF/applicationContext-jdbc.xml
      /WEB-INF/applicationContext-security.xml
  </param-value>
</context-param>

+------------------------------------------------------

    Still inside web.xml, insert the following block of code.
    It should be inserted right after the </context-param> end-tag.

+------------------------------------------------------

    <filter>
        <filter-name>springSecurityFilterChain</filter-name>
        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
    </filter>

    <filter-mapping>
      <filter-name>springSecurityFilterChain</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>

+------------------------------------------------------
   Our last step is to specify which URLs require authorization and which do not. Let's
    edit %spring%\samples\petclinic\war\WEB-INF\applicationContext-security-ns.xml.
    All URLs ending with '.do' will be protected.

+------------------------------------------------------
	<http auto-config="true">
		<intercept-url pattern="/*.do" access="ROLE_USER" />
		<intercept-url pattern="/**" access="IS_AUTHENTICATED_ANONYMOUSLY" />
	</http>
+------------------------------------------------------

** Test

    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. 

    Finally, start your container and try to visit the home page.
    Your request should be intercepted and you will be forced to login.
    You can now log in using  the usernames and passwords that are documented at the end
    of applicationContext-security-ns.xml file. 

** Log out

    To make it easier to experiment with the application, users should be able to log out of the application. 
    Edit %spring%\samples\petclinic\war\WEB-INF\jsp\footer.jsp. Add a new "logout" link, as shown:

+------------------------------------------------------

<table class="footer">
    <tr>
      <td><a href="<c:url value="/welcome.do"/>">Home</a></td>
      <td style="text-align:right;color:silver">PetClinic :: a Spring Framework demonstration</td>
      <td align="right"><img src="<c:url value="/images/springsource-logo.png"/>"/></td>
      <td align="right"><a href="<c:url value="/j_spring_security_logout"/>">Logout</a></td>
    </tr>
</table>

+------------------------------------------------------



* 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.

** protect-pointcut

    Finally, we need to declare a protect-pointcut that will hold the security restriction. 
    Inside %spring%\samples\petclinic\war\WEB-INF\applicationContext-security.xml, update
    the global-method-security tag as follows:

+------------------------------------------------------

	<global-method-security secured-annotations="enabled">
		<protect-pointcut expression="execution(* org.springframework.samples.petclinic.Clinic.storeVisit(..))" 
		access="ROLE_SUPERVISOR"/>
	</global-method-security>

+------------------------------------------------------

    Redeploy your web application.
    Login as "peter" that does not have the "ROLE_SUPERVISOR" role.

    * Click on "Find owners"

    * Keep the "last name" field blank and validate

    * Select one owner in the list

    * Click on "add visit"

    * Add a description and validate

    Access should be denied.

    Now log out and try  "rod", who has ROLE_SUPERVISOR. It should be working.

** The "sec" tag-library

    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. Spring Security provides a tag library to help
    you do that. Edit %spring%\samples\petclinic\war\WEB-INF\jsp\owner.jsp (please 
    make sure that you are opening owner.jsp, not owners.jsp !!). Add
    the following line to the top of the file:

+------------------------------------------------------
<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>
+------------------------------------------------------

    Next, scroll down and find the link to "add visit". Modify it as follows:

+------------------------------------------------------

<sec:authorize ifAllGranted="ROLE_SUPERVISOR">
  <form method="GET" action="<c:url value="/addVisit.do"/>" name="formVisitPet${pet.id}">
      <input type="hidden" name="petId" value="${pet.id}"/>
      <p class="submit"><input type="submit" value="Add Visit"/></p>
  </form>
</sec:authorize>

+------------------------------------------------------

* What now?

    These steps can be applied to your own application. We suggest that you review
    the "Suggested Steps" for getting started with Spring
    Security on the web site. The suggested steps are optimized for learning Spring Security quickly
    and applying it to your own projects. This section also includes realistic time estimates
    for each step so you can plan your integration activities.