diff --git a/doc/docbook/index.xml b/doc/docbook/index.xml index bd8e387d2c..f71c342fe5 100644 --- a/doc/docbook/index.xml +++ b/doc/docbook/index.xml @@ -26,7 +26,7 @@ Reference Documentation - 0.7.0-SNAPSHOT + 0.7.0 @@ -106,29 +106,12 @@ Portable Runtime Project versioning guidelines, available from http://apr.apache.org/versioning.html. - Some improvements are currently intended prior to the 1.0.0 - release. These are: - - - - "Remember me" functionality. Some discussion on this can be - found at - http://sourceforge.net/mailarchive/forum.php?thread_id=5177499&forum_id=40659. - - - - Implementation of an - ObjectDefinitionSource that retrieves its - details from a database. - - - - Whilst this list is subject to change and not in any particular - order, none of the above improvements are likely to result in changes - to the API. The improvements are also relatively minor to implement. - Users of Acegi Security System for Spring should therefore be - comfortable depending on the current version of the project in their - applications. + Some minor improvements are currently intended prior to the + 1.0.0 release, although each of these represent additional + functionality that will in no way modify the project's central + interfaces or classes. Users of Acegi Security System for Spring + should therefore be comfortable depending on the current version of + the project in their applications. @@ -2044,7 +2027,7 @@ public boolean supports(Class clazz); several concrete implementations that integrate with its ACL capabilities. - Figure 4 illustrates Acegi Security's + Figure 5 illustrates Acegi Security's AfterInvocationManager and its concrete implementations. @@ -2055,7 +2038,7 @@ public boolean supports(Class clazz); - Figure 4: After Invocation Implementation + Figure 5: After Invocation Implementation @@ -2481,37 +2464,29 @@ public boolean supports(Class clazz); JBoss Container Adapter. It extracts the authentication from java:comp/env/security/subject. - - - AutoIntegrationFilter automatically - determines which filter to use. This makes a web application WAR - file more portable, as the web.xml is not - hard-coded to a specific - AbstractIntegrationFilter. - - To define the AutoIntegrationFilter + To define the HttpSessionIntegrationFilter (recommended), simply add the following to your web.xml: <filter> - <filter-name>Acegi Security System for Spring Auto Integration Filter</filter-name> + <filter-name>Acegi Security System for Spring HttpSession Integration Filter</filter-name> <filter-class>net.sf.acegisecurity.util.FilterToBeanProxy</filter-class> <init-param> <param-name>targetClass</param-name> - <param-value>net.sf.acegisecurity.ui.AutoIntegrationFilter</param-value> + <param-value>net.sf.acegisecurity.ui.webapp.HttpSessionIntegrationFilter</param-value> </init-param> </filter> <filter-mapping> - <filter-name>Acegi Security System for Spring Auto Integration Filter</filter-name> + <filter-name>Acegi Security System for Spring HttpSession Integration Filter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> You will also need to add the following line to your application context: - <bean id="autoIntegrationFilter" class="net.sf.acegisecurity.ui.AutoIntegrationFilter" /> + <bean id="httpSessionIntegrationFilter" class="net.sf.acegisecurity.ui.webapp.HttpSessionIntegrationFilter" /> Once in the ContextHolder, the standard Acegi Security System for Spring classes can be used. Because @@ -2627,10 +2602,8 @@ public boolean supports(Class clazz); Catalina (Tomcat) Installation - The following was tested with Jakarta Tomcat 4.1.30 and 5.0.19. - We automatically test the following directions using our container - integration test system and these versions of Catalina - (Tomcat). + The following was tested with Jakarta Tomcat 4.1.30 and + 5.0.19. $CATALINA_HOME refers to the root of your Catalina (Tomcat) installation. @@ -2650,7 +2623,7 @@ public boolean supports(Class clazz); Copy acegisecurity.xml into $CATALINA_HOME/conf. - Copy acegi-security-catalina.jar into + Copy acegi-security-catalina-XX.jar into $CATALINA_HOME/server/lib. Copy the following files into @@ -2665,10 +2638,6 @@ public boolean supports(Class clazz); spring.jar - - acegi-security-core.jar - - commons-codec.jar @@ -2683,9 +2652,10 @@ public boolean supports(Class clazz); None of the above JAR files (or - acegi-security.jar) should be in your application's - WEB-INF/lib. The realm name indicated in your - web.xml does not matter with Catalina. + acegi-security-XX.jar) should be in your + application's WEB-INF/lib. The realm name indicated + in your web.xml does not matter with + Catalina. We have received reports of problems using this Container Adapter with Mac OS X. A work-around is to use a script such as @@ -2701,9 +2671,7 @@ $CATALINA_HOME/bin/startup.sh Jetty Installation - The following was tested with Jetty 4.2.18. We automatically - test the following directions using our container integration test - system and this version of Jetty. + The following was tested with Jetty 4.2.18. $JETTY_HOME refers to the root of your Jetty installation. @@ -2740,7 +2708,7 @@ $CATALINA_HOME/bin/startup.sh - acegi-security-jetty-ext.jar + acegi-security-jetty-XX.jar @@ -2757,9 +2725,9 @@ $CATALINA_HOME/bin/startup.sh None of the above JAR files (or - acegi-security.jar) should be in your application's - WEB-INF/lib. The realm name indicated in your - web.xml does matter with Jetty. The + acegi-security-XX.jar) should be in your + application's WEB-INF/lib. The realm name indicated + in your web.xml does matter with Jetty. The web.xml must express the same <realm-name> as your jetty.xml (in the example above, "Spring Powered @@ -2769,9 +2737,7 @@ $CATALINA_HOME/bin/startup.sh JBoss Installation - The following was tested with JBoss 3.2.6. We automatically test - the following directions using our container integration test system - and this version of JBoss. + The following was tested with JBoss 3.2.6. $JBOSS_HOME refers to the root of your JBoss installation. @@ -2852,7 +2818,7 @@ $CATALINA_HOME/bin/startup.sh - acegi-security-jboss-lib.jar + acegi-security-jboss-XX.jar @@ -2869,11 +2835,12 @@ $CATALINA_HOME/bin/startup.sh None of the above JAR files (or - acegi-security.jar) should be in your application's - WEB-INF/lib. The realm name indicated in your - web.xml does not matter with JBoss. However, your - web application's WEB-INF/jboss-web.xml must - express the same <security-domain> as your + acegi-security-XX.jar) should be in your + application's WEB-INF/lib. The realm name indicated + in your web.xml does not matter with JBoss. + However, your web application's + WEB-INF/jboss-web.xml must express the same + <security-domain> as your login-config.xml. For example, to match the above example, your jboss-web.xml would look like this: @@ -2914,7 +2881,7 @@ $CATALINA_HOME/bin/startup.sh - acegi-security-resin-lib.jar + acegi-security-resin-XX.jar @@ -2948,8 +2915,8 @@ $CATALINA_HOME/bin/startup.sh </web-app> With the basic configuration provided above, none of the JAR - files listed (or acegi-security.jar) should be in - your application's WEB-INF/lib. The realm name + files listed (or acegi-security-XX.jar) should be + in your application's WEB-INF/lib. The realm name indicated in your web.xml does not matter with Resin, as the relevant authentication class is indicated by the <authenticator> setting. @@ -3802,7 +3769,7 @@ $CATALINA_HOME/bin/startup.sh The net.sf.acegisecurity.acl package is very simple, comprising only a handful of interfaces and a single class, as - shown in Figure 5. It provides the basic foundation for access control + shown in Figure 6. It provides the basic foundation for access control list (ACL) lookups. @@ -3811,7 +3778,7 @@ $CATALINA_HOME/bin/startup.sh - Figure 5: Access Control List Manager + Figure 6: Access Control List Manager @@ -3864,7 +3831,7 @@ public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authen Integer Masked ACLs Acegi Security System for Spring includes a production-quality - ACL provider implementation, which is shown in Figure 6. + ACL provider implementation, which is shown in Figure 7. @@ -3873,7 +3840,7 @@ public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authen - Figure 6: Basic ACL Manager + Figure 7: Basic ACL Manager @@ -4231,33 +4198,30 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); provided by the system (and confirm your Container Adapter is properly configured if you're using one). - The Contacts sample application includes two deployable versions: - contacts.war is configured with the HTTP Session - Authentication approach, and does not use Container Adapters. The - contacts-container-adapter.war is configured to use a - Container Adapter. If you're just wanting to see how the sample - application works, please use contacts.war as it does - not require special configuration of your container. + If you build from CVS, the Contacts sample application includes + three deployable versions: + acegi-security-sample-contacts-filter.war is + configured with the HTTP Session Authentication approach. The + acegi-security-sample-contacts-ca.war + is configured to use a Container Adapter. Finally, + acegi-security-sample-contacts-cas.war is designed to + work with a Yale CAS server. If you're just wanting to see how the + sample application works, please use + acegi-security-sample-contacts-filter.war + as it does not require special configuration of your container. This is + also the artifact included in ofiical release ZIPs. - If you are going to use the - contacts-container-adapter.war version, first - configure your container as described in the Container Adapters section - of this chapter. Do not modify acegisecurity.xml. It - contains a very basic in-memory authentication configuration that is - compatible with the sample application. - - To deploy, simply copy the relevant - contacts.war or - contacts-container-adapter.war file from the Acegi + To deploy, simply copy the relevant WAR file from the Acegi Security System for Spring distribution into your container’s webapps directory. After starting your container, check the application can load. - Visit http://localhost:8080/contacts (or whichever - URL is appropriate for your web container and the WAR you deployed). A - random contact should be displayed. Click "Refresh" several times and - you will see different contacts. The business method that provides this - random contact is not secured. + Visit + http://localhost:8080/acegi-security-sample-contacts-filter + (or whichever URL is appropriate for your web container and the WAR you + deployed). A random contact should be displayed. Click "Refresh" several + times and you will see different contacts. The business method that + provides this random contact is not secured. Next, click "Debug". You will be prompted to authenticate, and a series of usernames and passwords are suggested on that page. Simply @@ -4290,45 +4254,46 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); If you receive a different message, and deployed - contacts-container-adapter.war, check you have - properly configured your Container Adapter. Refer to the instructions - provided above. + acegi-security-sample-contacts-ca.war, check you have + properly configured your Container Adapter as described elsewhere in + this reference guide. Once you successfully receive the above message, return to the sample application's home page and click "Manage". You can then try out - the application. Notice that only the contacts belonging to the + the application. Notice that only the contacts available to the currently logged on user are displayed, and only users with ROLE_SUPERVISOR are granted access to delete their contacts. Behind the scenes, the MethodSecurityInterceptor is securing the business - objects. If you're using contacts.war, the + objects. If you're using + acegi-security-sample-contacts-filter.war + or acegi-security-sample-contacts-cas.war, the FilterSecurityInterceptor is also securing the HTTP - requests. If using contacts.war, be sure to try - visiting http://localhost:8080/contacts/secure/super, - which will demonstrate access being denied by the - SecurityEnforcementFilter. + requests. If using either of these WARs, be sure to try visiting + http://localhost:8080/contacts/secure/super, which + will demonstrate access being denied by the + SecurityEnforcementFilter. Note the sample + application enables you to modify the access control lists associated + with different contacts. Be sure to give this a try and understand how + it works by reviewing the sample application's application context XML + files. The Contacts sample application also include a client directory. Inside you will find a small - application that queries the backend business objects using the Hessian - and Burlap protocols. This demonstrates how to use the Acegi Security + application that queries the backend business objects using several web + services protocols. This demonstrates how to use the Acegi Security System for Spring for authentication with Spring remoting protocols. To try this client, ensure your servlet container is still running the Contacts sample application, and then execute client marissa - marissa koala. The command-line parameters respectively - represent the owner of the contacts to extract, the username to use, and - the password to use. Note that you may need to edit - client.properties to use a different target URL. To - see that security does indeed work, try running client scott - marissa koala, which will try to obtain - scott's contacts when authenticating as - marissa. To see it work properly, use client - scott scott wombat. + koala. The command-line parameters respectively represent the + username to use, and the password to use. Note that you may need to edit + client.properties to use a different target + URL. Please note the sample application's client does not currently support CAS. You can still give it a try, though, if - you're ambitious: try client scott _cas_stateless_ - YOUR-SERVICE-TICKET-ID-FOR-SCOTT. + you're ambitious: try client _cas_stateless_ + YOUR-SERVICE-TICKET-ID. @@ -4347,29 +4312,19 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); - Run the Ant format task (or use a suitable - IDE plug-in) to convert your code into the project's consistent - style + Use a suitable IDE Jalopy plug-in to convert your code into + the project's consistent style - Ensure your code does not break any unit tests (run the Ant - tests target) - - - - Please use the container integration test system to test your - code in the project's officially supported containers - - - - When writing a new container adapter, expand the container - integration test system to properly test it + Ensure your code does not break any unit tests (run the Maven + test:test goal) If you have added new code, please provide suitable unit tests - (use ant clover.html to view coverage) + (use the Maven clover:html-report to view + coverage) @@ -4387,15 +4342,6 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); create - - Mentioned above is our container integration test system, which - aims to test the Acegi Security System for Spring container adapters - with current, production versions of each container. Some containers - might not be supported due to difficulties with starting or stopping the - container within an Ant target. You will need to download the container - release files as specified in the integration test - readme.txt file. These files are intentionally - excluded from CVS due to their large size.