2004-12-22 13:15:07 +00:00
|
|
|
<!--
|
|
|
|
|
* ========================================================================
|
|
|
|
|
*
|
|
|
|
|
* 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>
|
|
|
|
|
|
2004-12-23 00:15:00 +00:00
|
|
|
<h2>What is Acegi Security?</h2>
|
2004-12-25 07:18:17 +00:00
|
|
|
<p>Acegi Security is an open source project that provides comprehensive authentication
|
2004-12-23 00:15:00 +00:00
|
|
|
and authorisation services for enterprise applications based on
|
|
|
|
|
<a href="http://www.springframework.org">The Spring Framework</a>.
|
|
|
|
|
Acegi Security can authenticate using a variety of pluggable providers, and
|
|
|
|
|
can authorise both web requests and method invocations.
|
|
|
|
|
Acegi Security provides an integrated security approach across
|
|
|
|
|
these various targets, and also offers access control list (ACL) capabilities to
|
|
|
|
|
enable individual domain object instances to be secured. At an implementation
|
|
|
|
|
level, Acegi Security is managed through Spring's inversion of control and
|
|
|
|
|
lifecycle services, and actually enforces security using interception through
|
|
|
|
|
servlet Filters and Java AOP frameworks. In terms of AOP framework support, Acegi
|
|
|
|
|
Security currently supports AOP Alliance (which is what the
|
|
|
|
|
Spring IoC container uses internally) and AspectJ, although additional frameworks
|
|
|
|
|
can be easily supported.</p>
|
|
|
|
|
|
|
|
|
|
<h2>Why not just use web.xml security?</h2>
|
2004-12-23 01:30:04 +00:00
|
|
|
<p>Let's assume you're developing an enterprise application based on Spring.
|
2004-12-23 00:15:00 +00:00
|
|
|
There are four security concerns you typically need to address: authentication,
|
|
|
|
|
web request security, service layer security (ie your methods that implement
|
|
|
|
|
business logic), and domain object instance security (ie different domain objects
|
|
|
|
|
have different permissions). With these typical requirements in mind:
|
|
|
|
|
<ol>
|
|
|
|
|
<li><b>Authentication</b>: The servlet specification provides an approach
|
|
|
|
|
to authentication. However, you will need to configure the container
|
|
|
|
|
to perform authentication which typically requires editing of
|
|
|
|
|
container-specific "realm" settings. This makes a non-portable
|
|
|
|
|
configuration, and if you need to write an actual Java class to implement
|
|
|
|
|
the container's authentication interface, it becomes even more non-portable.
|
|
|
|
|
With Acegi Security you achieve complete portability - right down to the
|
|
|
|
|
WAR level. Also, Acegi Security offers a choice of production-proven
|
|
|
|
|
authentication providers and mechanisms, meaning you can switch your
|
|
|
|
|
authentication approaches at deployment time. This is particularly
|
|
|
|
|
valuable for software vendors writing products that need to work in
|
|
|
|
|
an unknown target environment.<br><br></li>
|
|
|
|
|
<li><b>Web request security:</b> The servlet specification provides an
|
|
|
|
|
approach to secure your request URIs. However, these URIs can only be
|
|
|
|
|
expressed in the servlet specification's own limited URI path format.
|
|
|
|
|
Acegi Security provides a far more comprehensive approach. For instance,
|
|
|
|
|
you can use Ant paths or regular expressions, you can consider parts of the
|
2004-12-25 07:18:17 +00:00
|
|
|
URI other than simply the requested page (eg you can consider HTTP GET
|
2004-12-23 00:15:00 +00:00
|
|
|
parameters), and you can implement your own runtime source of configuration
|
|
|
|
|
data. This means your web request security can be dynamically changed during
|
|
|
|
|
the actual execution of your webapp.<br><br></li>
|
|
|
|
|
<li><b>Service layer and domain object security:</b> The absence of support
|
|
|
|
|
in the servlet specification for services layer security or domain object
|
|
|
|
|
instance security represent serious limitations for multi-tiered
|
|
|
|
|
applications. Typically developers either ignore these requirements, or
|
|
|
|
|
implement security logic within their MVC controller code (or even worse,
|
|
|
|
|
inside the views). There are serious disadvantages with this approach:<br><br>
|
|
|
|
|
<ol>
|
|
|
|
|
<li><i>Separation of concerns:</i> Authorization is a
|
|
|
|
|
crosscutting concern and should be implemented as such.
|
|
|
|
|
MVC controllers or views implementing authorization code
|
|
|
|
|
makes it more difficult to test both the controller and
|
|
|
|
|
authorization logic, more difficult to debug, and will
|
|
|
|
|
often lead to code duplication.</li>
|
|
|
|
|
<li><i>Support for rich clients and web services:</i> If an
|
|
|
|
|
additional client type must ultimately be supported, any
|
|
|
|
|
authorization code embedded within the web layer is
|
|
|
|
|
non-reusable. It should be considered that Spring remoting
|
|
|
|
|
exporters only export service layer beans (not MVC
|
|
|
|
|
controllers). As such authorization logic needs to be
|
|
|
|
|
located in the services layer to support a multitude of
|
|
|
|
|
client types.</li>
|
|
|
|
|
<li><i>Layering issues:</i> An MVC controller or view is simply
|
|
|
|
|
the incorrect architectural layer to implement authorization
|
|
|
|
|
decisions concerning services layer methods or domain object
|
|
|
|
|
instances. Whilst the Principal may be passed to the services
|
|
|
|
|
layer to enable it to make the authorization decision, doing
|
|
|
|
|
so would introduce an additional argument on every services
|
|
|
|
|
layer method. A more elegant approach is to use a ThreadLocal
|
|
|
|
|
to hold the Principal, although this would likely increase
|
2004-12-23 01:30:04 +00:00
|
|
|
development time to a point where it would become more
|
|
|
|
|
economical (on a cost-benefit basis) to simply use a dedicated
|
2004-12-23 00:15:00 +00:00
|
|
|
security framework.</li>
|
|
|
|
|
<li><i>Authorisation code quality:</i> It is often said of web
|
|
|
|
|
frameworks that they "make it easier to do the right things,
|
|
|
|
|
and harder to do the wrong things". Security frameworks are
|
|
|
|
|
the same, because they are designed in an abstract manner for
|
|
|
|
|
a wide range of purposes. Writing your own authorization code
|
|
|
|
|
from scratch does not provide the "design check" a framework
|
|
|
|
|
would offer, and in-house authorization code will typically
|
|
|
|
|
lack the improvements that emerge from widespread deployment,
|
|
|
|
|
peer review and new versions.
|
|
|
|
|
</ol>
|
|
|
|
|
</li>
|
|
|
|
|
</ol>
|
2004-12-23 01:30:04 +00:00
|
|
|
For simple applications, servlet specification security may just be enough.
|
2004-12-23 00:15:00 +00:00
|
|
|
Although when considered within the context of web container portability,
|
|
|
|
|
configuration requirements, limited web request security flexibility, and
|
|
|
|
|
non-existent services layer and domain object instance security, it becomes
|
|
|
|
|
clear why developers often look to alternative solutions.
|
|
|
|
|
</p>
|
|
|
|
|
|
2004-12-22 13:15:07 +00:00
|
|
|
<h2>How do you pronounce "Acegi"?</h2>
|
2004-12-23 00:15:00 +00:00
|
|
|
<p><i>Ah-see-gee</i>. Said quickly, without emphasis on any part.
|
|
|
|
|
Acegi isn't an acronym, name of a Greek God or anything similarly
|
|
|
|
|
impressive - it's just letters #1, #3, #5, #7 and #9 of the alphabet.</p>
|
2004-12-22 13:15:07 +00:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2004-12-23 00:15:00 +00:00
|
|
|
<h2>What catches 80% of users reporting problems?</h2>
|
2004-12-22 13:15:07 +00:00
|
|
|
<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>
|
2004-12-25 07:18:17 +00:00
|
|
|
<p>The next most common source of problems stem from custom
|
2004-12-22 13:15:07 +00:00
|
|
|
<code>AuthenticationDao</code> implementations that simply don't properly
|
2004-12-25 07:18:17 +00:00
|
|
|
implement the interface contract. For example, they return <code>null</code> instead
|
2004-12-22 13:15:07 +00:00
|
|
|
of the user not found exception, or fail to add in the
|
2004-12-23 01:30:04 +00:00
|
|
|
<code>GrantedAuthority[]</code>s. Whilst <code>DaoAuthenticationProvider</code>
|
2004-12-25 07:18:17 +00:00
|
|
|
does its best to check the <code>AuthenticationDao</code> returns a valid
|
2004-12-23 01:30:04 +00:00
|
|
|
<code>UserDetails</code>, we suggest you write the
|
|
|
|
|
<code>UserDetails</code> object to the log and check it looks correct.</p>
|
2004-12-22 13:15:07 +00:00
|
|
|
|
2005-09-20 02:31:23 +00:00
|
|
|
<h2>Common Problem #1: My application goes into an "endless loop" when I try to login, what's going on?</h2>
|
|
|
|
|
<p>A common user problem with infinite loop and redirecting to the login page
|
|
|
|
|
is caused by accidently configuring the login page as a "secured" resource.
|
|
|
|
|
See this forum <a href="http://forum.springframework.org/viewtopic.php?t=8766">post</a> for more details.</p>
|
|
|
|
|
|
|
|
|
|
<h2>Common Problem #2: My application pages don't seem to be protected.</h2>
|
|
|
|
|
<p>If you are securing web resources and they dont seem to be matched in the URL patterns,
|
|
|
|
|
check the objectDefinitionSource in the FilterSecurityInterceptor.
|
|
|
|
|
If you are using the <tt>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</tt> setting,
|
|
|
|
|
then the URL patterns configured MUST be in lowercase.
|
|
|
|
|
<p>
|
|
|
|
|
For example, making a request ending in <tt>/someAction.do</tt> will need
|
|
|
|
|
to be configured as: <tt>/someaction.do</tt> (Note the case).
|
|
|
|
|
<pre>
|
|
|
|
|
<property name="objectDefinitionSource">
|
|
|
|
|
<value>
|
|
|
|
|
CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
|
|
|
|
|
PATTERN_TYPE_APACHE_ANT
|
|
|
|
|
/index.jsp=ROLE_ANONYMOUS,ROLE_USER
|
|
|
|
|
/someaction.do=ROLE_USER
|
|
|
|
|
<value>
|
|
|
|
|
</property>
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
See this forum <a href="http://forum.springframework.org/viewtopic.php?t=8746">post</a> for more details.</p>
|
|
|
|
|
|
2005-09-21 01:53:35 +00:00
|
|
|
<h2>Common Problem #3: How do I disable a user after a number of failed logins?</h2>
|
|
|
|
|
<p>A common user requirement is to disable / lock an account after a number of failed login attempts.
|
|
|
|
|
Acegi itself does not provide anything "out of the box", however in your application you can implement
|
|
|
|
|
and register an <tt>org.springframework.context.ApplicationListener</tt>. Inside your application
|
|
|
|
|
event listener you can then check for an instanceof the particular <tt>AuthenticationFailureEvent</tt>
|
|
|
|
|
and then call your application user management interface to update the user details.
|
|
|
|
|
<p>
|
|
|
|
|
For example:
|
|
|
|
|
<pre>
|
|
|
|
|
public void onApplicationEvent(ApplicationEvent event) {
|
|
|
|
|
|
|
|
|
|
// check failed event
|
|
|
|
|
if(event instanceof AuthenticationFailurePasswordEvent){
|
|
|
|
|
// call user management interface to increment failed login attempts, etc.
|
|
|
|
|
. . .
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
See this forum <a href="http://forum.springframework.org/viewtopic.php?t=8525">post</a> for more details.</p>
|
|
|
|
|
|
|
|
|
|
<h2>Common Problem #4: I am changing my password using a web controller and DAO, why is my password still not being refreshed?</h2>
|
|
|
|
|
<p>There are three things you must do to make a user password change take affect:
|
|
|
|
|
<ul>
|
|
|
|
|
<li> Change the password using your authentication DAO</li>
|
|
|
|
|
<li> Remove the user from the User Cache (i.e. if you have a cache configured) </li>
|
|
|
|
|
<li> Update the <tt>ContextHolder</tt> to include the new <tt>Authentication</tt> object and password</li>
|
|
|
|
|
</ul>
|
|
|
|
|
See this forum <a href="http://forum.springframework.org/viewtopic.php?t=4624">post</a> for more details.</p>
|
|
|
|
|
|
2004-12-22 13:15:07 +00:00
|
|
|
<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>
|
|
|
|
|
|
2004-12-23 00:15:00 +00:00
|
|
|
<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>
|
|
|
|
|
|
2004-12-22 13:15:07 +00:00
|
|
|
<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
|
2004-12-23 01:30:04 +00:00
|
|
|
role in professional software development.</p>
|
2004-12-22 13:15:07 +00:00
|
|
|
|
|
|
|
|
<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>
|
