diff --git a/src/site/apt/petclinic-tutorial.apt b/src/site/apt/petclinic-tutorial.apt index 5292bf3eda..f5b108d631 100644 --- a/src/site/apt/petclinic-tutorial.apt +++ b/src/site/apt/petclinic-tutorial.apt @@ -19,32 +19,68 @@ Tutorial: Adding Security to Spring Petclinic You will also need to download: - * Spring 2.5.2 with dependencies ZIP file + * {{{http://www.springframework.org/download}Spring 2.5.2 with dependencies ZIP file}} - * Spring Security 2.0 + * {{{http://www.springframework.org/download}Spring Security 2.0}} Unzip both files. After unzipping Spring Security, you'll need to unzip the spring-security-sample-tutorial-2.0.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.0. - + 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. -* Add required Spring Security files to Petclinic +* 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 and folder creation. - You can adapt it on any operating system. + 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. +------------------------------------------------------ -mkdir %spring%\samples\petclinic\war\WEB-INF\lib - 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.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib copy %spring-sec-tutorial%\WEB-INF\lib\spring-security-core-tiger-2.0.0-RC1.jar %spring%\samples\petclinic\war\WEB-INF\lib @@ -54,27 +90,10 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe +------------------------------------------------------ -* Configure Petclinic's files +** Configure Petclinic's files - Edit %spring%\samples\petclinic\war\WEB-INF\web.xml and insert the following block of code. - It should be inserted right after the end-tag. - -+------------------------------------------------------ - - - springSecurityFilterChain - org.springframework.web.filter.DelegatingFilterProxy - - - - springSecurityFilterChain - /* - - -+------------------------------------------------------ - - Still inside 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 + 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-ns.xml (Spring config file for Spring Security). The resulting block will look like this: @@ -91,6 +110,46 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe +------------------------------------------------------ + Still inside web.xml, insert the following block of code. + It should be inserted right after the end-tag. + ++------------------------------------------------------ + + + springSecurityFilterChain + org.springframework.web.filter.DelegatingFilterProxy + + + + springSecurityFilterChain + /* + + ++------------------------------------------------------ + 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. + ++------------------------------------------------------ + + + + ++------------------------------------------------------ + +** 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: @@ -106,53 +165,6 @@ copy %spring-sec-tutorial%\WEB-INF\lib\commons-codec-1.3.jar %spring%\samples\pe +------------------------------------------------------ - 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. - -+------------------------------------------------------ - - - - - - - - -+------------------------------------------------------ - - - - -* 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 -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 home page. - Your request should be intercepted and you will be forced to login.

@@ -162,6 +174,7 @@ copy dist\petclinic.war %TOMCAT_HOME%\webapps 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-ns.xml, update @@ -170,27 +183,35 @@ copy dist\petclinic.war %TOMCAT_HOME%\webapps +------------------------------------------------------ - + +------------------------------------------------------ - 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. + 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 + + * 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. Add + 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: +------------------------------------------------------