spring-security/src/site/fml/faq.fml

<?xml version="1.0" encoding="UTF-8"?>
<faqs title="Frequently Asked Questions" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/maven-1.x/plugins/faq/faq.xsd">

    <part id="general">
    <title>General</title>
    	
    <faq id="other-concerns">
    	<question>Will Spring Security take care of all my application security requirements?</question>
    	<answer>
    		<p>Spring Security provides you with a very flexible framework for
    			your authentication and authorization requirements, but there are many other considerations
    			for building a secure application that are outside its scope. Web applications are
    			vulnerable to all kinds of attacks which you should be familiar with, preferably before you 
    			start development so you can design and code with them in mind from the beginning. 
    			Check out the <a href="http://www.owasp.org/">OWASP web site</a>
    			for information on the major issues facing web application developers and the countermeasures
    			you can use against them.
    		</p>
    	</answer>
    </faq>
    <faq id="web-xml">
	    <question>Why not just use web.xml security?</question>
	    <answer>
	    
	    <p>Let's assume you're developing an enterprise application based on Spring.
		There are four security concerns you typically need to address: authentication,
		web request security, service layer security (i.e. your methods that implement
		business logic), and domain object instance security (i.e. 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 Spring Security you achieve complete portability - right down to the
				WAR level. Also, Spring 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><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.
				Spring Security provides a far more comprehensive approach. For instance,
				you can use Ant paths or regular expressions, you can consider parts of the
				URI other than simply the requested page (eg you can consider HTTP GET
				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><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
							development time to a point where it would become more
							economical (on a cost-benefit basis) to simply use a dedicated
							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.
					</li></ol>
					</li>
		</ol>
		</p>
		<p>
		For simple applications, servlet specification security may just be enough.
		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>            
		</answer>
		
    </faq>
    <faq id="requirements">
    	<question>What Java and Spring Framework versions are required</question>
    	<answer>
    		Spring Security 2.0.x requires a minimum JDK version of 1.4 and is built against Spring 2.0.x. It should
    		also be compatible with applications using Spring 2.5.x.
    	</answer>
    </faq>

    </part>
    <part id="common-problems">
     	<title>Common Problems</title>
 	    <faq id="login-loop">
 	    	<question>My application goes into an "endless loop" when I try to login, what's going on?</question>
 	    	<answer><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. Make sure your configuration
 	    		allows anonymous access to the login page, either by excluding it from the security filter
 	    		chain or marking it as requiring ROLE_ANONYMOUS.</p>
 	    		<p>If your AccessDecisionManager includes an AutheticatedVoter, you can use the attribute
 	    			"IS_AUTHENTICATED_ANONYMOUSLY". This is automatically available if you are using the
 	    			standard namespace configuration setup.
 	    		</p>
 	    		<p>
 	    			From Spring Security 2.0.1 onwards, when you are using namespace-based configuration, a check will be made 
 	    			on loading the application context and a warning message logged if your login page appears to be protected.
 	    		</p>
 	    	</answer>
 	    </faq>
    	<faq id="anon-access-denied">
    		<question>I get an exception with the message "Access is denied (user is anonymous);". What's wrong?</question>
    		<answer>
    			<p>
    			This is a debug level message which occurs the first time an anonymous user attempts to access a protected
    			resource.
    			<pre>
DEBUG [ExceptionTranslationFilter] - Access is denied (user is anonymous); redirecting to authentication entry point
org.springframework.security.AccessDeniedException: Access is denied
    at org.springframework.security.vote.AffirmativeBased.decide(AffirmativeBased.java:68)
    at org.springframework.security.intercept.AbstractSecurityInterceptor.beforeInvocation(AbstractSecurityInterceptor.java:262)    				
    			</pre>
    				It is normal and shouldn't be anything to worry about.
    			</p>
    		</answer>
    	</faq>
    	<faq id="tomcat-https-session">
    		<question>
    			I'm using Tomcat and have enabled HTTPS for my login page, switching back to HTTP afterwards. It doesn't work - I just 
    			end up back at the login page after authenticating.
    		</question>
    		<answer>
    			<p>
    			This happens because Tomcat sessions created under HTTPS cannot subsequently be used under HTTP and any session state is lost (including 
    			the security context information). Starting in HTTP first should work.
    			</p>
    		</answer>
    	</faq>
    	<faq id="no-security-on-forward">
    		<question>
    			I'm forwarding a request to another URL using the RequestDispatcher, but my security constraints aren't being applied.
    		</question>
    		<answer>
    			Filters are not applied by default to forwards or includes. If you really want the security filters to be applied to forwards and/or includes, 
    			then you have to configure these explicitly in your web.xml using the &lt;dispatcher&gt; element, a child element of &lt;filter-mapping&gt;.
    		</answer>
    	</faq>
    	<faq id="session-listener-missing">
    		<question>
    			I'm trying to use the concurrent session-control support but it won't let me log back in, even if I'm sure I've logged out and haven't exceeded the allowed sessions.
    		</question>
    		<answer>
    			Make sure you have added the listener to your web.xml file. It is essential to make sure that the Spring Security session registry is
    			notified when a session is destroyed. Without it, the session information will not be removed from the registry.
    			<pre>
  &lt;listener&gt;
    &lt;listener-classorg.springframework.security.ui.session.HttpSessionEventPublisher&lt;/listener-class&gt;
  &lt;/listener&gt;    				
    			</pre>
    		</answer>
    	</faq>
    </part>
	  <part id="how-tos">
	  	<title>Common "How To" Requests</title>
	  	<faq id="extra-login-fields">
	  		<question>I need to login in with more information than just the username. How do I add support for extra login fields (e.g. a company name)?</question>
	  		<answer>
	  			<p>This question comes up repeatedly in the Spring Security forum so you will find more information there by searching the archives (or through google).</p>
	  			<p>
	  			The submitted login information is processed by an instance of <i>AuthenticationProcessingFilter</i>. You will need to customize this class to handle
	  				the extra data field(s). One option is to use your own customized authentication token class (rather than the standard <i>UsernamePasswordAuthenticationToken</i>),
	  				another is simply to concatenate the extra fields with the username (for example, using a ":" as the separator) and pass them in the username property of
	  				<i>UsernamePasswordAuthenticationToken</i>.
	  			</p>
	  			<p>
	  				You will also need to customize the actual authentication process. If you are using a custom authentication token class, for example, you will have to write an 
	  				<i>AuthenticationProvider</i> to handle it (or extend the standard <i>DaoAuthenticationProvider</i>). 
	  			  If you have concatenated the fields, you can implement your own <i>UserDetailsService</i> which splits them up and loads the appropriate user data for
	  				authentication.
	  			</p>
	  		</answer>
	  	</faq>
	  	<faq>
	  		<title>How do I know what dependencies to add to my application to work with Spring Security?</title>
	  		<para>
	  			<p>
	  				There is no definite answer here, (it will depend on what features you are using), but a good starting point is to copy those from one of the 
	  				pre-built sample applications WEB-INF/lib directories. For a basic application, you can start with the tutorial sample. If you want to 
	  				use LDAP, with an embedded test server, then use the LDAP sample as a starting point.
	  			</p>
	  			<p>
	  				If you are building your project with maven, then adding the appropriate Spring Security modules to your pom.xml will automatically pull in
	  				the core jars that the framework requires. Any which are marked as "optional" in the Spring Security POM files will have to be added 
	  				to your own pom.xml file if you need them.
	  			</p>
	  		</para>
	  	</faq>
	  </part>
</faqs>