diff --git a/docs/faq/src/docbook/faq.xml b/docs/faq/src/docbook/faq.xml index 66608408d4..655d9fc5d7 100644 --- a/docs/faq/src/docbook/faq.xml +++ b/docs/faq/src/docbook/faq.xml @@ -2,10 +2,11 @@
Frequently Answered - Questions (FAQ) + Questions (FAQ) +
+ General Questions - General Will Spring Security take care of all my application security requirements? @@ -141,8 +142,13 @@ combining them in a complex system. + +
+
+ Common Problems + - Common Problems + Authentication My application goes into an "endless loop" when I try to login, what's going on? @@ -186,37 +192,78 @@ I get an exception with the message "An Authentication object was - not found in the SecurityContext". What's wrong? + 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 AnonymousAuthenticationFilter in your filter - chain configuration. - + anonymous user attempts to access a protected resource, but when you do not + have an AnonymousAuthenticationFilter 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. + It is normal and shouldn't be anything to worry about. + + + Session Management + + Session management issues are a common source of forum questions. If you are developing Java web applications, you + should understand how the session is maintained between the servlet container and the user's browser. You should also + understand the difference between secure and non-secure cookies and the implications of using HTTP/HTTPS and switching + between the two. Spring Security has nothing to do with maintaining the session or providing session identifiers. This is + entirely handled by the servlet container. + + + + + I'm using Spring Security's concurrent session control to prevent users from logging in more than once at a time. + When I open another browser window after logging in, it doesn't stop me from logging in again. Why can I log + in more than once? + + Browsers generally maintain a single session per browser instance. You cannot have two separate + sessions at once. So if you log in again in another window or tab you are just reauthenticating in the same session. + The server doesn't know anything about tabs, windows or browser instances. All it sees are HTTP requests and it ties + those to a particular session according to the value of the the JSESSIONID cookie that they contain. + When a user authenticates during a session, Spring Security's concurrent session control checks the number of + other authenticated sessions that they have. If they are already authenticated + with the same session, then re-authenticating will have no effect. + + + + + Why does the session Id change when I authenticate through Spring Security? + With the default configuration, Spring Security invalidates the existing session when the user + authenticates and creates a new one, transferring the session data to it. The intention is to change the session + identifier to prevent session-fixation attacks. You can find more about this online and in the reference + manual. + + + - I'm using Tomcat and have enabled HTTPS for my login page, + I'm using Tomcat (or some other servlet container) 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 a session in HTTP first should work - as the session cookie won't be marked as secure. + This happens because sessions created under HTTPS, for which the session cookie is marked as + secure, cannot subsequently be used under HTTP. The browser will not send the cookie + back to the server and any session state will be lost (including the security context information). + Starting a session in HTTP first should work as the session cookie won't be marked as secure. - - 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 not switching between HTTP and HTTPS but my session is still getting lost + + + Sessions are maintained either by exchanging a session cookie or by adding the a jsessionid + parameter to URLs (this happens automatically if you are using JSTL to output URLs, or if you call + HttpServletResponse.encodeUrl on URLs (before a redirect, for example). + If clients have cookies disabled, and you are not rewriting URLs to include the jsessionid, then the + session will be lost. Note that the use of cookues os preferred for security reasons, as it does not expose the session information in + the URL. + + I'm trying to use the concurrent session-control support but it @@ -231,35 +278,6 @@ ]]> - - I have a user who has definitely been authenticated, but when I try - to access the SecurityContextHolder during some - requests, the Authentication is null. Why - can't I see the user information? - If you have excluded the request from the security filter chain using - the attribute filters='none' in the - <intercept-url> element that matches the URL - pattern, then the SecurityContextHolder will not be - populated for that request. Check the debug log to see whether the request - is passing through the filter chain. (You are reading the debug log, - right?). - - - I have added Spring Security's <global-method-security> - element to my application context but if I add security annotations to my - Spring MVC controller beans (Struts actions etc.) then they don't seem to - have an effect. - The application context which holds the Spring MVC beans for the - dispatcher servlet is a child application context of the main application - context which is loaded using the - ContextLoaderListener you define in your - web.xml. The beans in the child context are not - visible in the parent context so you need to either move the - <global-method-security> declaration to the web context or moved the - beans you want secured into the main application context. - Generally we would recommend applying method security at the - service layer rather than on individual web controllers. - Spring Security is creating a session somewhere, even though I've configured it not to, @@ -282,7 +300,52 @@ - Spring Security Architecture Questions + Miscellaneous + + 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 have added Spring Security's <global-method-security> + element to my application context but if I add security annotations to my + Spring MVC controller beans (Struts actions etc.) then they don't seem to + have an effect. + The application context which holds the Spring MVC beans for the + dispatcher servlet is a child application context of the main application + context which is loaded using the + ContextLoaderListener you define in your + web.xml. The beans in the child context are not + visible in the parent context so you need to either move the + <global-method-security> declaration to the web context or moved the + beans you want secured into the main application context. + Generally we would recommend applying method security at the + service layer rather than on individual web controllers. + + + I have a user who has definitely been authenticated, but when I try + to access the SecurityContextHolder during some + requests, the Authentication is null. Why + can't I see the user information? + If you have excluded the request from the security filter chain using + the attribute filters='none' in the + <intercept-url> element that matches the URL + pattern, then the SecurityContextHolder will not be + populated for that request. Check the debug log to see whether the request + is passing through the filter chain. (You are reading the debug log, + right?). + + + +
+
Spring Security Architecture Questions + + How do I know which package class X is in? The best way of locating classes is by installing the Spring Security @@ -328,9 +391,37 @@ + + How do I know which dependencies to add to my application to work + with Spring Security? + It will depend on what features you are using and what type of + application you are developing. With Spring Security 3.0, the project jars + are divided into clearly distinct areas of functionality, so it is + straightforward to work out which Spring Security jars you need from your + application requirements. All applications will need the + spring-security-core jar. If you're developing a + web application, you need the spring-security-web jar. + If you're using security namespace configuration you need the + spring-security-config jar, for LDAP support you + need the spring-security-ldap jar and so on. + For third-party jars the situation isn't always quite so + obvious. 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 as dependencies 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. + + +
+
+ Common <quote>Howto</quote> Requests + - 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 @@ -354,6 +445,29 @@ UserDetailsService which splits them up and loads the appropriate user data for authentication. + + How do I access the user's IP Address (or other web-request data) in a UserDetailsService? + + + Obviously you can't (without resorting to something like thread-local variables) since + the only information supplied to the interface is the username. Instead of implementing + UserDetailsService, you should implement + AuthenticationProvider directly and extract the information + from the supplied Authentication token. + + + In a standard web setup, the getDetails() method on the + Authentication object will return an instance of + WebAuthenticationDetails. If you need additional information, + you can inject a custom AuthenticationDetailsSource + into the authentication filter you are using. If you are using the namespace, for example with + the <form-login> element, then you should remove this element and replace it + with a <custom-filter> declaration pointing to an explicitly configured + UsernamePasswordAuthenticationFilter. + + + + How do I define the secured URLs within an application dynamically? @@ -373,10 +487,7 @@ Both method and web security are protected by subclasses of AbstractSecurityInterceptor which is configured with a SecurityMetadataSource from which it - obtains the metadata for a particular method or filter invocation - This class previouly went by the rather obscure name - of ObjectDefinitionSource, but has been - renamed in Spring Security 3.0. For web security, + obtains the metadata for a particular method or filter invocation. For web security, the interceptor class is FilterSecurityInterceptor and it uses the marker interface FilterInvocationSecurityMetadataSource. @@ -426,30 +537,7 @@ DefaultFilterInvocationSecurityMetadataSource. - - How do I know which dependencies to add to my application to work - with Spring Security? - It will depend on what features you are using and what type of - application you are developing. With Spring Security 3.0, the project jars - are divided into clearly distinct areas of functionality, so it is - straightforward to work out which Spring Security jars you need from your - application requirements. All applications will need the - spring-security-core jar. If you're developing a - web application, you need the spring-security-web jar. - If you're using security namespace configuration you need the - spring-security-config jar, for LDAP support you - need the spring-security-ldap jar and so on. - For third-party jars the situation isn't always quite so - obvious. 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 as dependencies 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. - + How do I authenticate against LDAP but load user roles from a database? @@ -489,4 +577,5 @@ +
diff --git a/docs/faq/src/resources/css/faq.css b/docs/faq/src/resources/css/faq.css index 03cfffd644..e7108d0909 100644 --- a/docs/faq/src/resources/css/faq.css +++ b/docs/faq/src/resources/css/faq.css @@ -29,6 +29,11 @@ h1,h2,h3,h4 { font-family: Arial, Sans-serif; } +h4.title { + font-size: 1.2em; + margin-bottom: 0; +} + pre { line-height: 1.0; color: black; diff --git a/docs/faq/src/xsl/html-single-custom.xsl b/docs/faq/src/xsl/html-single-custom.xsl index 6fb09740b7..cb728e04b4 100644 --- a/docs/faq/src/xsl/html-single-custom.xsl +++ b/docs/faq/src/xsl/html-single-custom.xsl @@ -8,30 +8,18 @@ - - 1 - - css/faq.css text/css - + + article toc + qandaset toc + +