From 3bc740485428ef598c3b606c7218f90b031adf0b Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Tue, 26 May 2009 11:25:13 +0000 Subject: [PATCH] Restructured docs, faq and removed use of docbkx plugin --- {src/docbkx => docs/manual}/classindex.pl | 0 .../src/docbook}/anon-auth-provider.xml | 0 .../src/docbook}/appendix-db-schema.xml | 0 .../src/docbook}/appendix-namespace.xml | 0 .../src/docbook}/authorization-common.xml | 0 .../src/docbook}/basic-authentication.xml | 2 +- .../manual/src/docbook}/cas-auth-provider.xml | 0 .../manual/src/docbook}/channel-security.xml | 0 .../manual/src/docbook}/class-index-html.xsl | 0 .../src/docbook}/common-auth-services.xml | 0 .../manual/src/docbook}/community.xml | 0 .../src/docbook}/container-adapters.xml | 0 .../manual/src/docbook}/dao-auth-provider.xml | 0 .../src/docbook}/digest-authentication.xml | 0 .../manual/src/docbook}/domain-acls.xml | 0 .../src/docbook}/form-authentication.xml | 0 docs/manual/src/docbook/html-titlepage.xml | 61 +++++++++++ .../manual/src/docbook}/index-classes.xsl | 0 .../manual/src/docbook}/introduction.xml | 0 .../src/docbook}/jaas-auth-provider.xml | 0 .../src/docbook}/ldap-auth-provider.xml | 0 .../manual/src/docbook}/namespace-config.xml | 50 ++++----- docs/manual/src/docbook/pdf-titlepage.xml | 101 ++++++++++++++++++ .../manual/src/docbook}/preauth.xml | 0 .../docbook}/remember-me-authentication.xml | 0 .../src/docbook}/runas-auth-provider.xml | 0 .../manual/src/docbook}/samples.xml | 0 .../manual/src/docbook}/secured-objects.xml | 0 .../src/docbook}/siteminder-auth-provider.xml | 0 .../manual/src/docbook}/springsecurity.xml | 0 .../docbook}/supporting-infrastructure.xml | 0 .../manual/src/docbook}/taglibs.xml | 0 .../src/docbook}/technical-overview.xml | 79 +++++++------- .../src/docbook}/x509-auth-provider.xml | 0 .../src}/resources/images/ACLSecurity.gif | Bin .../resources/images/AccessDecisionVoting.gif | Bin .../src}/resources/images/AfterInvocation.gif | Bin .../src}/resources/images/Authentication.gif | Bin .../resources/images/BasicAclProvider.gif | Bin .../manual/src}/resources/images/Context.gif | Bin .../src}/resources/images/Permissions.gif | Bin .../resources/images/SecurityInterception.gif | Bin .../src}/resources/images/i21-banner-rhs.jpg | Bin .../manual/src}/resources/images/logo.gif | Bin .../manual/src}/resources/images/logo.psd | Bin .../src}/resources/images/s2-banner-rhs.png | Bin .../src}/resources/images/s2_box_logo.png | Bin .../resources/images/xdev-spring_logo.jpg | Bin pom.xml | 64 +---------- src/docbkx/resources/xsl/html.xsl | 6 +- src/site/fml/faq.fml | 90 ++++++++-------- 51 files changed, 281 insertions(+), 172 deletions(-) rename {src/docbkx => docs/manual}/classindex.pl (100%) rename {src/docbkx => docs/manual/src/docbook}/anon-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/appendix-db-schema.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/appendix-namespace.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/authorization-common.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/basic-authentication.xml (98%) rename {src/docbkx => docs/manual/src/docbook}/cas-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/channel-security.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/class-index-html.xsl (100%) rename {src/docbkx => docs/manual/src/docbook}/common-auth-services.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/community.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/container-adapters.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/dao-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/digest-authentication.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/domain-acls.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/form-authentication.xml (100%) create mode 100644 docs/manual/src/docbook/html-titlepage.xml rename {src/docbkx => docs/manual/src/docbook}/index-classes.xsl (100%) rename {src/docbkx => docs/manual/src/docbook}/introduction.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/jaas-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/ldap-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/namespace-config.xml (95%) create mode 100644 docs/manual/src/docbook/pdf-titlepage.xml rename {src/docbkx => docs/manual/src/docbook}/preauth.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/remember-me-authentication.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/runas-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/samples.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/secured-objects.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/siteminder-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/springsecurity.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/supporting-infrastructure.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/taglibs.xml (100%) rename {src/docbkx => docs/manual/src/docbook}/technical-overview.xml (90%) rename {src/docbkx => docs/manual/src/docbook}/x509-auth-provider.xml (100%) rename {src/docbkx => docs/manual/src}/resources/images/ACLSecurity.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/AccessDecisionVoting.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/AfterInvocation.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/Authentication.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/BasicAclProvider.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/Context.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/Permissions.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/SecurityInterception.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/i21-banner-rhs.jpg (100%) rename {src/docbkx => docs/manual/src}/resources/images/logo.gif (100%) rename {src/docbkx => docs/manual/src}/resources/images/logo.psd (100%) rename {src/docbkx => docs/manual/src}/resources/images/s2-banner-rhs.png (100%) rename {src/docbkx => docs/manual/src}/resources/images/s2_box_logo.png (100%) rename {src/docbkx => docs/manual/src}/resources/images/xdev-spring_logo.jpg (100%) diff --git a/src/docbkx/classindex.pl b/docs/manual/classindex.pl similarity index 100% rename from src/docbkx/classindex.pl rename to docs/manual/classindex.pl diff --git a/src/docbkx/anon-auth-provider.xml b/docs/manual/src/docbook/anon-auth-provider.xml similarity index 100% rename from src/docbkx/anon-auth-provider.xml rename to docs/manual/src/docbook/anon-auth-provider.xml diff --git a/src/docbkx/appendix-db-schema.xml b/docs/manual/src/docbook/appendix-db-schema.xml similarity index 100% rename from src/docbkx/appendix-db-schema.xml rename to docs/manual/src/docbook/appendix-db-schema.xml diff --git a/src/docbkx/appendix-namespace.xml b/docs/manual/src/docbook/appendix-namespace.xml similarity index 100% rename from src/docbkx/appendix-namespace.xml rename to docs/manual/src/docbook/appendix-namespace.xml diff --git a/src/docbkx/authorization-common.xml b/docs/manual/src/docbook/authorization-common.xml similarity index 100% rename from src/docbkx/authorization-common.xml rename to docs/manual/src/docbook/authorization-common.xml diff --git a/src/docbkx/basic-authentication.xml b/docs/manual/src/docbook/basic-authentication.xml similarity index 98% rename from src/docbkx/basic-authentication.xml rename to docs/manual/src/docbook/basic-authentication.xml index 9cbaebe28f..a1776af877 100644 --- a/src/docbkx/basic-authentication.xml +++ b/docs/manual/src/docbook/basic-authentication.xml @@ -27,7 +27,7 @@ BasicProcessingFilter and its required collaborator: - + <bean id="basicProcessingFilter" class="org.springframework.security.web.authentication.www.BasicProcessingFilter"> <property name="authenticationManager"><ref bean="authenticationManager"/></property> <property name="authenticationEntryPoint"><ref bean="authenticationEntryPoint"/></property> diff --git a/src/docbkx/cas-auth-provider.xml b/docs/manual/src/docbook/cas-auth-provider.xml similarity index 100% rename from src/docbkx/cas-auth-provider.xml rename to docs/manual/src/docbook/cas-auth-provider.xml diff --git a/src/docbkx/channel-security.xml b/docs/manual/src/docbook/channel-security.xml similarity index 100% rename from src/docbkx/channel-security.xml rename to docs/manual/src/docbook/channel-security.xml diff --git a/src/docbkx/class-index-html.xsl b/docs/manual/src/docbook/class-index-html.xsl similarity index 100% rename from src/docbkx/class-index-html.xsl rename to docs/manual/src/docbook/class-index-html.xsl diff --git a/src/docbkx/common-auth-services.xml b/docs/manual/src/docbook/common-auth-services.xml similarity index 100% rename from src/docbkx/common-auth-services.xml rename to docs/manual/src/docbook/common-auth-services.xml diff --git a/src/docbkx/community.xml b/docs/manual/src/docbook/community.xml similarity index 100% rename from src/docbkx/community.xml rename to docs/manual/src/docbook/community.xml diff --git a/src/docbkx/container-adapters.xml b/docs/manual/src/docbook/container-adapters.xml similarity index 100% rename from src/docbkx/container-adapters.xml rename to docs/manual/src/docbook/container-adapters.xml diff --git a/src/docbkx/dao-auth-provider.xml b/docs/manual/src/docbook/dao-auth-provider.xml similarity index 100% rename from src/docbkx/dao-auth-provider.xml rename to docs/manual/src/docbook/dao-auth-provider.xml diff --git a/src/docbkx/digest-authentication.xml b/docs/manual/src/docbook/digest-authentication.xml similarity index 100% rename from src/docbkx/digest-authentication.xml rename to docs/manual/src/docbook/digest-authentication.xml diff --git a/src/docbkx/domain-acls.xml b/docs/manual/src/docbook/domain-acls.xml similarity index 100% rename from src/docbkx/domain-acls.xml rename to docs/manual/src/docbook/domain-acls.xml diff --git a/src/docbkx/form-authentication.xml b/docs/manual/src/docbook/form-authentication.xml similarity index 100% rename from src/docbkx/form-authentication.xml rename to docs/manual/src/docbook/form-authentication.xml diff --git a/docs/manual/src/docbook/html-titlepage.xml b/docs/manual/src/docbook/html-titlepage.xml new file mode 100644 index 0000000000..99c25da7c4 --- /dev/null +++ b/docs/manual/src/docbook/html-titlepage.xml @@ -0,0 +1,61 @@ + + + + + + + + + + + + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <mediaobject/> + <othercredit/> + <productname/> + <releaseinfo/> + <copyright/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + <legalnotice/> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +</t:templates> diff --git a/src/docbkx/index-classes.xsl b/docs/manual/src/docbook/index-classes.xsl similarity index 100% rename from src/docbkx/index-classes.xsl rename to docs/manual/src/docbook/index-classes.xsl diff --git a/src/docbkx/introduction.xml b/docs/manual/src/docbook/introduction.xml similarity index 100% rename from src/docbkx/introduction.xml rename to docs/manual/src/docbook/introduction.xml diff --git a/src/docbkx/jaas-auth-provider.xml b/docs/manual/src/docbook/jaas-auth-provider.xml similarity index 100% rename from src/docbkx/jaas-auth-provider.xml rename to docs/manual/src/docbook/jaas-auth-provider.xml diff --git a/src/docbkx/ldap-auth-provider.xml b/docs/manual/src/docbook/ldap-auth-provider.xml similarity index 100% rename from src/docbkx/ldap-auth-provider.xml rename to docs/manual/src/docbook/ldap-auth-provider.xml diff --git a/src/docbkx/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml similarity index 95% rename from src/docbkx/namespace-config.xml rename to docs/manual/src/docbook/namespace-config.xml index ae03f3ddce..316af575f2 100644 --- a/src/docbkx/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -29,7 +29,7 @@ you try out the <link xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite</link> as it has special features for working with standard Spring namespaces. </para> <para> To start using the security namespace in your application context, all you need to do is - add the schema declaration to your application context file: <programlisting> + add the schema declaration to your application context file: <programlisting language="xml"> <![CDATA[ <beans xmlns="http://www.springframework.org/schema/beans" xmlns:security="http://www.springframework.org/schema/security" @@ -43,7 +43,7 @@ omit the prefix on all the security namespace elements, making the context easier to read. You may also want to do this if you have your application context divided up into separate files and have most of your security configuration in one of them. Your security application context - file would then start like this <programlisting><![CDATA[ + file would then start like this <programlisting language="xml"><![CDATA[ <beans:beans xmlns="http://www.springframework.org/schema/security" xmlns:beans="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -109,7 +109,7 @@ <section xml:id="ns-web-xml"> <title><literal>web.xml</literal> Configuration The first thing you need to do is add the following filter declaration to your - web.xml file: + web.xml file: springSecurityFilterChain @@ -132,7 +132,7 @@
A Minimal <literal><http></literal> Configuration - All you need to enable web security to begin with is All you need to enable web security to begin with is @@ -145,7 +145,7 @@ the order listed and the first match will be used. So you must put the most specific matches at the top. - To add some users, you can define a set of test data directly in the namespace: To add some users, you can define a set of test data directly in the namespace: @@ -184,7 +184,7 @@
What does <literal>auto-config</literal> Include? The auto-config attribute, as we have used it above, is just a - shorthand syntax for: @@ -210,7 +210,7 @@ based on the features that are enabled and using standard values for the URL which processes the submitted login, the default target URL the user will be sent to and so on. However, the namespace offers plenty of suppport to allow you to customize these options. - For example, if you want to supply your own login page, you could use: @@ -223,7 +223,7 @@ requests for the login page should be excluded from processing by the security filters. Otherwise the request would be matched by the pattern /** and it wouldn't be possible to access the login page itself! If you want to use basic - authentication instead of form login, then change the configuration to @@ -241,7 +241,7 @@ that they user always ends up at this page (regardless of whether the login was "on-demand" or they explicitly chose to log in) by setting the always-use-default-target attribute to "true". This is useful if - your application always requires that the user starts at a "home" page, for example: @@ -260,10 +260,10 @@ dealt with in the LDAP chapter, so we won't cover it here. If you have a custom implementation of Spring Security's UserDetailsService, called "myUserDetailsService" in your - application context, then you can authenticate against this using ]]> - If you want to use a database, then you can use If you want to use a database, then you can use @@ -273,7 +273,7 @@ containing the standard Spring Security user data tables. Alternatively, you could configure a Spring Security JdbcDaoImpl bean and point at that using the - user-service-ref attribute: user-service-ref attribute: @@ -288,7 +288,7 @@ Adding a Password Encoder Often your password data will be encoded using a hashing algorithm. This is supported by the <password-encoder> element. With SHA encoded passwords, - the original authentication provider configuration would look like this: @@ -325,7 +325,7 @@ Adding HTTP/HTTPS Channel Security If your application supports both HTTP and HTTPS, and you require that particular URLs can only be accessed over HTTPS, then this is directly supported using the - requires-channel attribute on <intercept-url>: requires-channel attribute on <intercept-url>: @@ -352,19 +352,19 @@ If you wish to place constraints on a single user's ability to log in to your application, Spring Security supports this out of the box with the following simple additions. First you need to add the following listener to your web.xml - file to keep Spring Security updated about session lifecycle events: + file to keep Spring Security updated about session lifecycle events: org.springframework.security.web.session.HttpSessionEventPublisher -]]> Then add the following line to your application context: Then add the following line to your application context: ... ]]> This will prevent a user from logging in multiple times - a second login will cause the first to be invalidated. Often you would prefer to prevent a - second login, in which case you can use ... @@ -376,7 +376,7 @@
OpenID Login The namespace supports OpenID login either - instead of, or in addition to normal form-based login, with a simple change: @@ -500,7 +500,7 @@ You can add your own filter to the stack, using the custom-filter element and one of these names to specify the position - your filter should appear at: @@ -588,7 +588,7 @@ AccessDecisionManager for it to make the actual decision. This example is taken from the tutorial sample, which is a good starting point if you want to use method security in your application: - + public interface BankService { @Secured("IS_AUTHENTICATED_ANONYMOUSLY") @@ -605,7 +605,7 @@ Adding Security Pointcuts using <literal>protect-pointcut</literal> The use of protect-pointcut is particularly powerful, as it allows you to apply security to many beans with only a simple declaration. Consider the following - example: @@ -620,7 +620,7 @@
The <literal>intercept-methods</literal> Bean Decorator This alternative syntax allows you to specify security for a specific bean by adding - this element within the bean itself. @@ -654,7 +654,7 @@ For method security, you do this by setting the access-decision-manager-ref attribute on global-method-securityto the Id of the appropriate - AccessDecisionManager bean in the application context: AccessDecisionManager bean in the application context: ... @@ -678,7 +678,7 @@ You may want to register additional AuthenticationProvider beans with the ProviderManager and you can do this using the <custom-authentication-provider> element within the bean. For - example: @@ -688,7 +688,7 @@ Another common requirement is that another bean in the context may require a reference to the AuthenticationManager. There is a special element which lets you register an alias for the AuthenticationManager and - you can then use this name elsewhere in your application context. diff --git a/docs/manual/src/docbook/pdf-titlepage.xml b/docs/manual/src/docbook/pdf-titlepage.xml new file mode 100644 index 0000000000..13019b85ac --- /dev/null +++ b/docs/manual/src/docbook/pdf-titlepage.xml @@ -0,0 +1,101 @@ + + + + + + + + + + + + + + + + +]> + + + + + + <subtitle + text-align="center" + font-size="&hsize4;" + space-before="&hsize4space;" + font-family="{$title.fontset}" + /> + + <corpauthor space-before="0.5em" + font-size="&hsize2;" + /> + + <authorgroup space-before="0.5em" + font-size="&hsize2;" + /> + + <author space-before="0.5em" font-size="&hsize2;"/> + <mediaobject space-before="2em" space-after="2em"/> + <releaseinfo space-before="5em" font-size="&hsize2;"/> + + <othercredit space-before="2em" font-weight="normal" font-size="8"/> + <pubdate space-before="0.5em"/> + <revision space-before="0.5em"/> + <revhistory space-before="0.5em"/> + + <abstract space-before="0.5em" + text-align="start" + margin-left="0.1in" + margin-right="0.1in" + font-family="{$body.fontset}" + /> + </t:titlepage-content> + + <t:titlepage-content t:side="verso" text-align="start"> + <copyright space-before="1.5em"/> + <legalnotice space-before="15em"/> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> + </t:titlepage> + +<!-- ==================================================================== --> + +</t:templates> diff --git a/src/docbkx/preauth.xml b/docs/manual/src/docbook/preauth.xml similarity index 100% rename from src/docbkx/preauth.xml rename to docs/manual/src/docbook/preauth.xml diff --git a/src/docbkx/remember-me-authentication.xml b/docs/manual/src/docbook/remember-me-authentication.xml similarity index 100% rename from src/docbkx/remember-me-authentication.xml rename to docs/manual/src/docbook/remember-me-authentication.xml diff --git a/src/docbkx/runas-auth-provider.xml b/docs/manual/src/docbook/runas-auth-provider.xml similarity index 100% rename from src/docbkx/runas-auth-provider.xml rename to docs/manual/src/docbook/runas-auth-provider.xml diff --git a/src/docbkx/samples.xml b/docs/manual/src/docbook/samples.xml similarity index 100% rename from src/docbkx/samples.xml rename to docs/manual/src/docbook/samples.xml diff --git a/src/docbkx/secured-objects.xml b/docs/manual/src/docbook/secured-objects.xml similarity index 100% rename from src/docbkx/secured-objects.xml rename to docs/manual/src/docbook/secured-objects.xml diff --git a/src/docbkx/siteminder-auth-provider.xml b/docs/manual/src/docbook/siteminder-auth-provider.xml similarity index 100% rename from src/docbkx/siteminder-auth-provider.xml rename to docs/manual/src/docbook/siteminder-auth-provider.xml diff --git a/src/docbkx/springsecurity.xml b/docs/manual/src/docbook/springsecurity.xml similarity index 100% rename from src/docbkx/springsecurity.xml rename to docs/manual/src/docbook/springsecurity.xml diff --git a/src/docbkx/supporting-infrastructure.xml b/docs/manual/src/docbook/supporting-infrastructure.xml similarity index 100% rename from src/docbkx/supporting-infrastructure.xml rename to docs/manual/src/docbook/supporting-infrastructure.xml diff --git a/src/docbkx/taglibs.xml b/docs/manual/src/docbook/taglibs.xml similarity index 100% rename from src/docbkx/taglibs.xml rename to docs/manual/src/docbook/taglibs.xml diff --git a/src/docbkx/technical-overview.xml b/docs/manual/src/docbook/technical-overview.xml similarity index 90% rename from src/docbkx/technical-overview.xml rename to docs/manual/src/docbook/technical-overview.xml index e3c37f519e..bbdd072275 100644 --- a/src/docbkx/technical-overview.xml +++ b/docs/manual/src/docbook/technical-overview.xml @@ -8,11 +8,8 @@ <title>Runtime Environment - Spring Security is written to execute within a standard Java 1.4 - Runtime Environment. It also supports Java 5.0, although the Java - types which are specific to this release are packaged in a separate - package with the suffix "tiger" in their JAR filename. As Spring - Security aims to operate in a self-contained manner, there is no need + Spring Security 3.0 requires a Java 5.0 Runtime Environment or higher. + As Spring Security aims to operate in a self-contained manner, there is no need to place any special configuration files into your Java Runtime Environment. In particular, there is no need to configure a special Java Authentication and Authorization Service (JAAS) policy file or @@ -20,7 +17,8 @@ Similarly, if you are using an EJB Container or Servlet Container there is no need to put any special configuration files - anywhere, nor include Spring Security in a server classloader. + anywhere, nor include Spring Security in a server classloader. All the required + files will be contained within your application. This design offers maximum deployment time flexibility, as you can simply copy your target artifact (be it a JAR, WAR or EAR) @@ -184,23 +182,32 @@ if (obj instanceof UserDetails) { authenticate a user). Of course, Spring Security is expressly designed to handle this common requirement, but you'd instead use the project's domain object security capabilities for this purpose. - - Last but not least, sometimes you will need to store the - SecurityContext between HTTP requests. Other times - the principal will re-authenticate on every request, although most of - the time it will be stored. The - HttpSessionContextIntegrationFilter is responsible - for storing a SecurityContext between HTTP - requests. As suggested by the name of the class, the - HttpSession is used to store this information. You - should never interact directly with the HttpSession - for security purposes. There is simply no justification for doing so - - always use the SecurityContextHolder - instead. -
- +
+ Storing the <interfacename>SecurityContext</interfacename> + Last but not least, depending on the type of application, there may need to be + a strategy in place to store the security context between user operations. + In a typical web application, for example, a user logs in once and is subsequently identified + by their session Id. The server caches the principal information for the duration session. + In Spring Security, the responsibility for storing the SecurityContext + between requests falls to the SecurityContextPersistenceFilter, which + by default stores the context as an HttpSession attribute between HTTP + requests. It restores the context to the SecurityContextHolder for each request + and, crucially, clears the SecurityContextHolder when the request completes. + You should never interact directly with the HttpSession for security purposes. + There is simply no justification for doing so - always use the SecurityContextHolder + instead. + + + Many other types of application (for example, a stateless RESTful web service) do not use HTTP sessions and + will re-authenticate on every request. However, it is still important that the + SecurityContextPersistenceFilter is included in the + chain to make sure that the SecurityContextHolder is cleared after each request, + even if + +
+
Summary Just to recap, the major building blocks of Spring Security @@ -219,9 +226,9 @@ if (obj instanceof UserDetails) { - HttpSessionContextIntegrationFilter, to - store the SecurityContext in the - HttpSession between web requests. + SecurityContextPersistenceFilter, to + store the SecurityContext (typically in the + HttpSession) between web requests. @@ -562,18 +569,18 @@ if (obj instanceof UserDetails) {
Extending the Secure Object Model - Only developers contemplating an entirely new way of - intercepting and authorizing requests would need to use secure objects - directly. For example, it would be possible to build a new secure - object to secure calls to a messaging system. Anything that requires - security and also provides a way of intercepting a call (like the AOP - around advice semantics) is capable of being made into a secure - object. Having said that, most Spring applications will simply use the - three currently supported secure object types (AOP Alliance - MethodInvocation, AspectJ - JoinPoint and web request - FilterInvocation) with complete - transparency. + Only developers contemplating an entirely new way of + intercepting and authorizing requests would need to use secure objects + directly. For example, it would be possible to build a new secure + object to secure calls to a messaging system. Anything that requires + security and also provides a way of intercepting a call (like the AOP + around advice semantics) is capable of being made into a secure + object. Having said that, most Spring applications will simply use the + three currently supported secure object types (AOP Alliance + MethodInvocation, AspectJ + JoinPoint and web request + FilterInvocation) with complete + transparency.
diff --git a/src/docbkx/x509-auth-provider.xml b/docs/manual/src/docbook/x509-auth-provider.xml similarity index 100% rename from src/docbkx/x509-auth-provider.xml rename to docs/manual/src/docbook/x509-auth-provider.xml diff --git a/src/docbkx/resources/images/ACLSecurity.gif b/docs/manual/src/resources/images/ACLSecurity.gif similarity index 100% rename from src/docbkx/resources/images/ACLSecurity.gif rename to docs/manual/src/resources/images/ACLSecurity.gif diff --git a/src/docbkx/resources/images/AccessDecisionVoting.gif b/docs/manual/src/resources/images/AccessDecisionVoting.gif similarity index 100% rename from src/docbkx/resources/images/AccessDecisionVoting.gif rename to docs/manual/src/resources/images/AccessDecisionVoting.gif diff --git a/src/docbkx/resources/images/AfterInvocation.gif b/docs/manual/src/resources/images/AfterInvocation.gif similarity index 100% rename from src/docbkx/resources/images/AfterInvocation.gif rename to docs/manual/src/resources/images/AfterInvocation.gif diff --git a/src/docbkx/resources/images/Authentication.gif b/docs/manual/src/resources/images/Authentication.gif similarity index 100% rename from src/docbkx/resources/images/Authentication.gif rename to docs/manual/src/resources/images/Authentication.gif diff --git a/src/docbkx/resources/images/BasicAclProvider.gif b/docs/manual/src/resources/images/BasicAclProvider.gif similarity index 100% rename from src/docbkx/resources/images/BasicAclProvider.gif rename to docs/manual/src/resources/images/BasicAclProvider.gif diff --git a/src/docbkx/resources/images/Context.gif b/docs/manual/src/resources/images/Context.gif similarity index 100% rename from src/docbkx/resources/images/Context.gif rename to docs/manual/src/resources/images/Context.gif diff --git a/src/docbkx/resources/images/Permissions.gif b/docs/manual/src/resources/images/Permissions.gif similarity index 100% rename from src/docbkx/resources/images/Permissions.gif rename to docs/manual/src/resources/images/Permissions.gif diff --git a/src/docbkx/resources/images/SecurityInterception.gif b/docs/manual/src/resources/images/SecurityInterception.gif similarity index 100% rename from src/docbkx/resources/images/SecurityInterception.gif rename to docs/manual/src/resources/images/SecurityInterception.gif diff --git a/src/docbkx/resources/images/i21-banner-rhs.jpg b/docs/manual/src/resources/images/i21-banner-rhs.jpg similarity index 100% rename from src/docbkx/resources/images/i21-banner-rhs.jpg rename to docs/manual/src/resources/images/i21-banner-rhs.jpg diff --git a/src/docbkx/resources/images/logo.gif b/docs/manual/src/resources/images/logo.gif similarity index 100% rename from src/docbkx/resources/images/logo.gif rename to docs/manual/src/resources/images/logo.gif diff --git a/src/docbkx/resources/images/logo.psd b/docs/manual/src/resources/images/logo.psd similarity index 100% rename from src/docbkx/resources/images/logo.psd rename to docs/manual/src/resources/images/logo.psd diff --git a/src/docbkx/resources/images/s2-banner-rhs.png b/docs/manual/src/resources/images/s2-banner-rhs.png similarity index 100% rename from src/docbkx/resources/images/s2-banner-rhs.png rename to docs/manual/src/resources/images/s2-banner-rhs.png diff --git a/src/docbkx/resources/images/s2_box_logo.png b/docs/manual/src/resources/images/s2_box_logo.png similarity index 100% rename from src/docbkx/resources/images/s2_box_logo.png rename to docs/manual/src/resources/images/s2_box_logo.png diff --git a/src/docbkx/resources/images/xdev-spring_logo.jpg b/docs/manual/src/resources/images/xdev-spring_logo.jpg similarity index 100% rename from src/docbkx/resources/images/xdev-spring_logo.jpg rename to docs/manual/src/resources/images/xdev-spring_logo.jpg diff --git a/pom.xml b/pom.xml index 6689d019d5..4e15f92d07 100644 --- a/pom.xml +++ b/pom.xml @@ -431,65 +431,6 @@ - - - org.apache.maven.plugins - maven-site-plugin - 2.0 - - - - com.agilejava.docbkx - docbkx-maven-plugin - 2.0.7 - - - - generate-html - generate-pdf - - pre-site - - - - - org.docbook - docbook-xml - 4.4 - runtime - - - - springsecurity.xml - true - css/html.css - true - src/docbkx/resources/xsl/html_chunk.xsl - src/docbkx/resources/xsl/fopdf.xsl - - - version - ${pom.version} - - - - - - - - - - - - - - - - - - - - @@ -825,10 +766,7 @@ 3.0.0.M3 1.1.2 - 6.1.15 - - ${basedir}/src/docbkx - ${basedir}/target/site/guide + 6.1.18 diff --git a/src/docbkx/resources/xsl/html.xsl b/src/docbkx/resources/xsl/html.xsl index aa7930bab8..30b845c01e 100644 --- a/src/docbkx/resources/xsl/html.xsl +++ b/src/docbkx/resources/xsl/html.xsl @@ -7,7 +7,7 @@ xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - + diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml index 4fe29142df..775ff061f6 100644 --- a/src/site/fml/faq.fml +++ b/src/site/fml/faq.fml @@ -8,28 +8,28 @@ Will Spring Security take care of all my application security requirements? -

Spring Security provides you with a very flexible framework for + 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 + 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. + 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: -

    -
  1. Authentication: The servlet specification provides an approach + + 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 @@ -40,8 +40,8 @@ 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.



    2. -
  2. Web request security: The servlet specification provides an + 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, @@ -49,29 +49,29 @@ 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.



    3. -
  3. Service layer and domain object security: The absence of support + 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:

    -
      -
    1. Separation of concerns: Authorization is a + + 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.
      2. -
    2. Support for rich clients and web services: If an + 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.
      3. -
    3. Layering issues: An MVC controller or view is simply + 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 @@ -81,8 +81,8 @@ 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.
      4. -
    4. Authorisation code quality: It is often said of web + 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 @@ -91,17 +91,17 @@ would offer, and in-house authorization code will typically lack the improvements that emerge from widespread deployment, peer review and new versions. -
    -
    4. -
-

-

+ + + + + 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. -

+ @@ -118,24 +118,24 @@ 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 + 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 + 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. 

@@ -145,13 +145,13 @@ org.springframework.security.AccessDeniedException: Access is denied
     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. 

@@ -161,7 +161,7 @@ org.springframework.security.AccessDeniedException: Access is denied
     					at org.springframework.security.intercept.AbstractSecurityInterceptor.beforeInvocation(AbstractSecurityInterceptor.java:254)
It is normal and shouldn't be anything to worry about. -

+ @@ -170,10 +170,10 @@ org.springframework.security.AccessDeniedException: Access is denied 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. -

+ @@ -205,34 +205,34 @@ org.springframework.security.AccessDeniedException: Access is denied 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).

-

+ 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. -

+