More documentation.
This commit is contained in:
Ben Alex
parent
b82c6c8a24
commit
118fde588c
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -29,30 +29,30 @@
|
|||
|
||||
<menu name="Overview">
|
||||
<item name="Home" href="index.html"/>
|
||||
<item name="Reference" href="reference.html"/>
|
||||
<item name="Building with Maven" href="building.html"/>
|
||||
<item name="Downloads" href="downloads.html"/>
|
||||
<item name="Subprojects" href="projects-overview.html"/>
|
||||
</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.6" href="upgrade/upgrade-05-06.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"/>
|
||||
</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="Catalina" href="multiproject/acegi-security-catalina/index.html"/>
|
||||
<item name="JBoss" href="multiproject/acegi-security-jboss/index.html"/>
|
||||
<item name="Jetty" href="multiproject/acegi-security-jetty/index.html"/>
|
||||
<item name="Resin" href="multiproject/acegi-security-resin/index.html"/>
|
||||
<item name="Subproject Index" href="projects-overview.html"/>
|
||||
</menu>
|
||||
|
||||
<menu name="Samples">
|
||||
|
|
@ -62,7 +62,7 @@
|
|||
|
||||
<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="Code Coverage by Clover" href="http://www.thecortex.net/clover" img="http://www.thecortex.net/clover/images/clovered1.gif"/>
|
||||
</menu>
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@
|
|||
</td>
|
||||
<td>
|
||||
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>
|
||||
</tr>
|
||||
|
||||
|
|
@ -48,7 +48,7 @@
|
|||
<a href="docbook/index.pdf">Reference Guide PDF</a>
|
||||
</td>
|
||||
<td>
|
||||
The pdf version of the reference guide.
|
||||
The PDF version of the reference guide.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
Loading…
Reference in New Issue