diff --git a/src/site/apt/petclinic-tutorial.apt b/src/site/apt/petclinic-tutorial.apt new file mode 100644 index 0000000000..b54e272eb1 --- /dev/null +++ b/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. + ++------------------------------------------------------ + + + Acegi Filter Chain Proxy + org.acegisecurity.util.FilterToBeanProxy + + targetClass + org.acegisecurity.util.FilterChainProxy + + + + + Acegi Filter Chain Proxy + /* + + ++------------------------------------------------------ + + Next, locate the "contextConfigLocation" parameter, and add a new line into the existing param-value. + The resulting block will look like this: + ++------------------------------------------------------ + + + contextConfigLocation + + /WEB-INF/applicationContext-jdbc.xml + /WEB-INF/applicationContext-acegi-security.xml + + + ++------------------------------------------------------ + + 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: + ++------------------------------------------------------ + + + + + + +
">Home">LogoutPetClinic :: a Spring Framework demonstration
++------------------------------------------------------ + + 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: + ++------------------------------------------------------ + + + CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON + PATTERN_TYPE_APACHE_ANT + /acegilogin.jsp=IS_AUTHENTICATED_ANONYMOUSLY + /**=IS_AUTHENTICATED_REMEMBERED + + ++------------------------------------------------------ + +* 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.

+ +* 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: + ++------------------------------------------------------ + ++------------------------------------------------------ + + Finally, we need to add in the referred-to "methodSecurityInterceptor" bean definition. + So pop an extra bean definition in, as shown below: + ++------------------------------------------------------ + + + + + + + + + + + + + + + + + org.springframework.samples.petclinic.Clinic.*=IS_AUTHENTICATED_REMEMBERED + org.springframework.samples.petclinic.Clinic.storeVisit=ROLE_SUPERVISOR + + + + ++------------------------------------------------------ + + 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: + ++------------------------------------------------------ + + +
" name="formVisitPet"> + "/> + + +
 + ++------------------------------------------------------ + +* What now? + + These steps can be applied to your own application. Although we do suggest + that you visit http://acegisecurity.org + 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.