From 41899a881f8dca3d01c59eaf0af8970b031df123 Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Tue, 26 May 2009 11:28:02 +0000 Subject: [PATCH] Docbook faq --- docs/faq/src/docbook/faq.xml | 268 +++++++++++++++++++++++ docs/faq/src/resources/css/faq.css | 59 +++++ docs/faq/src/resources/css/highlight.css | 35 +++ docs/faq/src/xsl/html-single-custom.xsl | 101 +++++++++ 4 files changed, 463 insertions(+) create mode 100644 docs/faq/src/docbook/faq.xml create mode 100644 docs/faq/src/resources/css/faq.css create mode 100644 docs/faq/src/resources/css/highlight.css create mode 100644 docs/faq/src/xsl/html-single-custom.xsl diff --git a/docs/faq/src/docbook/faq.xml b/docs/faq/src/docbook/faq.xml new file mode 100644 index 0000000000..4200136a43 --- /dev/null +++ b/docs/faq/src/docbook/faq.xml @@ -0,0 +1,268 @@ + + +
+ Frequently Answered Questions (FAQ) + + + + General + + + Will Spring Security take care of all my application security + requirements? + + + + 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 OWASP web site for information on the major issues facing web application developers and the countermeasures you can use against them. + + + + + Why not just use web.xml security? + + + 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: + + Authentication: 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. + + + Web request security: 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. + + + Service layer and domain object security: + 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: + + Separation of concerns: + 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. + + + Support for rich clients and web + services: 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. + + + Layering issues: 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. + + + Authorisation code quality: + 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. + + + + + 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. + + + + + What Java and Spring Framework versions are required? + + + 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. + Spring Security 3.0 will require JDK 1.5 as a minimum and will also + require Spring 3.0. + + + + Common Problems + + + My application goes into an "endless loop" when I try to login, what's + going on? + + + 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. + 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. + 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. + + + + + I get an exception with the message "Access is denied (user is + anonymous);". What's wrong? + + + This is a debug level message which occurs the first time an anonymous + user attempts to access a protected resource. + + 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) + + It is normal and shouldn't be anything to worry about. + + + + + I get an exception with the message "An Authentication object was not + found in the SecurityContext". What's wrong? + + + This is a another debug level message which occurs the first time an + anonymous user attempts to access a protected resource, but when you do not + have an AnonymousProcessingFilter in your filter chain configuration. + + DEBUG [ExceptionTranslationFilter] - Authentication exception occurred; redirecting to authentication entry point + org.springframework.security.AuthenticationCredentialsNotFoundException: An Authentication object was not found in the SecurityContext + at org.springframework.security.intercept.AbstractSecurityInterceptor.credentialsNotFound(AbstractSecurityInterceptor.java:342) + at org.springframework.security.intercept.AbstractSecurityInterceptor.beforeInvocation(AbstractSecurityInterceptor.java:254) + + It is normal and shouldn't be anything to worry about. + + + + + 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. + + + 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. + + + + + I'm forwarding a request to another URL using the RequestDispatcher, but + my security constraints aren't being applied. + + + 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 + <dispatcher> element, a child element of <filter-mapping>. + + + + + + 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. + + + 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. + + <listener> + <listener-classorg.springframework.security.ui.session.HttpSessionEventPublisher</listener-class> + </listener> + + + + + + Common <quote>Howto</quote> Requests + + + 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)? + + + This question comes up repeatedly in the Spring Security forum so you will + find more information there by searching the archives (or through + google). + The submitted login information is processed by an instance of + AuthenticationProcessingFilter. 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 + UsernamePasswordAuthenticationToken), 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 + UsernamePasswordAuthenticationToken. + 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 AuthenticationProvider to handle it (or + extend the standard DaoAuthenticationProvider). If + you have concatenated the fields, you can implement your own + UserDetailsService which splits them up + and loads the appropriate user data for authentication. + + + + + How do I know what dependencies to add to my application to work with + Spring Security? + + + 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. + 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. + + + + +
diff --git a/docs/faq/src/resources/css/faq.css b/docs/faq/src/resources/css/faq.css new file mode 100644 index 0000000000..4314f6b328 --- /dev/null +++ b/docs/faq/src/resources/css/faq.css @@ -0,0 +1,59 @@ +@IMPORT url("highlight.css"); + +html { + padding: 0pt; + margin: 0pt; +} + +body { + margin-left: 10%; + margin-right: 10%; + font-family: Arial, Sans-serif; +} + +div { + margin: 0pt; +} + +p { + text-align: justify; +} + +hr { + border: 1px solid gray; + background: gray; +} + +h1,h2,h3,h4 { + color: #234623; + font-family: Arial, Sans-serif; +} + +pre { + line-height: 1.0; + color: black; +} + +pre.programlisting { + font-size: 10pt; + padding: 7pt 3pt; + border: 1pt solid black; + background: #eeeeee; + clear: both; +} + +div.table { + margin: 1em; + padding: 0.5em; + text-align: center; +} + +div.table table { + display: table; + width: 100%; +} + +div.table td { + padding-left: 7px; + padding-right: 7px; +} diff --git a/docs/faq/src/resources/css/highlight.css b/docs/faq/src/resources/css/highlight.css new file mode 100644 index 0000000000..ffefef72de --- /dev/null +++ b/docs/faq/src/resources/css/highlight.css @@ -0,0 +1,35 @@ +/* + code highlight CSS resemblign the Eclipse IDE default color schema + @author Costin Leau +*/ + +.hl-keyword { + color: #7F0055; + font-weight: bold; +} + +.hl-comment { + color: #3F5F5F; + font-style: italic; +} + +.hl-multiline-comment { + color: #3F5FBF; + font-style: italic; +} + +.hl-tag { + color: #3F7F7F; +} + +.hl-attribute { + color: #7F007F; +} + +.hl-value { + color: #2A00FF; +} + +.hl-string { + color: #2A00FF; +} \ No newline at end of file diff --git a/docs/faq/src/xsl/html-single-custom.xsl b/docs/faq/src/xsl/html-single-custom.xsl new file mode 100644 index 0000000000..ccb1cb31d6 --- /dev/null +++ b/docs/faq/src/xsl/html-single-custom.xsl @@ -0,0 +1,101 @@ + + + + + + + + + + + 1 + + + + + css/faq.css + text/css + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Begin Google Analytics code + + + End Google Analytics code + + + + + Begin LoopFuse code + + + End LoopFuse code + + + \ No newline at end of file