浏览代码

More documentation.

Ben Alex 20 年之前
父节点
当前提交
118fde588c
共有 5 个文件被更改,包括 351 次插入12 次删除
  1. 64 0
      doc/xdocs/articles.html
  2. 137 0
      doc/xdocs/faq.html
  3. 10 10
      doc/xdocs/navigation.xml
  4. 2 2
      doc/xdocs/reference.xml
  5. 138 0
      doc/xdocs/suggested.html

+ 64 - 0
doc/xdocs/articles.html

@@ -0,0 +1,64 @@
+<!--
+ * ========================================================================
+ * 
+ * Copyright 2004 Acegi Technology Pty Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * 
+ * ========================================================================
+-->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<head>
+<title>Articles, Blog Posts and Comments covering Acegi Security</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+</head>
+
+<body>
+  <h1>Articles, Blog Posts and Comments covering Acegi Security</h1>
+  <p>Here are some of the external pages mentioning Acegi Security. If you've
+	found another, please let us know.
+  <ul>
+    <li><b><a href="http://www.springframework.org">Spring Forums</a></b>:
+		The first place to look for Acegi Security support (use the 'search' function).
+	</li>
+    <li><b><a href="mail-lists.html">Acegi Security Mailing Lists</a></b>:
+		If you'd like to discuss development of the project.
+	</li>
+    <li><b><a href="http://www.javalobby.org/articles/acegisecurity/part1.jsp">Securing Your Java Applications - Acegi Security Style</a></b>:
+		Matthew Porter wrote this good introductory article for Javalobby.
+	</li>
+    <li><b><a href="http://confluence.sourcebeat.com/display/SPL/Update+Chapters">Spring Live Update Chapters</a></b>:
+		Matt Raible is including Acegi Security in Chapter 12 of his popular ebook.
+	</li>
+    <li><b><a href="http://tp.its.yale.edu/tiki/tiki-view_faq.php?faqId=2#q16">Central Authentication Service FAQ</a></b>:
+		A general overview of how Acegi Security is used with Yale's CAS.
+	</li>
+    <li><b><a href="http://jroller.com/page/habuma/20041124#simplifying_acegi_configuration">Simplifying Acegi Configuration</a></b>:
+		Craig Walls provides a good approach to reusing your Acegi Security configuration between projects.
+	</li>
+    <li><b><a href="http://www.almaer.com/blog/archives/000500.html">Let's leak IoC/DI into standards. You miss them when they aren't there!</a></b>:
+		Ain't that the truth! A good example of where Acegi Security's <code>FilterToProxyBean</code> comes in handy.
+	</li>
+    <li><b><a href="http://www.manageability.org/blog/stuff/single-sign-on-in-java/view">Open Source Identity Management Solutions Written in Java</a></b>:
+		From <code>manageability.org</code>.
+	</li>
+    <li><b><a href="http://www.orablogs.com/fnimphius/archives/000730.html">J2EE Security: Struts "Shale" proposal does improve web application security</a></b>:
+		Frank Nimphius' blog contained some comments on Acegi Security. See
+		our <a href="faq.html">FAQ</a> for additional JAAS comments.
+	</li>
+  </ul>
+</body>
+</html>

+ 137 - 0
doc/xdocs/faq.html

@@ -0,0 +1,137 @@
+<!--
+ * ========================================================================
+ * 
+ * Copyright 2004 Acegi Technology Pty Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * 
+ * ========================================================================
+-->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<head>
+<title>Frequently Asked Questions (FAQ) on Acegi Security</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+</head>
+
+<body>
+  <h1>Frequently Asked Questions</h1>
+  
+  <h2>How do you pronounce "Acegi"?</h2>
+  <p><i>Ah-see-gee</i>. Said quickly, without emphasis on any part.</p>
+
+  <h2>Is it called "Acegi" or "Acegi Security"?</h2>
+  <p>It's official name is <i>Acegi Security System for Spring</i>,
+	although we're happy for it to be abbreviated to
+	<i>Acegi Security</i>. Please don't just call it <i>Acegi</i>, though,
+	as that gets confused with the name of the company that maintains Acegi
+	Security.</p>
+
+  <h2>Why catches 80% of users reporting problems?</h2>
+  <p>80% of support questions are because people have not defined
+	the necessary filters in <code>web.xml</code>, or the filters are being
+	mapped in the incorrect order. Check the 
+	<a href="reference.html">Reference Guide</a>, which
+	has a specific section on filter ordering.</p>
+  
+  <h2>I'm sure my filters are ordered correctly. What else could be wrong?</h2>
+  <p>The next most common source of problems step from custom
+	<code>AuthenticationDao</code> implementations that simply don't properly
+	implement the interface. For example, they return <code>null</code> instead
+	of the user not found exception, or fail to add in the
+	<code>GrantedAuthority[]</code>s. We suggest you write the
+	<code>UserDetails</code> object generated by your <code>AuthenticationDao</code>
+	to the log and check it looks correct.</p>
+
+  <h2>How do I store custom properties, like a user's email address?</h2>
+  <p>In most cases write an <code>AuthenticationDao</code> which returns
+	a subclass of <code>User</code>. Alternatively, write your own
+	<code>UserDetails</code> implementation from scratch and return that.</p>
+
+  <h2>I need some help. What files should I post?</h2>
+  <p>The most important things to post with any support requests on the
+	<a href="http://forum.springframework.org">Spring Forums</a> are your
+	<code>web.xml</code>, <code>applicationContext.xml</code> (or whichever
+	XML loads the security-related beans) as well as any custom
+	<code>AuthenticationDao</code> you might be using. For really odd problems,
+	also switch on debug-level logging and include the resulting log.</p>
+
+  <h2>How do I switch on debug-level logging?</h2>
+  <p>Acegi Security uses Commons Logging, just as Spring does. So you use the
+	same approach as you'd use for Spring. Most people output to Log4J, so
+	the following <code>log4j.properties</code> would work:</p>
+	
+	<pre>
+		log4j.rootCategory=WARN, stdout
+		
+		log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+		log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+		log4j.appender.stdout.layout.ConversionPattern=%d %p %c - %m%n
+		
+		log4j.category.net.sf.acegisecurity=DEBUG</pre>
+
+  <h2>Why doesn't Acegi Security use JAAS?</h2>
+  <p>Acegi Security targets <i>enterprise applications</i>, which are typically
+	multi-user, data-oriented applications that are important to
+	the core business. Acegi Security was designed to provide a portable and effective
+	security framework for this target application type. It was not designed for securing
+	limited privilege runtime environments, such as web browser applets.</p>
+	
+	<p>We did consider JAAS when designing Acegi Security, but it simply
+	wasn't suitable for our purpose. We needed to avoid complex JRE configurations,
+	we needed container portability, and we wanted maximum leveraging of the Spring IoC
+	container. Particularly as limited privilege runtime environments were not
+	an actual requirement, this lead to the natural design of Acegi Security as
+	it exists today.</p>
+	
+	<p>Acegi Security already provides some JAAS integration. It can today authenticate
+	via delegation to a JAAS login module. This means it offers the same level of JAAS
+	integration as many web containers. Indeed the container adapter model supported by
+	Acegi Security allows Acegi Security and container-managed security to happily
+	co-exist and benefit from each other. Any debate about Acegi Security and JAAS
+	should therefore centre on the authorisation issue. An evaluation of major
+	containers and security frameworks would reveal that Acegi Security is by no
+	means unusual in not using JAAS for authorisation.</p>
+	
+	<p>There are many examples of open source applications being preferred to
+	official standards. A few that come to mind in the Java community include
+	using Spring managed POJOs (rather than EJBs), Hibernate (instead of entity beans),
+	Log4J (instead of JDK logging), Tapestry (instead of JSF), and Velocity/FreeMarker
+	(instead of JSP). It's important to recognise that many open source projects do
+	develop into de facto standards, and in doing so play a legitimate and beneficial
+	role in the software development profession.</p>
+
+  <h2>Do you welcome contributions?</h2>
+  <p>Yes. If you've written something and it works well, please feel free to share it.
+	Simply email the contribution to the 
+	<a href="mail-lists.html">acegisecurity-developers</a> list. If you haven't yet
+	written the contribution, we encourage you to send your thoughts to the same 
+	list so that you can receive some initial design feedback.</p>
+	
+	<p>For a contribution to be used, it must have appropriate unit test coverage and
+	detailed JavaDocs. It will ideally have some comments for the Reference Guide
+	as well (this can be sent in word processor or HTML format if desired). This
+	helps ensure the contribution maintains the same quality as the remainder of
+	the project.</p>
+	
+	<p>We also welcome documentation improvements, unit tests, illustrations,
+	people supporting the user community (especially on the forums), design ideas,
+	articles, blog entries, presentations and alike. If you're looking for something
+	to do, you can always email the
+	<a href="mail-lists.html">acegisecurity-developers</a> list and we'll be
+	pleased to suggest something. :-)</p>
+
+</body>
+</html>

+ 10 - 10
doc/xdocs/navigation.xml

@@ -29,30 +29,30 @@
 
 
     <menu name="Overview">
     <menu name="Overview">
       <item name="Home" href="index.html"/>
       <item name="Home" href="index.html"/>
-      <item name="Reference" href="reference.html"/>
       <item name="Building with Maven" href="building.html"/>
       <item name="Building with Maven" href="building.html"/>
       <item name="Downloads" href="downloads.html"/>
       <item name="Downloads" href="downloads.html"/>
-      <item name="Subprojects" href="projects-overview.html"/>
     </menu>
     </menu>
 
 
-    <menu name="Core">
-      <item name="Core" href="multiproject/acegi-security/index.html"/>
-      <item name="Sample SQL" href="dbinit.txt"/>
-    </menu>
-
-    <menu name="Upgrade Help">
+    <menu name="Documentation">
+      <item name="Suggested Steps" href="suggested.html"/>
+      <item name="Reference Guide" href="reference.html"/>
+      <item name="Sample SQL Schema" href="dbinit.txt"/>
+      <item name="Frequently Asked Questions" href="faq.html"/>
+      <item name="External Web Articles" href="articles.html"/>
       <item name="Upgrading to 0.7.0" href="upgrade/upgrade-06-070.html"/>
       <item name="Upgrading to 0.7.0" href="upgrade/upgrade-06-070.html"/>
       <item name="Upgrading to 0.6" href="upgrade/upgrade-05-06.html"/>
       <item name="Upgrading to 0.6" href="upgrade/upgrade-05-06.html"/>
       <item name="Upgrading to 0.5" href="upgrade/upgrade-04-05.html"/>
       <item name="Upgrading to 0.5" href="upgrade/upgrade-04-05.html"/>
       <item name="Upgrading to 0.4" href="upgrade/upgrade-03-04.html"/>
       <item name="Upgrading to 0.4" href="upgrade/upgrade-03-04.html"/>
     </menu>
     </menu>
 
 
-    <menu name="Adapters">
+    <menu name="Projects">
+      <item name="Core" href="multiproject/acegi-security/index.html"/>
       <item name="CAS" href="multiproject/acegi-security-cas/index.html"/>
       <item name="CAS" href="multiproject/acegi-security-cas/index.html"/>
       <item name="Catalina" href="multiproject/acegi-security-catalina/index.html"/>
       <item name="Catalina" href="multiproject/acegi-security-catalina/index.html"/>
       <item name="JBoss" href="multiproject/acegi-security-jboss/index.html"/>
       <item name="JBoss" href="multiproject/acegi-security-jboss/index.html"/>
       <item name="Jetty" href="multiproject/acegi-security-jetty/index.html"/>
       <item name="Jetty" href="multiproject/acegi-security-jetty/index.html"/>
       <item name="Resin" href="multiproject/acegi-security-resin/index.html"/>
       <item name="Resin" href="multiproject/acegi-security-resin/index.html"/>
+      <item name="Subproject Index" href="projects-overview.html"/>
     </menu>
     </menu>
 
 
     <menu name="Samples">
     <menu name="Samples">
@@ -62,7 +62,7 @@
 
 
     <search/>
     <search/>
 
 
-    <menu name="" type="footer">
+    <menu type="footer">
       <item name="Spring Framework" href="http://www.springframework.org/" img="http://www.springframework.org/buttons/spring_white.png"/>
       <item name="Spring Framework" href="http://www.springframework.org/" img="http://www.springframework.org/buttons/spring_white.png"/>
       <item name="Code Coverage by Clover" href="http://www.thecortex.net/clover" img="http://www.thecortex.net/clover/images/clovered1.gif"/>
       <item name="Code Coverage by Clover" href="http://www.thecortex.net/clover" img="http://www.thecortex.net/clover/images/clovered1.gif"/>
     </menu>
     </menu>

+ 2 - 2
doc/xdocs/reference.xml

@@ -39,7 +39,7 @@
             </td>
             </td>
             <td>
             <td>
               The original docbook-generated reference. This is a good place to start if you want
               The original docbook-generated reference. This is a good place to start if you want
-              to use the Acegi System to secure your applications.
+              to use the Acegi Security System to secure your applications.
             </td>
             </td>
           </tr>
           </tr>
 
 
@@ -48,7 +48,7 @@
               <a href="docbook/index.pdf">Reference Guide PDF</a>
               <a href="docbook/index.pdf">Reference Guide PDF</a>
             </td>
             </td>
             <td>
             <td>
-              The pdf version of the reference guide.
+              The PDF version of the reference guide.
             </td>
             </td>
           </tr>
           </tr>
 
 

+ 138 - 0
doc/xdocs/suggested.html

@@ -0,0 +1,138 @@
+<!--
+ * ========================================================================
+ * 
+ * Copyright 2004 Acegi Technology Pty Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * 
+ * ========================================================================
+-->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<head>
+<title>Acegi Security Suggested Steps</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+</head>
+
+<body>
+  <h1>Suggested Steps</h1>
+  <p>Presented below are the steps we encourage you to take in order to gain the most
+  out of Acegi Security in a realistic timeframe.
+  <ol>
+    <li>Your first step is to ensure you're able to actually build Acegi Security. This is
+	because if you encounter any problems the first thing we'll probably suggest you do is
+	upgrade to the latest CVS HEAD. It also means you can try things out if you get stuck,
+	such as adding even more logging messages to the actual Acegi Security core code.
+	The good news is building is actually very easy, and
+	we've gone to a lot of trouble to document what is involved. If you have a working Maven
+	installation, it <i>should</i> be as simple as two commands. Have a look on the
+	<a href="building.html">Building with Maven</a> page, and follow the
+	"Checking Out from CVS" and "Building All JARs" steps. Of course, you can safely skip
+	this step if you don't have time.<br><br>
+	
+	Estimated time: 30 minutes - 2 hours.<br><br>
+	</li>
+	
+	<li>Next up gain a proper understanding of how the Contacts Sample application works.
+	This will probably involve deploying <code>acegi-security-sample-contacts-filter.war</code>.<br><br>
+	
+	The actual <a target="_blank" class="newWindow" href="multiproject/acegi-security-sample-contacts/xref/index.html">java code</a>
+	is a completely standard Spring application, except <code>ContactManagerBackend</code>
+	which shows how we create and delete ACL permissions. The rest of the Java code has no
+	security awareness, with all security services being declared in the XML files
+	(don't worry, there aren't any new XML formats to learn: they're all standard Spring IoC container
+	declarations or the stock-standard <code>web.xml</code>). The main
+	XML files to review are
+	<a target="_blank" class="newWindow" href="http://cvs.sourceforge.net/viewcvs.py/acegisecurity/acegisecurity/samples/contacts/src/main/webapp/filter/WEB-INF/applicationContext-acegi-security.xml?view=auto">applicationContext-acegi-security.xml</a> (from the filter webapp),
+	<a target="_blank" class="newWindow" href="http://cvs.sourceforge.net/viewcvs.py/acegisecurity/acegisecurity/samples/contacts/src/main/webapp/common/WEB-INF/applicationContext-common-authorization.xml?view=auto">applicationContext-common-authorization.xml</a>,
+	<a target="_blank" class="newWindow" href="http://cvs.sourceforge.net/viewcvs.py/acegisecurity/acegisecurity/samples/contacts/src/main/webapp/common/WEB-INF/applicationContext-common-business.xml?view=auto">applicationContext-common-business.xml</a> (just note we add <code>contactManagerSecurity</code> to the services layer target bean), and
+	<a target="_blank" class="newWindow" href="http://cvs.sourceforge.net/viewcvs.py/acegisecurity/acegisecurity/samples/contacts/src/main/webapp/filter/WEB-INF/web.xml?view=auto">web.xml</a> (from the filter webapp).
+	The XML definitions are comprehensively discussed in the
+	<a href="reference.html">Reference Guide</a>.
+	<br><br>
+		
+	To gain the most from reviewing these XML files, we suggest you start by understanding how
+	authentication takes place. There's not much point knowing all about authorization until authentication is
+	really clear, especially the interaction between the <code>ContextHolder</code>, the
+	authentication mechanism (such as <code>AuthenticationProcessingFilter</code>), the
+	authentication commencement process (specifically <code>SecurityEnforcementFilter</code> and
+	say <code>AuthenticationProcessingFilterEntryPoint</code>), and the system that manages authentication
+	data between invocations (say <code>HttpSessionIntegrationFilter</code>). You don't have to
+	know every detail, just basically what they do and the key differences (again, the
+	reference guide should help considerably, as there are diagrams etc).
+	<br><br>	
+		
+	Once you understand authentication in the contacts Sample application, look at how authorisation
+	is handled. Start with <code>FilterSecurityInterceptor</code>'s role and how its
+	regular expression or Ant paths protect URIs. Next up explore how <code>RoleVoter</code>
+	works in our sample application with the <code>FilterSecurityInterceptor</code> and
+	<code>MethodSecurityInterceptor</code>. Finally, review what the
+	<code>BasicAclEntryVoter</code> does in our sample application, in terms of protecting
+	domain objects from method invocations the principal does not have permission to.
+	
+	<br><br>Lastly, get an understanding of how the <code>AfterInvocationProviderManager</code>
+	is being used to stop domain objects being returned to which the principal has no
+	permission, and to filter <code>Collection</code>s so they don't contain domain objects to
+	which the principal has no permission. By all means comment out parts of the Spring IoC XML
+	and see the effect. For example, comment out the <code>AfterInvocationProviderManager</code> (of course, remove its reference
+	in the <code>MethodSecurityInterceptor</code>) and see how all of the contacts get returned.
+	<br><br>
+	
+	Estimated time: 1-2 days.<br><br>
+	</li>
+	
+	<li>By now you will have a good grasp on how Acegi Security works, and all that is left to
+	do is design your own application's implementation. The way we suggested you explore the Contacts Sample
+	is the same way we suggest you implement security in your own application: start with authentication,
+	then add basic web request URI security. Follow it with the standard role voter to protect
+	method invocations. Finally, and only if your application actually needs it, introduce
+	domain object security with the <code>BasicAclEntryVoter</code> and 
+	<code>AfterInvocationProviderManager</code>.
+	<br><br>
+		
+	We do not encourage you to use CAS, container adapters, BASIC authentication, transparent
+	RMI invocation, run-as replacement, rich client integration or any of the other interesting features
+	of Acegi Security until you've got a "bare bones" installation working with <code>DaoAuthenticationProvider</code>,
+	one of Acegi Security's <code>AuthenticationDao</code>s (or your own), and your basic
+	authorisation configuration. Like anything, start with something simple and build on it
+	(this would be the opposite advice if you were building your own security framework,
+	where you would need to cross the highest and most difficult bridges first, to check they
+	are actually possible).<br><br>
+	
+	If you've followed the steps above, and refer back to the reference guide, forums, and FAQ
+	for help, you'll find it pretty easy to implement Acegi Security in your application.
+	Most importantly, you'll be using a security framework that offers you complete container
+	portability, flexibility, and community support - without needing to write and maintain your
+	own code.<br><br>
+	
+	Estimated time: 1-5 days.<br><br>
+	</br>
+	</li>
+	
+  </ol>
+  
+  <p>Please note the time estimates are just that: estimates. They will vary considerably depending
+  on how much experience you have, particularly with Java and Spring. They will also vary depending
+  on how complex your intended security-enabled application will be. Some people need to push the domain
+  object instance access control list capabilities to the maximum, whilst others don't even need anything
+  beyond web request URI security. The good thing is Acegi Security will either directly support your future
+  needs, or provide a clearly-defined extension point for addressing them.
+  
+  <p>
+  We welcome your feedback about how long it has actually taken you to complete each step, so we
+  can update this page and help new users better assess their project timetables in the future.
+  Any other tips on what you found helpful in learning Acegi Security are also very welcome.
+</body>
+</html>