From f0c4cccb0d8bbc2b15a1833b26025f088615faa8 Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Sun, 16 May 2010 14:10:42 +0100 Subject: [PATCH] SEC-1479: Clarify that matching is against servletPath + pathInfo for ant pattern matching. Added some extra pointers to request-matching info in namespace doc. --- .../manual/src/docbook/appendix-namespace.xml | 434 ++++++------ docs/manual/src/docbook/namespace-config.xml | 661 +++++++++--------- .../web/util/AntPathRequestMatcher.java | 9 +- 3 files changed, 562 insertions(+), 542 deletions(-) diff --git a/docs/manual/src/docbook/appendix-namespace.xml b/docs/manual/src/docbook/appendix-namespace.xml index 61d9006fa4..d6aeb0a88d 100644 --- a/docs/manual/src/docbook/appendix-namespace.xml +++ b/docs/manual/src/docbook/appendix-namespace.xml @@ -8,40 +8,40 @@ and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document). If you haven't used the namespace before, please read the - introductory chapter on namespace configuration, as + introductory chapter on namespace configuration, as this is intended as a supplement to the information there. Using a good quality XML editor while editing a configuration based on the schema is recommended as this will provide contextual information on which elements and attributes are available as well as comments explaining their purpose. The namespace is written in RELAX NG Compact format and later converted into - an XSD schema. If you are familiar with this format, you may wish to examine the schema file directly. + xlink:href="http://www.relaxng.org/">RELAX NG Compact format and later converted + into an XSD schema. If you are familiar with this format, you may wish to examine the schema file directly.
Web Application Security - the <literal><http></literal> Element The <http> element encapsulates the security configuration for the web layer of your application. It creates a - FilterChainProxy bean named "springSecurityFilterChain" which + FilterChainProxy bean named "springSecurityFilterChain" which maintains the stack of security filters which make up the web security configuration - See the introductory chapter for how to set - up the mapping from your web.xml + See the introductory chapter for how to + set up the mapping from your web.xml . Some core filters are always created and others will be added to the stack depending on the attributes child elements which are present. The positions of the standard filters are fixed (see the filter order - table in the namespace introduction), removing a common source of errors with + table in the namespace introduction), removing a common source of errors with previous versions of the framework when users had to configure the filter chain explicitly in theFilterChainProxy bean. You can, of course, still do this if you need full control of the configuration. All filters which require a reference to the - AuthenticationManager will be automatically injected with - the internal instance created by the namespace configuration (see the introductory chapter for more on the - AuthenticationManager). + AuthenticationManager will be automatically injected + with the internal instance created by the namespace configuration (see the introductory chapter for more on the + AuthenticationManager). The <http> namespace block always creates an - HttpSessionContextIntegrationFilter, an - ExceptionTranslationFilter and a - FilterSecurityInterceptor. These are fixed and cannot be replaced - with alternatives. + HttpSessionContextIntegrationFilter, an + ExceptionTranslationFilter and a + FilterSecurityInterceptor. These are fixed and cannot be + replaced with alternatives.
<literal><http></literal> Attributes The attributes on the <http> element control some of the @@ -51,45 +51,47 @@ Provides versions of HttpServletRequest security methods such as isUserInRole() and getPrincipal() which are implemented by adding a - SecurityContextHolderAwareRequestFilter bean to the + SecurityContextHolderAwareRequestFilter bean to the stack. Defaults to "true".
<literal>request-matcher</literal> Defines the RequestMatcher strategy used in the FilterChainProxy and the beans created by the - intercept-url to match incoming requests. Options are + intercept-url to match incoming requests. Options are currently ant, regex and - ciRegex, for ant, regular-expression and case-insensitive + ciRegex, for ant, regular-expression and case-insensitive regular-expression repsectively. A separate instance is created for each - intercept-url element using its pattern - and method attributes (see below). Ant paths are matched - using an AntPathRequestMatcher and regular expressions - are matched using a RegexRequestMatcher. See the Javadoc - for these classes for more details. Ant paths are the default strategy. + intercept-url element using its + pattern and method attributes (see + below). Ant paths are matched using an + AntPathRequestMatcher and regular expressions are + matched using a RegexRequestMatcher. See the Javadoc for + these classes for more details on exactly how the matching is preformed. Ant + paths are the default strategy.
<literal>realm</literal> Sets the realm name used for basic authentication (if enabled). Corresponds to the realmName property on - BasicAuthenticationEntryPoint. + BasicAuthenticationEntryPoint.
<literal>entry-point-ref</literal> Normally the AuthenticationEntryPoint used will be set depending on which authentication mechanisms have been configured. This attribute allows this behaviour to be overridden by defining a customized - AuthenticationEntryPoint bean which will start - the authentication process. + AuthenticationEntryPoint bean which will + start the authentication process.
<literal>access-decision-manager-ref</literal> Optional attribute specifying the ID of the - AccessDecisionManager implementation which should - be used for authorizing HTTP requests. By default an - AffirmativeBased implementation is used for with a - RoleVoter and an - AuthenticatedVoter. + AccessDecisionManager implementation which + should be used for authorizing HTTP requests. By default an + AffirmativeBased implementation is used for with a + RoleVoter and an + AuthenticatedVoter.
<literal>access-denied-page</literal> @@ -99,40 +101,41 @@
<literal>once-per-request</literal> Corresponds to the observeOncePerRequest property of - FilterSecurityInterceptor. Defaults to "true". + FilterSecurityInterceptor. Defaults to "true". +
<literal>create-session</literal> Controls the eagerness with which an HTTP session is created. If not set, defaults to "ifRequired". Other options are "always" and "never". The setting of this attribute affect the allowSessionCreation and - forceEagerSessionCreation properties of - HttpSessionContextIntegrationFilter. - allowSessionCreation will always be true unless this + forceEagerSessionCreation properties of + HttpSessionContextIntegrationFilter. + allowSessionCreation will always be true unless this attribute is set to "never". forceEagerSessionCreation is "false" unless it is set to "always". So the default configuration allows session creation but does not force it. The exception is if concurrent session control is enabled, when forceEagerSessionCreation will be set to true, regardless of what the setting is here. Using "never" would then cause an exception during the initialization of - HttpSessionContextIntegrationFilter. + HttpSessionContextIntegrationFilter.
<literal>use-expressions</literal> - Enables EL-expressions in the access attribute, as described - in the chapter on expression-based access-control. - + Enables EL-expressions in the access attribute, as + described in the chapter on expression-based + access-control.
<literal><access-denied-handler></literal> This element allows you to set the errorPage property for the default AccessDeniedHandler used by the - ExceptionTranslationFilter, (using the - error-page attribute, or to supply your own implementation using - the ref attribute. This is discussed in more detail in the + ExceptionTranslationFilter, (using the + error-page attribute, or to supply your own implementation + using the ref attribute. This is discussed in more detail in the section on the - ExceptionTranslationFilter. + ExceptionTranslationFilter.
The <literal><intercept-url></literal> Element @@ -141,8 +144,8 @@ the FilterInvocationSecurityMetadataSource used by the FilterSecurityInterceptor and to exclude particular patterns from the filter chain entirely (by setting the attribute - filters="none"). It is also responsible for configuring a - ChannelAuthenticationFilter if particular URLs need to be + filters="none"). It is also responsible for configuring a + ChannelAuthenticationFilter if particular URLs need to be accessed by HTTPS, for example. When matching the specified patterns against an incoming request, the matching is done in the order in which the elements are declared. So the most specific matches patterns should come first and the most @@ -150,8 +153,8 @@
<literal>pattern</literal> The pattern which defines the URL path. The content will depend on the - request-matcher attribute from the containing http element, - so will default to ant path syntax. + request-matcher attribute from the containing http + element, so will default to ant path syntax.
<literal>method</literal> @@ -163,9 +166,9 @@
<literal>access</literal> Lists the access attributes which will be stored in the - FilterInvocationSecurityMetadataSource for the - defined URL pattern/method combination. This should be a comma-separated list of - the security configuration attributes (such as role names). + FilterInvocationSecurityMetadataSource for + the defined URL pattern/method combination. This should be a comma-separated + list of the security configuration attributes (such as role names).
<literal>requires-channel</literal> @@ -173,15 +176,15 @@ particular URL pattern should be accessed over HTTP or HTTPS respectively. Alternatively the value any can be used when there is no preference. If this attribute is present on any - <intercept-url> element, then a - ChannelAuthenticationFilter will be added to the filter - stack and its additional dependencies added to the application + <intercept-url> element, then a + ChannelAuthenticationFilter will be added to the + filter stack and its additional dependencies added to the application context. If a <port-mappings> configuration is added, this will be used to by the SecureChannelProcessor and - InsecureChannelProcessor beans to determine the ports + InsecureChannelProcessor beans to determine the ports used for redirecting to HTTP/HTTPS.
@@ -201,7 +204,7 @@ Each child <port-mapping> element defines a pair of HTTP:HTTPS ports. The default mappings are 80:443 and 8080:8443. An example of overriding these can be found in the namespace introduction. + >namespace introduction.
The <literal><form-login></literal> Element @@ -210,30 +213,30 @@ application context to provide authentication on demand. This will always take precedence over other namespace-created entry points. If no attributes are supplied, a login page will be generated automatically at the URL "/spring-security-login" - This feature is really just provided for convenience and is not intended for - production (where a view technology will have been chosen and can be used to - render a customized login page). The class - DefaultLoginPageGeneratingFilter is responsible for - rendering the login page and will provide login forms for both normal form login - and/or OpenID if required. + This feature is really just provided for convenience and is not intended + for production (where a view technology will have been chosen and can be + used to render a customized login page). The class + DefaultLoginPageGeneratingFilter is responsible + for rendering the login page and will provide login forms for both normal + form login and/or OpenID if required. The behaviour can be customized using the following attributes.
<literal>login-page</literal> The URL that should be used to render the login page. Maps to the - loginFormUrl property of the - LoginUrlAuthenticationEntryPoint. Defaults to + loginFormUrl property of the + LoginUrlAuthenticationEntryPoint. Defaults to "/spring-security-login".
<literal>login-processing-url</literal> Maps to the filterProcessesUrl property of - UsernamePasswordAuthenticationFilter. The default value - is "/j_spring_security_check". + UsernamePasswordAuthenticationFilter. The default + value is "/j_spring_security_check".
<literal>default-target-url</literal> Maps to the defaultTargetUrl property of - UsernamePasswordAuthenticationFilter. If not set, the + UsernamePasswordAuthenticationFilter. If not set, the default value is "/" (the application root). A user will be taken to this URL after logging in, provided they were not asked to login while attempting to access a secured resource, when they will be taken to the originally requested @@ -242,16 +245,16 @@
<literal>always-use-default-target</literal> If set to "true", the user will always start at the value given by - default-target-url, regardless of how they arrived at the + default-target-url, regardless of how they arrived at the login page. Maps to the alwaysUseDefaultTargetUrl property of - UsernamePasswordAuthenticationFilter. Default value is - "false". + UsernamePasswordAuthenticationFilter. Default value + is "false".
<literal>authentication-failure-url</literal> Maps to the authenticationFailureUrl property of - UsernamePasswordAuthenticationFilter. Defines the URL the - browser will be redirected to on login failure. Defaults to + UsernamePasswordAuthenticationFilter. Defines the URL + the browser will be redirected to on login failure. Defaults to "/spring_security_login?login_error", which will be automatically handled by the automatic login page generator, re-rendering the login page with an error message. @@ -263,8 +266,8 @@ the navigation flow after a successful authentication. The value should be the name of an AuthenticationSuccessHandler bean in the application context. By default, an imlementation of - SavedRequestAwareAuthenticationSuccessHandler is used and - injected with the default-target-url. + SavedRequestAwareAuthenticationSuccessHandler is used + and injected with the default-target-url.
<literal>authentication-failure-handler-ref</literal> @@ -278,7 +281,7 @@
The <literal><http-basic></literal> Element Adds a BasicAuthenticationFilter and - BasicAuthenticationEntryPoint to the configuration. The + BasicAuthenticationEntryPoint to the configuration. The latter will only be used as the configuration entry point if form-based login is not enabled.
@@ -286,57 +289,57 @@ The <literal><remember-me></literal> Element Adds the RememberMeAuthenticationFilter to the stack. This in turn will be configured with either a - TokenBasedRememberMeServices, a - PersistentTokenBasedRememberMeServices or a user-specified - bean implementing RememberMeServices depending on the - attribute settings. + TokenBasedRememberMeServices, a + PersistentTokenBasedRememberMeServices or a + user-specified bean implementing RememberMeServices + depending on the attribute settings.
<literal>data-source-ref</literal> If this is set, PersistentTokenBasedRememberMeServices will be used and configured with a - JdbcTokenRepositoryImpl instance. + JdbcTokenRepositoryImpl instance.
<literal>token-repository-ref</literal> Configures a PersistentTokenBasedRememberMeServices but allows the use of a custom - PersistentTokenRepository bean. + PersistentTokenRepository bean.
<literal>services-ref</literal> Allows complete control of the - RememberMeServices implementation that will be - used by the filter. The value should be the Id of a bean in the application + RememberMeServices implementation that will + be used by the filter. The value should be the Id of a bean in the application context which implements this interface.
<literal>token-repository-ref</literal> Configures a PersistentTokenBasedRememberMeServices but allows the use of a custom - PersistentTokenRepository bean. + PersistentTokenRepository bean.
The <literal>key</literal> Attribute Maps to the "key" property of - AbstractRememberMeServices. Should be set to a unique + AbstractRememberMeServices. Should be set to a unique value to ensure that remember-me cookies are only valid within the one application - This doesn't affect the use of - PersistentTokenBasedRememberMeServices, where the - tokens are stored on the server side. + This doesn't affect the use of + PersistentTokenBasedRememberMeServices, where + the tokens are stored on the server side. .
<literal>token-validity-seconds</literal> Maps to the tokenValiditySeconds property of - AbstractRememberMeServices. Specifies the period in + AbstractRememberMeServices. Specifies the period in seconds for which the remember-me cookie should be valid. By default it will be valid for 14 days.
<literal>user-service-ref</literal> The remember-me services implementations require access to a - UserDetailsService, so there has to be one + UserDetailsService, so there has to be one defined in the application context. If there is only one, it will be selected and used automatically by the namespace configuration. If there are multiple instances, you can specify a bean Id explicitly using this attribute. @@ -345,7 +348,7 @@
The <literal><session-management></literal> Element Session-management related functionality is implemented by the addition of a - SessionManagementFilter to the filter stack. + SessionManagementFilter to the filter stack.
<literal>session-fixation-protection</literal> Indicates whether an existing session should be invalidated when a user @@ -354,27 +357,28 @@ a new session and copy the session attributes to the new session. Defaults to "migrateSession". If session fixation protection is enabled, the - SessionManagementFilter is inected with a appropriately - configured DefaultSessionAuthenticationStrategy. See the - Javadoc for this class for more details. + SessionManagementFilter is inected with a + appropriately configured + DefaultSessionAuthenticationStrategy. See the Javadoc + for this class for more details.
The <literal><concurrency-control></literal> Element Adds support for concurrent session control, allowing limits to be placed on the number of active sessions a user can have. A - ConcurrentSessionFilter will be created, and a - ConcurrentSessionControlStrategy will be used with the - SessionManagementFilter. If a form-login - element has been declared, the strategy object will also be injected into the - created authentication filter. An instance of - SessionRegistry (a - SessionRegistryImpl instance unless the user wishes to use a - custom bean) will be created for use by the strategy. + ConcurrentSessionFilter will be created, and a + ConcurrentSessionControlStrategy will be used with the + SessionManagementFilter. If a + form-login element has been declared, the strategy object + will also be injected into the created authentication filter. An instance of + SessionRegistry (a + SessionRegistryImpl instance unless the user wishes to + use a custom bean) will be created for use by the strategy.
The <literal>max-sessions</literal> attribute Maps to the maximumSessions property of - ConcurrentSessionControlStrategy. + ConcurrentSessionControlStrategy.
The <literal>expired-url</literal> attribute @@ -388,13 +392,13 @@
The <literal>error-if-maximum-exceeded</literal> attribute If set to "true" a - SessionAuthenticationException will be raised + SessionAuthenticationException will be raised when a user attempts to exceed the maximum allowed number of sessions. The default behaviour is to expire the original session.
The <literal>session-registry-alias</literal> and - <literal>session-registry-ref</literal> attributes + session-registry-ref attributes The user can supply their own SessionRegistry implementation using the session-registry-ref attribute. The other concurrent session control beans will be wired up to use it. @@ -407,24 +411,24 @@
The <literal><anonymous></literal> Element Adds an AnonymousAuthenticationFilter to the stack and an - AnonymousAuthenticationProvider. Required if you are using - the IS_AUTHENTICATED_ANONYMOUSLY attribute. + AnonymousAuthenticationProvider. Required if you are + using the IS_AUTHENTICATED_ANONYMOUSLY attribute.
The <literal><x509></literal> Element Adds support for X.509 authentication. An - X509AuthenticationFilter will be added to the stack and an - Http403ForbiddenEntryPoint bean will be created. The latter - will only be used if no other authentication mechanisms are in use (it's only + X509AuthenticationFilter will be added to the stack and + an Http403ForbiddenEntryPoint bean will be created. The + latter will only be used if no other authentication mechanisms are in use (it's only functionality is to return an HTTP 403 error code). A - PreAuthenticatedAuthenticationProvider will also be created - which delegates the loading of user authorities to a - UserDetailsService. + PreAuthenticatedAuthenticationProvider will also be + created which delegates the loading of user authorities to a + UserDetailsService.
The <literal>subject-principal-regex</literal> attribute Defines a regular expression which will be used to extract the username from the certificate (for use with the - UserDetailsService). + UserDetailsService).
The <literal>user-service-ref</literal> attribute @@ -439,10 +443,10 @@ Similar to <form-login> and has the same attributes. The default value for login-processing-url is "/j_spring_openid_security_check". An - OpenIDAuthenticationFilter and - OpenIDAuthenticationProvider will be registered. The latter - requires a reference to a UserDetailsService. Again, - this can be specified by Id, using the user-service-ref + OpenIDAuthenticationFilter and + OpenIDAuthenticationProvider will be registered. The + latter requires a reference to a UserDetailsService. + Again, this can be specified by Id, using the user-service-ref attribute, or will be located automatically in the application context.
The <literal><attribute-exchange></literal> Element @@ -471,16 +475,16 @@
The <literal>invalidate-session</literal> attribute Maps to the invalidateHttpSession of the - SecurityContextLogoutHandler. Defaults to "true", so the - session will be invalidated on logout. + SecurityContextLogoutHandler. Defaults to "true", so + the session will be invalidated on logout.
The <literal><custom-filter></literal> Element This element is used to add a filter to the filter chain. It doesn't create any additional beans but is used to select a bean of type - javax.servlet.Filter which is already defined in the - appllication context and add that at a particular position in the filter chain + javax.servlet.Filter which is already defined in + the appllication context and add that at a particular position in the filter chain maintained by Spring Security. Full details can be found in the namespace chapter.
@@ -489,56 +493,56 @@ Authentication Services Before Spring Security 3.0, an AuthenticationManager was automatically registered internally. Now you must register one explicitly using the - <authentication-manager> element. This creates an instance of - Spring Security's ProviderManager class, which needs to be + <authentication-manager> element. This creates an instance + of Spring Security's ProviderManager class, which needs to be configured with a list of one or more - AuthenticationProvider instances. These can either be + AuthenticationProvider instances. These can either be created using syntax elements provided by the namespace, or they can be standard bean definitions, marked for addition to the list using the - authentication-provider element. + authentication-provider element.
The <literal><authentication-manager></literal> Element Every Spring Security application which uses the namespace must have include this element somewhere. It is responsible for registering the - AuthenticationManager which provides authentication - services to the application. It also allows you to define an alias name for the - internal instance for use in your own configuration. Its use is described in the - namespace introduction. All elements - which create AuthenticationProvider instances should - be children of this element. + AuthenticationManager which provides + authentication services to the application. It also allows you to define an alias + name for the internal instance for use in your own configuration. Its use is + described in the namespace introduction. + All elements which create AuthenticationProvider + instances should be children of this element.
The <literal><authentication-provider></literal> Element Unless used with a ref attribute, this element is shorthand for configuring a DaoAuthenticationProvider. - DaoAuthenticationProvider loads user information from a - UserDetailsService and compares the + >DaoAuthenticationProvider. + DaoAuthenticationProvider loads user information from + a UserDetailsService and compares the username/password combination with the values supplied at login. The - UserDetailsService instance can be defined either - by using an available namespace element (jdbc-user-service or - by using the user-service-ref attribute to point to a bean - defined elsewhere in the application context). You can find examples of these - variations in the namespace - introduction. + UserDetailsService instance can be defined + either by using an available namespace element + (jdbc-user-service or by using the + user-service-ref attribute to point to a bean defined + elsewhere in the application context). You can find examples of these variations + in the namespace introduction.
The <literal><password-encoder></literal> Element Authentication providers can optionally be configured to use a password encoder as described in the namespace introduction. This will result in the bean being injected - with the appropriate PasswordEncoder + >namespace introduction. This will result in the bean being + injected with the appropriate PasswordEncoder instance, potentially with an accompanying - SaltSource bean to provide salt values for - hashing. + SaltSource bean to provide salt values + for hashing.
Using <literal><authentication-provider></literal> to refer to an - <interfacename>AuthenticationProvider</interfacename> Bean + AuthenticationProvider Bean If you have written your own - AuthenticationProvider implementation (or want to - configure one of Spring Security's own implementations as a traditional bean for - some reason, then you can use the following syntax to add it to the internal - ProviderManager's list: AuthenticationProvider implementation (or + want to configure one of Spring Security's own implementations as a traditional + bean for some reason, then you can use the following syntax to add it to the + internal ProviderManager's list: @@ -556,18 +560,18 @@ the interface or class level) or by defining a set of pointcuts as child elements, using AspectJ syntax. Method security uses the same - AccessDecisionManager configuration as web security, - but this can be overridden as explained above , using the same attribute. + AccessDecisionManager configuration as web + security, but this can be overridden as explained above , using the same attribute.
The <literal>secured-annotations</literal> and - <literal>jsr250-annotations</literal> Attributes + jsr250-annotations Attributes Setting these to "true" will enable support for Spring Security's own - @Secured annotations and JSR-250 annotations, respectively. - They are both disabled by default. Use of JSR-250 annotations also adds a - Jsr250Voter to the - AccessDecisionManager, so you need to make sure - you do this if you are using a custom implementation and want to use these + @Secured annotations and JSR-250 annotations, + respectively. They are both disabled by default. Use of JSR-250 annotations also + adds a Jsr250Voter to the + AccessDecisionManager, so you need to make + sure you do this if you are using a custom implementation and want to use these annotations.
@@ -577,118 +581,120 @@ cross-cutting security constraints across whole sets of methods and interfaces in your service layer using the <protect-pointcut> element. This has two attributes: - - expression - the pointcut expression - - - access - the security attributes which apply - + + expression - the pointcut expression + + + access - the security attributes which + apply + You can find an example in the namespace introduction. + xlink:href="#ns-protect-pointcut">namespace introduction.
The <literal><after-invocation-provider></literal> Element This element can be used to decorate an - AfterInvocationProvider for use by the security - interceptor maintained by the <global-method-security> - namespace. You can define zero or more of these within the - global-method-security element, each with a - ref attribute pointing to an - AfterInvocationProvider bean instance within your - application context. + AfterInvocationProvider for use by the + security interceptor maintained by the + <global-method-security> namespace. You can define + zero or more of these within the global-method-security + element, each with a ref attribute pointing to an + AfterInvocationProvider bean instance within + your application context.
LDAP Namespace Options LDAP is covered in some details in its own - chapter. We will expand on that here with some explanation of how the + chapter. We will expand on that here with some explanation of how the namespace options map to Spring beans. The LDAP implementation uses Spring LDAP extensively, so some familiarity with that project's API may be useful.
Defining the LDAP Server using the <literal><ldap-server></literal> Element This element sets up a Spring LDAP - ContextSource for use by the other LDAP beans, - defining the location of the LDAP server and other information (such as a + ContextSource for use by the other LDAP + beans, defining the location of the LDAP server and other information (such as a username and password, if it doesn't allow anonymous access) for connecting to it. It can also be used to create an embedded server for testing. Details of the syntax for both options are covered in the LDAP - chapter. The actual ContextSource + chapter. The actual ContextSource implementation is DefaultSpringSecurityContextSource which extends Spring LDAP's LdapContextSource class. The - manager-dn and manager-password attributes - map to the latter's userDn and password - properties respectively. + manager-dn and manager-password + attributes map to the latter's userDn and + password properties respectively. If you only have one server defined in your application context, the other LDAP namespace-defined beans will use it automatically. Otherwise, you can give the element an "id" attribute and refer to it from other namespace beans using the server-ref attribute. This is actually the bean Id of the - ContextSource instance, if you want to use it in other + ContextSource instance, if you want to use it in other traditional Spring beans.
The <literal><ldap-provider></literal> Element This element is shorthand for the creation of an - LdapAuthenticationProvider instance. By default this will - be configured with a BindAuthenticator instance and a - DefaultAuthoritiesPopulator. As with all namespace + LdapAuthenticationProvider instance. By default this + will be configured with a BindAuthenticator instance and + a DefaultAuthoritiesPopulator. As with all namespace authentication providers, it must be included as a child of the - authentication-provider element. + authentication-provider element.
The <literal>user-dn-pattern</literal> Attribute If your users are at a fixed location in the directory (i.e. you can work out the DN directly from the username without doing a directory search), you can use this attribute to map directly to the DN. It maps directly to the - userDnPatterns property of - AbstractLdapAuthenticator. + userDnPatterns property of + AbstractLdapAuthenticator.
The <literal>user-search-base</literal> and - <literal>user-search-filter</literal> Attributes + user-search-filter Attributes If you need to perform a search to locate the user in the directory, then you can set these attributes to control the search. The - BindAuthenticator will be configured with a - FilterBasedLdapUserSearch and the attribute values - map directly to the first two arguments of that bean's constructor. If these - attributes aren't set and no user-dn-pattern has been - supplied as an alternative, then the default search values of - user-search-filter="(uid={0})" and - user-search-base="" will be used. + BindAuthenticator will be configured with a + FilterBasedLdapUserSearch and the attribute + values map directly to the first two arguments of that bean's constructor. + If these attributes aren't set and no user-dn-pattern has + been supplied as an alternative, then the default search values of + user-search-filter="(uid={0})" and + user-search-base="" will be used.
<literal>group-search-filter</literal>, - <literal>group-search-base</literal>, - <literal>group-role-attribute</literal> and <literal>role-prefix</literal> - Attributes + group-search-base, + group-role-attribute and + role-prefix Attributes The value of group-search-base is mapped to the - groupSearchBase constructor argument of - DefaultAuthoritiesPopulator and defaults to + groupSearchBase constructor argument of + DefaultAuthoritiesPopulator and defaults to "ou=groups". The default filter value is "(uniqueMember={0})", which assumes that the entry is of type "groupOfUniqueNames". - group-role-attribute maps to the - groupRoleAttribute attribute and defaults to "cn". + group-role-attribute maps to the + groupRoleAttribute attribute and defaults to "cn". Similarly role-prefix maps to - rolePrefix and defaults to "ROLE_". + rolePrefix and defaults to "ROLE_".
The <literal><password-compare></literal> Element This is used as child element to <ldap-provider> and switches the authentication strategy from - BindAuthenticator to - PasswordComparisonAuthenticator. This can optionally - be supplied with a hash attribute or with a child - <password-encoder> element to hash the password - before submitting it to the directory for comparison. + BindAuthenticator to + PasswordComparisonAuthenticator. This can + optionally be supplied with a hash attribute or with a + child <password-encoder> element to hash the + password before submitting it to the directory for comparison.
The <literal><ldap-user-service></literal> Element This element configures an LDAP - UserDetailsService. The class used is - LdapUserDetailsService which is a combination of a - FilterBasedLdapUserSearch and a - DefaultAuthoritiesPopulator. The attributes it supports - have the same usage as in <ldap-provider>. + UserDetailsService. The class used is + LdapUserDetailsService which is a combination of a + FilterBasedLdapUserSearch and a + DefaultAuthoritiesPopulator. The attributes it + supports have the same usage as in <ldap-provider>. +
diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index 290631f506..43f58081ef 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -9,9 +9,9 @@ Namespace configuration has been available since version 2.0 of the Spring framework. It allows you to supplement the traditional Spring beans application context syntax with elements from additional XML schema. You can find more information in the Spring Reference Documentation. A namespace element can be used simply to allow a more - concise way of configuring an individual bean or, more powerfully, to define an + xlink:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/apc.html" + > Reference Documentation. A namespace element can be used simply to allow a + more concise way of configuring an individual bean or, more powerfully, to define an alternative configuration syntax which more closely matches the problem domain and hides the underlying complexity from the user. A simple element may conceal the fact that multiple beans and processing steps are being added to the application context. For @@ -22,13 +22,13 @@ beans. The most common alternative configuration requirements are supported by attributes on the ldap-server element and the user is isolated from worrying about which beans they need to create and what the bean property names are. - You can find out more about the use of the ldap-server element - in the chapter on LDAP. + You can find out more about the use of the ldap-server + element in the chapter on LDAP. . Use of a good XML editor while editing the application context file should provide information on the attributes and elements that are available. We would recommend that you try out the SpringSource Tool Suite as - it has special features for working with standard Spring namespaces. + xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite + as it has special features for working with standard Spring namespaces. 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: - - Web/HTTP Security - the most complex part. Sets up - the filters and related service beans used to apply the framework - authentication mechanisms, to secure URLs, render login and error pages and - much more. - - - Business Object (Method) Security - options for - securing the service layer. - - - AuthenticationManager - handles authentication - requests from other parts of the framework. - - - AccessDecisionManager - provides access decisions - for web and method security. A default one will be registered, but you can - also choose to use a custom one, declared using normal Spring bean - syntax. - - - AuthenticationProviders - mechanisms against which - the authentication manager authenticates users. The namespace provides - supports for several standard options and also a means of adding custom - beans declared using a traditional syntax. - - - UserDetailsService - closely related to - authentication providers, but often also required by other beans. - - + + + Web/HTTP Security - the most complex part. Sets up + the filters and related service beans used to apply the framework + authentication mechanisms, to secure URLs, render login and error pages + and much more. + + + + Business Object (Method) Security - options for + securing the service layer. + + + + AuthenticationManager - handles authentication + requests from other parts of the framework. + + + + AccessDecisionManager - provides access decisions + for web and method security. A default one will be registered, but you + can also choose to use a custom one, declared using normal Spring bean + syntax. + + + + AuthenticationProviders - mechanisms against which + the authentication manager authenticates users. The namespace provides + supports for several standard options and also a means of adding custom + beans declared using a traditional syntax. + + + + UserDetailsService - closely related to + authentication providers, but often also required by other beans. + + We'll see how to configure these in the following sections.
@@ -109,7 +115,7 @@
<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 org.springframework.web.filter.DelegatingFilterProxy @@ -123,11 +129,12 @@ infrastructure. DelegatingFilterProxy is a Spring Framework class which delegates to a filter implementation which is defined as a Spring bean in your application context. In this case, the bean is named - springSecurityFilterChain, which is an internal infrastructure bean - created by the namespace to handle web security. Note that you should not use this - bean name yourself. Once you've added this to your web.xml, - you're ready to start editing your application context file. Web security services - are configured using the <http> element. + springSecurityFilterChain, which is an internal infrastructure + bean created by the namespace to handle web security. Note that you should not use + this bean name yourself. Once you've added this to your + web.xml, you're ready to start editing your application context + file. Web security services are configured using the <http> + element.
A Minimal <literal><http></literal> Configuration @@ -138,30 +145,32 @@ ]]> Which says that we want all URLs within our application to be secured, requiring the role ROLE_USER to access them. The - <http> element is the parent for all web-related namespace + <http> element is the parent for all web-related namespace functionality. The <intercept-url> element defines a - pattern which is matched against the URLs of incoming requests - using an ant path style syntax. The access attribute defines the - access requirements for requests matching the given pattern. With the default - configuration, this is typically a comma-separated list of roles, one of which a - user must have to be allowed to make the request. The prefix ROLE_ is - a marker which indicates that a simple comparison with the user's authorities should - be made. In other words, a normal role-based check should be used. Access-control in - Spring Security is not limited to the use of simple roles (hence the use of the - prefix to differentiate between different types of security attributes). We'll see - later how the interpretation can vary - The interpretation of the comma-separated values in the - access attribute depends on the implementation of the AccessDecisionManager which is used. In - Spring Security 3.0, the attribute can also be populated with an EL expression. + pattern which is matched against the URLs of incoming + requests using an ant path style syntax. You can also use regular-expression + matching as an alternative (see the namespace appendix for more details). The + access attribute defines the access requirements for requests + matching the given pattern. With the default configuration, this is typically a + comma-separated list of roles, one of which a user must have to be allowed to make + the request. The prefix ROLE_ is a marker which indicates that a + simple comparison with the user's authorities should be made. In other words, a + normal role-based check should be used. Access-control in Spring Security is not + limited to the use of simple roles (hence the use of the prefix to differentiate + between different types of security attributes). We'll see later how the + interpretation can vary + The interpretation of the comma-separated values in the + access attribute depends on the implementation of the + AccessDecisionManager which + is used. In Spring Security 3.0, the attribute can also be populated with an + EL expression. . You can use multiple <intercept-url> elements to define different access requirements for different sets of URLs, but they will be evaluated in the order listed and the first match will be used. So you must put the most specific matches at the top. You can also add a - method attribute to limit the match to a particular HTTP + method attribute to limit the match to a particular HTTP method (GET, POST, PUT etc.). If a request matches multiple patterns, the method-specific match will take precedence regardless of ordering. @@ -180,17 +189,17 @@ If you are familiar with pre-namespace versions of the framework, you can probably already guess roughly what's going on here. The - <http> element is responsible for creating a - FilterChainProxy and the filter beans which it uses. + <http> element is responsible for creating a + FilterChainProxy and the filter beans which it uses. Common problems like incorrect filter ordering are no longer an issue as the filter positions are predefined. The <authentication-provider> element creates a - DaoAuthenticationProvider bean and the - <user-service> element creates an - InMemoryDaoImpl. All - authentication-provider elements must be children of the - <authentication-manager> element, which creates a - ProviderManager and registers the authentication + DaoAuthenticationProvider bean and the + <user-service> element creates an + InMemoryDaoImpl. All + authentication-provider elements must be children of the + <authentication-manager> element, which creates a + ProviderManager and registers the authentication providers with it. You can find more detailed information on the beans that are created in the namespace appendix. It's worth cross-checking this if you want to start understanding what the @@ -200,20 +209,20 @@ The configuration above defines two users, their passwords and their roles within the application (which will be used for access control). It is also possible to load user information from a standard properties file using the - properties attribute on user-service. See the - section on in-memory - authentication for more details on the file format. Using the - <authentication-provider> element means that the user + properties attribute on user-service. See + the section on in-memory + authentication for more details on the file format. Using the + <authentication-provider> element means that the user information will be used by the authentication manager to process authentication requests. You can have multiple <authentication-provider> elements to define different authentication sources and each will be consulted in turn. At this point you should be able to start up your application and you will be required to log in to proceed. Try it out, or try experimenting with the - tutorial sample application that comes with the project. The above - configuration actually adds quite a few services to the application because we have - used the auto-config attribute. For example, form-based login - processing is automatically enabled. + tutorial sample application that comes with the project. The + above configuration actually adds quite a few services to the application because we + have used the auto-config attribute. For example, form-based + login processing is automatically enabled.
What does <literal>auto-config</literal> Include? The auto-config attribute, as we have used it above, is @@ -225,27 +234,27 @@ ]]> These other elements are responsible for setting up form-login, basic authentication and logout handling services respectively - In versions prior to 3.0, this list also included remember-me - functionality. This could cause some confusing errors with some - configurations and was removed in 3.0. In 3.0, the addition of an - AnonymousAuthenticationFilter is part of the default - <http> configuration, so the <anonymous - /> element is added regardless of whether - auto-config is enabled. + In versions prior to 3.0, this list also included remember-me + functionality. This could cause some confusing errors with some + configurations and was removed in 3.0. In 3.0, the addition of an + AnonymousAuthenticationFilter is part of the + default <http> configuration, so the + <anonymous /> element is added regardless of + whether auto-config is enabled. . They each have attributes which can be used to alter their behaviour.
Form and Basic Login Options - You might be wondering where the login form came from when you were prompted - to log in, since we made no mention of any HTML files or JSPs. In fact, since we - didn't explicitly set a URL for the login page, Spring Security generates one - automatically, 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 after loggin in and so on. However, the namespace offers plenty - of support to allow you to customize these options. For example, if you want to - supply your own login page, you could use: You might be wondering where the login form came from when you were prompted to + log in, since we made no mention of any HTML files or JSPs. In fact, since we didn't + explicitly set a URL for the login page, Spring Security generates one + automatically, 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 after loggin in and so on. However, the namespace offers plenty of support + to allow you to customize these options. For example, if you want to supply your own + login page, you could use: @@ -253,19 +262,19 @@ ]]> Note that you can still use auto-config. The - form-login element just overrides the default settings. Also - note that we've added an extra intercept-url element to say - that any requests for the login page should be available to anonymous users - See the chapter on anonymous - authentication and also the AuthenticatedVoter class for - more details on how the value - IS_AUTHENTICATED_ANONYMOUSLY is processed. + form-login element just overrides the default settings. Also + note that we've added an extra intercept-url element to say that + any requests for the login page should be available to anonymous users + See the chapter on anonymous + authentication and also the AuthenticatedVoter class + for more details on how the value + IS_AUTHENTICATED_ANONYMOUSLY is processed. . Otherwise the request would be matched by the pattern - /** and it wouldn't be possible to access the login page - itself! This is a common configuration error and will result in an infinite loop - in the application. Spring Security will emit a warning in the log if your login - page appears to be secured. It is also possible to have all requests matching a + /** and it wouldn't be possible to access the login page + itself! This is a common configuration error and will result in an infinite loop in + the application. Spring Security will emit a warning in the log if your login page + appears to be secured. It is also possible to have all requests matching a particular pattern bypass the security filter chain completely: @@ -276,10 +285,10 @@ ]]> It's important to realise that these requests will be completely oblivious to any further Spring Security web-related configuration or additional - attributes such as requires-channel, so you will not be able - to access information on the current user or call secured methods during the - request. Use access='IS_AUTHENTICATED_ANONYMOUSLY' as an - alternative if you still want the security filter chain to be applied. + attributes such as requires-channel, so you will not be able to + access information on the current user or call secured methods during the request. + Use access='IS_AUTHENTICATED_ANONYMOUSLY' as an alternative if + you still want the security filter chain to be applied. If you want to use basic authentication instead of form login, then change the configuration to @@ -288,18 +297,18 @@ ]]> Basic authentication will then take precedence and will be used to - prompt for a login when a user attempts to access a protected resource. Form - login is still available in this configuration if you wish to use it, for - example through a login form embedded in another web page. + prompt for a login when a user attempts to access a protected resource. Form login + is still available in this configuration if you wish to use it, for example through + a login form embedded in another web page.
Setting a Default Post-Login Destination - If a form login isn't prompted by an attempt to access a protected - resource, the default-target-url option comes into play. - This is the URL the user will be taken to after successfully logging in, and - defaults to "/". You can also configure things so that the 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 + If a form login isn't prompted by an attempt to access a protected resource, + the default-target-url option comes into play. This is the + URL the user will be taken to after successfully logging in, and defaults to + "/". You can also configure things so that the 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: @@ -310,12 +319,11 @@ ]]> For even more control over the destination, you can use the - authentication-success-handler-ref attribute as an - alternative to default-target-url. The referenced bean - should be an instance of - AuthenticationSuccessHandler. You'll find - more on this in the Core - Filters chapter and also in the namespace appendix, as well as + authentication-success-handler-ref attribute as an + alternative to default-target-url. The referenced bean should + be an instance of AuthenticationSuccessHandler. + You'll find more on this in the Core Filters chapter and also in the namespace appendix, as well as information on how to customize the flow when authentication fails.
@@ -326,7 +334,7 @@ user information in something like a database or an LDAP server. LDAP namespace configuration is 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 + UserDetailsService, called "myUserDetailsService" in your application context, then you can authenticate against this using @@ -340,11 +348,12 @@ ]]> Where securityDataSource is the name of a - DataSource bean in the application context, pointing at a + DataSource bean in the application context, pointing at a database 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 data tables. + Alternatively, you could configure a Spring Security + JdbcDaoImpl bean and point at that using the + user-service-ref attribute: @@ -355,18 +364,18 @@ ]]> You can also use standard - AuthenticationProvider beans as follows AuthenticationProvider beans as follows ]]> where myAuthenticationProvider is the name of a bean in your application context which implements - AuthenticationProvider. You can use multiple - authentication-provider elements, in which case the providers + AuthenticationProvider. You can use multiple + authentication-provider elements, in which case the providers will be queried in the order they are declared. See for more on information on how the Spring Security - AuthenticationManager is configured using the + AuthenticationManager is configured using the namespace.
Adding a Password Encoder @@ -397,8 +406,8 @@ ]]> You can use a custom password encoder bean by using the - ref attribute of password-encoder. This - should contain the name of a bean in the application context which is an + ref attribute of password-encoder. + This should contain the name of a bean in the application context which is an instance of Spring Security's PasswordEncoder interface.
@@ -415,8 +424,8 @@ 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>: @@ -454,8 +463,8 @@ 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: web.xml file to keep Spring Security updated about + session lifecycle events: org.springframework.security.web.session.HttpSessionEventPublisher @@ -478,44 +487,45 @@ ]]> The second login will then be rejected. By - rejected, we mean that the user will be sent to the - authentication-failure-url if form-based login is being used. - If the second authentication takes place through another non-interactive + rejected, we mean that the user will be sent to the + authentication-failure-url if form-based login is being + used. If the second authentication takes place through another non-interactive mechanism, such as remember-me, an unauthorized (402) error will be sent to the client. If instead you want to use an error page, you can add the attribute - session-authentication-error-url to the - session-management element. + session-authentication-error-url to the + session-management element. If you are using a customized authentication filter for form-based login, then you have to configure concurrent session control support explicitly. More details can be found in the Session Management - chapter. + chapter.
Session Fixation Attack Protection - Session - fixation attacks are a potential risk where it is possible for a + + Session + fixation attacks are a potential risk where it is possible for a malicious attacker to create a session by accessing a site, then persuade another user to log in with the same session (by sending them a link containing the session identifier as a parameter, for example). Spring Security protects against this automatically by creating a new session when a user logs in. If you don't require this protection, or it conflicts with some other requirement, you can control the behaviour using the - session-fixation-protection attribute on - <session-management>, which has three options - - migrateSession - creates a new session and copies - the existing session attributes to the new session. This is the - default. - - - none - Don't do anything. The original session will - be retained. - - - newSession - Create a new "clean" session, without - copying the existing session data. - + session-fixation-protection attribute on + <session-management>, which has three options + + migrateSession - creates a new session and + copies the existing session attributes to the new session. This is + the default. + + + none - Don't do anything. The original session + will be retained. + + + newSession - Create a new "clean" session, + without copying the existing session data. +
@@ -529,23 +539,24 @@ ]]>You should then register yourself with an OpenID provider (such as myopenid.com), and add the user information to your in-memory - <user-service> : <user-service> : ]]> You should be able to login using the myopenid.com site to authenticate. It is also possible to select a specific - UserDetailsService bean for use OpenID by setting the - user-service-ref attribute on the openid-login - element. See the previous section on authentication providers for more information. Note that we have omitted the - password attribute from the above user configuration, since this set of user data is - only being used to load the authorities for the user. A random password will be - generate internally, preventing you from accidentally using this user data as an - authentication source elsewhere in your configuration. + UserDetailsService bean for use OpenID by setting + the user-service-ref attribute on the + openid-login element. See the previous section on authentication providers for more + information. Note that we have omitted the password attribute from the above user + configuration, since this set of user data is only being used to load the + authorities for the user. A random password will be generate internally, preventing + you from accidentally using this user data as an authentication source elsewhere in + your configuration.
Attribute Exchange Support for OpenID attribute exchange. As an example, the following configuration would + xlink:href="http://openid.net/specs/openid-attribute-exchange-1_0.html" + >attribute exchange. As an example, the following configuration would attempt to retrieve the email and full name from the OpenID provider, for use by the application: @@ -555,26 +566,27 @@ ]]>The type of each OpenID attribute is a URI, determined by a particular schema, in this case http://axschema.org/. If an attribute - must be retrieved for successful authentication, the required - attribute can be set. The exact schema and attributes supported will depend on - your OpenID provider. The attribute values are returned as part of the - authentication process and can be accessed afterwards using the following code: + xlink:href="http://axschema.org/">http://axschema.org/. If an + attribute must be retrieved for successful authentication, the + required attribute can be set. The exact schema and + attributes supported will depend on your OpenID provider. The attribute values + are returned as part of the authentication process and can be accessed + afterwards using the following code: OpenIDAuthenticationToken token = (OpenIDAuthenticationToken)SecurityContextHolder.getContext().getAuthentication(); List<OpenIDAttribute> attributes = token.getAttributes();The - OpenIDAttribute contains the attribute type and the + OpenIDAttribute contains the attribute type and the retrieved value (or values in the case of multi-valued attributes). We'll see more about how the SecurityContextHolder class is used when we look at core Spring Security components in the technical overview chapter. Multiple + xlink:href="core-components">technical overview chapter. Multiple attribute exchange configurations are also be supported, if you wish to use multiple identity providers. You can supply multiple - attribute-exchange elements, using an - identifier-matcher attribute on each. This contains a regular - expression which will be matched against the OpenID identifier supplied by the - user. See the OpenID sample application in the codebase for an example + attribute-exchange elements, using an + identifier-matcher attribute on each. This contains a + regular expression which will be matched against the OpenID identifier supplied + by the user. See the OpenID sample application in the codebase for an example configuration, providing different attribute lists for the Google, Yahoo and MyOpenID providers.
@@ -587,122 +599,123 @@ List<OpenIDAttribute> attributes = token.getAttributes();The which there isn't currently a namespace configuration option (CAS, for example). Or you might want to use a customized version of a standard namespace filter, such as the UsernamePasswordAuthenticationFilter which is created by the - <form-login> element, taking advantage of some of the extra - configuration options which are available by using the bean explicitly. How can you - do this with namespace configuration, since the filter chain is not directly + <form-login> element, taking advantage of some of the + extra configuration options which are available by using the bean explicitly. How + can you do this with namespace configuration, since the filter chain is not directly exposed? The order of the filters is always strictly enforced when using the namespace. When the application context is being created, the filter beans are sorted by the namespace handling code and the standard Spring Security filters each have an alias in the namespace and a well-known position. - In previous versions, the sorting took place after the filter instances had - been created, during post-processing of the application context. In version 3.0+ - the sorting is now done at the bean metadata level, before the classes have been - instantiated. This has implications for how you add your own filters to the - stack as the entire filter list must be known during the parsing of the - <http> element, so the syntax has changed slightly in - 3.0. + In previous versions, the sorting took place after the filter instances + had been created, during post-processing of the application context. In + version 3.0+ the sorting is now done at the bean metadata level, before the + classes have been instantiated. This has implications for how you add your + own filters to the stack as the entire filter list must be known during the + parsing of the <http> element, so the syntax has + changed slightly in 3.0. The filters, aliases and namespace elements/attributes which create the filters are shown in . The filters are listed in the order in which they occur in the filter chain. - Standard Filter Aliases and Ordering - - - - - - - Alias - Filter Class - Namespace Element or Attribute - - - - - CHANNEL_FILTER - ChannelProcessingFilter - http/intercept-url@requires-channel - - - CONCURRENT_SESSION_FILTER - ConcurrentSessionFilter - session-management/concurrency-control - - - SECURITY_CONTEXT_FILTER - SecurityContextPersistenceFilter - http - - - LOGOUT_FILTER - LogoutFilter - http/logout - - - X509_FILTER - X509AuthenticationFilter - http/x509 - - - PRE_AUTH_FILTER - AstractPreAuthenticatedProcessingFilter - Subclasses - N/A - - - CAS_FILTER - CasAuthenticationFilter - N/A - - - FORM_LOGIN_FILTER - UsernamePasswordAuthenticationFilter - http/form-login - - - BASIC_AUTH_FILTER - BasicAuthenticationFilter - http/http-basic - - - SERVLET_API_SUPPORT_FILTER - SecurityContextHolderAwareFilter - http/@servlet-api-provision - - - REMEMBER_ME_FILTER - RememberMeAuthenticationFilter - http/remember-me - - - ANONYMOUS_FILTER - AnonymousAuthenticationFilter - http/anonymous - - - SESSION_MANAGEMENT_FILTER - SessionManagementFilter - session-management - - - EXCEPTION_TRANSLATION_FILTER - ExceptionTranslationFilter - http - - - FILTER_SECURITY_INTERCEPTOR - FilterSecurityInterceptor - http - - - SWITCH_USER_FILTER - SwitchUserFilter - N/A - - - + Standard Filter Aliases and Ordering + + + + + + + Alias + Filter Class + Namespace Element or Attribute + + + + + CHANNEL_FILTER + ChannelProcessingFilter + http/intercept-url@requires-channel + + + CONCURRENT_SESSION_FILTER + ConcurrentSessionFilter + + session-management/concurrency-control + + + SECURITY_CONTEXT_FILTER + SecurityContextPersistenceFilter + http + + + LOGOUT_FILTER + LogoutFilter + http/logout + + + X509_FILTER + X509AuthenticationFilter + http/x509 + + + PRE_AUTH_FILTER + AstractPreAuthenticatedProcessingFilter + Subclasses + N/A + + + CAS_FILTER + CasAuthenticationFilter + N/A + + + FORM_LOGIN_FILTER + UsernamePasswordAuthenticationFilter + http/form-login + + + BASIC_AUTH_FILTER + BasicAuthenticationFilter + http/http-basic + + + SERVLET_API_SUPPORT_FILTER + SecurityContextHolderAwareFilter + http/@servlet-api-provision + + + REMEMBER_ME_FILTER + RememberMeAuthenticationFilter + http/remember-me + + + ANONYMOUS_FILTER + AnonymousAuthenticationFilter + http/anonymous + + + SESSION_MANAGEMENT_FILTER + SessionManagementFilter + session-management + + + EXCEPTION_TRANSLATION_FILTER + ExceptionTranslationFilter + http + + + FILTER_SECURITY_INTERCEPTOR + FilterSecurityInterceptor + http + + + SWITCH_USER_FILTER + SwitchUserFilter + N/A + + +
You can add your own filter to the stack, using the - custom-filter element and one of these names to specify the + custom-filter element and one of these names to specify the position your filter should appear at: @@ -713,20 +726,20 @@ List<OpenIDAttribute> attributes = token.getAttributes();The You can also use the after or before attributes if you want your filter to be inserted before or after another filter in the stack. The names "FIRST" and "LAST" can be used with the - position attribute to indicate that you want your filter to + position attribute to indicate that you want your filter to appear before or after the entire stack, respectively. Avoiding filter position conflicts If you are inserting a custom filter which may occupy the same position as one of the standard filters created by the namespace then it's important that you don't include the namespace versions by mistake. Avoid using the - auto-config attribute and remove any elements which create - filters whose functionality you want to replace. + auto-config attribute and remove any elements which + create filters whose functionality you want to replace. Note that you can't replace filters which are created by the use of the - <http> element itself - - SecurityContextPersistenceFilter, - ExceptionTranslationFilter or - FilterSecurityInterceptor. + <http> element itself - + SecurityContextPersistenceFilter, + ExceptionTranslationFilter or + FilterSecurityInterceptor. If you're replacing a namespace filter which requires an authentication entry point (i.e. where the authentication process is triggered by an attempt by an @@ -740,11 +753,11 @@ List<OpenIDAttribute> attributes = token.getAttributes();The a traditional bean syntax and link them into the namespace, as we've just seen. The corresponding AuthenticationEntryPoint can be set using the entry-point-ref attribute on the - <http> element. + <http> element. The CAS sample application is a good example of the use of custom beans with the namespace, including this syntax. If you aren't familiar with authentication entry points, they are discussed in the technical overview chapter. + xlink:href="#tech-intro-auth-entry-point">technical overview chapter.
@@ -755,9 +768,9 @@ List<OpenIDAttribute> attributes = token.getAttributes();The security to your service layer methods. It provides support for JSR-250 annotation security as well as the framework's original @Secured annotation. From 3.0 you can also make use of new expression-based - annotations. You can apply security to a single bean, using the - intercept-methods element to decorate the bean declaration, or you - can secure multiple beans across the entire service layer using the AspectJ style + annotations. You can apply security to a single bean, using the + intercept-methods element to decorate the bean declaration, or + you can secure multiple beans across the entire service layer using the AspectJ style pointcuts.
The <literal><global-method-security></literal> Element @@ -765,14 +778,14 @@ List<OpenIDAttribute> attributes = token.getAttributes();The setting the appropriate attributes on the element), and also to group together security pointcut declarations which will be applied across your entire application context. You should only declare one - <global-method-security> element. The following declaration - would enable support for Spring Security's @Secured: <global-method-security> element. The following + declaration would enable support for Spring Security's @Secured: ]]> Adding an annotation to a method (on an class or interface) would then limit the access to that method accordingly. Spring Security's native annotation support defines a set of attributes for the method. These will be passed to the - AccessDecisionManager for it to make the actual + AccessDecisionManager for it to make the actual decision: public interface BankService { @@ -825,8 +838,8 @@ List<OpenIDAttribute> attributes = token.getAttributes();The This will protect all methods on beans declared in the application context whose classes are in the com.mycompany package and whose class names end in "Service". Only users with the - ROLE_USER role will be able to invoke these methods. As with - URL matching, the most specific matches must come first in the list of + ROLE_USER role will be able to invoke these methods. As + with URL matching, the most specific matches must come first in the list of pointcuts, as the first matching expression will be used.
@@ -838,24 +851,24 @@ List<OpenIDAttribute> attributes = token.getAttributes();The later, as this section is only really relevant for people who need to do some customization in order to use more than simple role-based security. When you use a namespace configuration, a default instance of - AccessDecisionManager is automatically registered for you - and will be used for making access decisions for method invocations and web URL access, - based on the access attributes you specify in your intercept-url and - protect-pointcut declarations (and in annotations if you are using - annotation secured methods). + AccessDecisionManager is automatically registered for + you and will be used for making access decisions for method invocations and web URL + access, based on the access attributes you specify in your + intercept-url and protect-pointcut + declarations (and in annotations if you are using annotation secured methods). The default strategy is to use an AffirmativeBased AccessDecisionManager with a - RoleVoter and an AuthenticatedVoter. You - can find out more about these in the chapter on authorization. + RoleVoter and an AuthenticatedVoter. + You can find out more about these in the chapter on authorization.
Customizing the AccessDecisionManager If you need to use a more complicated access control strategy then it is easy to set an alternative for both method and web security. For method security, you do this by setting the - access-decision-manager-ref attribute on - global-method-security to the Id of the appropriate - AccessDecisionManager bean in the application + access-decision-manager-ref attribute on + global-method-security to the Id of the appropriate + AccessDecisionManager bean in the application context: ... @@ -872,7 +885,7 @@ List<OpenIDAttribute> attributes = token.getAttributes();The
The Authentication Manager and the Namespace The main interface which provides authentication services in Spring Security is the - AuthenticationManager. This is usually an instance of + AuthenticationManager. This is usually an instance of Spring Security's ProviderManager class, which you may already be familiar with if you've used the framework before. If not, it will be covered later, in the technical overview chapter. The @@ -880,12 +893,12 @@ List<OpenIDAttribute> attributes = token.getAttributes();The namespace element. You can't use a custom AuthenticationManager if you are using either HTTP or method security through the namespace, but this should not be a problem as you have full control over the - AuthenticationProviders that are used. + AuthenticationProviders that are used. You may want to register additional AuthenticationProvider beans with the ProviderManager and you can do this using the - <authentication-provider> element with the - ref attribute, where the value of the attribute is the name of the - provider bean you want to add. For example: <authentication-provider> element with the + ref attribute, where the value of the attribute is the name of + the provider bean you want to add. For example: diff --git a/web/src/main/java/org/springframework/security/web/util/AntPathRequestMatcher.java b/web/src/main/java/org/springframework/security/web/util/AntPathRequestMatcher.java index 0c197e2392..b88d41beae 100644 --- a/web/src/main/java/org/springframework/security/web/util/AntPathRequestMatcher.java +++ b/web/src/main/java/org/springframework/security/web/util/AntPathRequestMatcher.java @@ -10,9 +10,9 @@ import org.springframework.util.Assert; import org.springframework.util.StringUtils; /** - * Matcher which compares a pre-defined ant-style pattern against the URL of an - * {@code HttpServletRequest}. Ignores the query string of the URL and always performs - * case-insensitive matching. + * Matcher which compares a pre-defined ant-style pattern against the URL + * ({@code servletPath + pathInfo}) of an {@code HttpServletRequest}. + * The query string of the URL is ignored and matching is case-insensitive. * * @author Luke Taylor * @since 3.1 @@ -52,7 +52,8 @@ public final class AntPathRequestMatcher implements RequestMatcher { /** * Returns true if the configured pattern (and HTTP-Method) match those of the supplied request. * - * @param request the request to match against. + * @param request the request to match against. The ant pattern will be matched against the + * {@code servletPath} + {@code pathInfo} of the request. */ public boolean matches(HttpServletRequest request) { if (httpMethod != null && httpMethod != HttpMethod.valueOf(request.getMethod())) {