diff --git a/docs/manual/src/docbook/appendix-namespace.xml b/docs/manual/src/docbook/appendix-namespace.xml
index 4f9ccfa4d7..fac62e1fe9 100644
--- a/docs/manual/src/docbook/appendix-namespace.xml
+++ b/docs/manual/src/docbook/appendix-namespace.xml
@@ -1,657 +1,584 @@
-
+ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
The Security Namespace
-
-
- This appendix provides a reference to the elements available in the security namespace 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 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.
-
-
+ This appendix provides a reference to the elements available in the security namespace 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 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. 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 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. 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 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).
-
-
- The <http> namespace block always creates an HttpSessionContextIntegrationFilter,
- an ExceptionTranslationFilter and a FilterSecurityInterceptor. These are fixed
- and cannot be replaced with alternatives.
-
-
+ The <http> element encapsulates the security configuration for
+ the web layer of your application. It creates a 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
+ . 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 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).
+ The <http> namespace block always creates an
+ 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 properties on the
- core filters.
-
+ The attributes on the <http> element control some of the
+ properties on the core filters. <literal>servlet-api-provision</literal>
-
- Provides versions of HttpServletRequest security methods such as
- isUserInRole() and getPrincipal() which are implemented by
- adding a SecurityContextHolderAwareRequestFilter bean to the stack. Defaults to "true".
-
+ Provides versions of HttpServletRequest security methods such as
+ isUserInRole() and getPrincipal() which are
+ implemented by adding a SecurityContextHolderAwareRequestFilter
+ bean to the stack. Defaults to "true".
-
<literal>path-type</literal>
-
- Controls whether URL patterns are interpreted as ant paths (the default) or regular expressions. In practice
- this sets a particular UrlMatcher instance on the FilterChainProxy.
-
+ Controls whether URL patterns are interpreted as ant paths (the default) or regular
+ expressions. In practice this sets a particular UrlMatcher
+ instance on the FilterChainProxy.
-
<literal>lowercase-comparisons</literal>
-
- Whether test URLs should be converted to lower case prior to comparing with defined path patterns. If unspecified,
- defaults to "true"
-
+ Whether test URLs should be converted to lower case prior to comparing with defined
+ path patterns. If unspecified, defaults to "true"
-
<literal>session-fixation-protection</literal>
-
- Indicates whether an existing session should be invalidated when a user authenticates and a new session started.
- If set to "none" no change will be made. "newSession" will create a new empty session.
- "migrateSession" will create a new session and copy the session attributes to the new session. Defaults to "migrateSession".
-
-
- If enabled this will add a SessionFixationProtectionFilter to the stack. The session fixation protection
- options on namespace-created instances of AbstractAuthenticationProcessingFilter will also be set appropriately.
-
+ Indicates whether an existing session should be invalidated when a user authenticates
+ and a new session started. If set to "none" no change will be made. "newSession" will
+ create a new empty session. "migrateSession" will create a new session and copy the
+ session attributes to the new session. Defaults to "migrateSession".
+ If enabled this will add a SessionFixationProtectionFilter to
+ the stack. The session fixation protection options on namespace-created instances of
+ AbstractAuthenticationProcessingFilter will also be set
+ appropriately.
-
<literal>realm</literal>
-
- Sets the realm name used for basic authentication (if enabled). Corresponds to the realmName proerty on
- BasicProcessingFilterEntryPoint.
-
+ Sets the realm name used for basic authentication (if enabled). Corresponds to the
+ realmName proerty on
+ BasicProcessingFilterEntryPoint.
-
<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.
-
+ 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.
-
<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.
-
+ 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.
-
<literal>access-denied-page</literal>
-
- Deprecated in favour of the access-denied-handler child element.
+ Deprecated in favour of the access-denied-handler child element.
-
<literal>once-per-request</literal>
-
- Corresponds to the observeOncePerRequest property of
- FilterSecurityInterceptor. Defaults to "true".
-
+ Corresponds to the observeOncePerRequest property of
+ 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 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.
-
+ 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 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.
-
<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. See for more information on the implementation details.
-
+ 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. See for more
+ information on the implementation details.
-
The <literal><intercept-url></literal> Element
-
- This element is used to define the set of URL patterns that the application is interested in
- and to configure how they should be handled. It is used to construct the
- FilterInvocationDefinitionSource 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 ChannelProcessingFilter if particular URLs need to be accessed
- by HTTPS, for example.
-
-
+ This element is used to define the set of URL patterns that the application is
+ interested in and to configure how they should be handled. It is used to construct the
+ FilterInvocationDefinitionSource 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 ChannelProcessingFilter if
+ particular URLs need to be accessed by HTTPS, for example. <literal>pattern</literal>
-
- The pattern which defines the URL path. The content will depend on the path-type attribute from the
- containing http element, so will default to ant path syntax.
-
+ The pattern which defines the URL path. The content will depend on the
+ path-type attribute from the containing http element, so will default
+ to ant path syntax. <literal>method</literal>
-
- The HTTP Method which will be used in combination with the pattern to match an incoming request. If omitted, any method will match.
-
+ The HTTP Method which will be used in combination with the pattern to match an
+ incoming request. If omitted, any method will match. <literal>access</literal>
-
- Lists the access attributes which will be stored in the FilterInvocationDefinitionSource for the defined
- URL pattern/method combination. This should be a comma-separated list of the attributes (such as role names).
-
+ Lists the access attributes which will be stored in the
+ FilterInvocationDefinitionSource for the defined URL
+ pattern/method combination. This should be a comma-separated list of the attributes (such
+ as role names). <literal>requires-channel</literal>
-
- Can be "http" or "https" depending on whether a 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 ChannelProcessingFilter will be added to the filter stack and its additional dependencies added
- to the application context. See the chapter on channel security for an
- example configuration using traditional beans.
-
-
- If a <port-mappings> configuration is added, this will be used to by the SecureChannelProcessor
- and InsecureChannelProcessor beans to determine the ports used for redirecting to HTTP/HTTPS.
-
-
+ Can be "http" or "https" depending on whether a 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
+ ChannelProcessingFilter will be added to the filter stack and its
+ additional dependencies added to the application context. See the chapter on channel security for an example
+ configuration using traditional beans.
+ If a <port-mappings> configuration is added, this will be
+ used to by the SecureChannelProcessor and
+ InsecureChannelProcessor beans to determine the ports used for
+ redirecting to HTTP/HTTPS.
+
-
The <literal><port-mappings></literal> Element
-
- By default, an instance of PortMapperImpl will be added to the configuration for use in redirecting
- to secure and insecure URLs. This element can optionally be used to override the default mappings which that class defines. 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.
-
+ By default, an instance of PortMapperImpl will be added to the
+ configuration for use in redirecting to secure and insecure URLs. This element can
+ optionally be used to override the default mappings which that class defines. 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.
-
The <literal><form-login></literal> Element
-
- Used to add an UsernamePasswordAuthenticationProcessingFilter to the filter stack and an
- LoginUrlAuthenticationEntryPoint to the 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.
- The behaviour can be customized using the following attributes.
-
-
+ Used to add an UsernamePasswordAuthenticationProcessingFilter to
+ the filter stack and an LoginUrlAuthenticationEntryPoint to the
+ 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.
+ 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
- "/spring-security-login".
-
+ The URL that should be used to render the login page. Maps to the
+ loginFormUrl property of the
+ LoginUrlAuthenticationEntryPoint. Defaults to
+ "/spring-security-login".
-
<literal>login-processing-url</literal>
-
- Maps to the filterProcessesUrl property of UsernamePasswordAuthenticationProcessingFilter.
- The default value is "/j_spring_security_check".
-
+ Maps to the filterProcessesUrl property of
+ UsernamePasswordAuthenticationProcessingFilter. The default value
+ is "/j_spring_security_check".
-
<literal>default-target-url</literal>
- Maps to the defaultTargetUrl property of UsernamePasswordAuthenticationProcessingFilter. 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 URL.
-
+ Maps to the defaultTargetUrl property of
+ UsernamePasswordAuthenticationProcessingFilter. 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 URL.
-
<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 login page. Maps to the alwaysUseDefaultTargetUrl property of
- UsernamePasswordAuthenticationProcessingFilter. Default value is "false".
-
+ If set to "true", the user will always start at the value given by
+ default-target-url, regardless of how they arrived at the login page.
+ Maps to the alwaysUseDefaultTargetUrl property of
+ UsernamePasswordAuthenticationProcessingFilter. Default value is
+ "false".
-
<literal>authentication-failure-url</literal>
-
- Maps to the authenticationFailureUrl property of UsernamePasswordAuthenticationProcessingFilter.
- 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.
-
+ Maps to the authenticationFailureUrl property of
+ UsernamePasswordAuthenticationProcessingFilter. 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.
-
The <literal><http-basic></literal> Element
-
- Adds a BasicProcessingFilter and BasicProcessingFilterEntryPoint to the
- configuration. The latter will only be used as the configuration entry point if form-based login is not enabled.
+ Adds a BasicProcessingFilter and
+ BasicProcessingFilterEntryPoint to the configuration. The latter
+ will only be used as the configuration entry point if form-based login is not enabled.
-
The <literal><remember-me></literal> Element
-
- Adds the RememberMeProcessingFilter 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.
-
+ Adds the RememberMeProcessingFilter 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. <literal>data-source-ref</literal>
-
- If this is set, PersistentTokenBasedRememberMeServices will be used and configured with
- a JdbcTokenRepositoryImpl instance.
+ If this is set, PersistentTokenBasedRememberMeServices will be
+ used and configured with a JdbcTokenRepositoryImpl instance.
-
<literal>token-repository-ref</literal>
-
- Configures a PersistentTokenBasedRememberMeServices but allows the use of a custom
- PersistentTokenRepository bean.
-
-
-
+ Configures a PersistentTokenBasedRememberMeServices but allows
+ the use of a custom 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 context which implements this interface.
-
-
-
+ 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 context which implements this interface.
+
<literal>token-repository-ref</literal>
-
- Configures a PersistentTokenBasedRememberMeServices but allows the use of a custom
- PersistentTokenRepository bean.
-
-
-
+ Configures a PersistentTokenBasedRememberMeServices but allows
+ the use of a custom PersistentTokenRepository bean.
+
The <literal>key</literal> Attribute
- Maps to the "key" property of 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..
-
+ Maps to the "key" property of 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.
+ .
-
<literal>token-validity-seconds</literal>
-
- Maps to the tokenValiditySeconds property of AbstractRememberMeServices. Specifies the period
- in seconds for which the remember-me cookie should be valid. By default it will be valid for 14 days.
+ Maps to the tokenValiditySeconds property of
+ 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 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.
-
+ The remember-me services implementations require access to a
+ 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.
-
The <literal><concurrent-session-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, along with a ConcurrentSessionControllerImpl
- and an instance of SessionRegistry (a SessionRegistryImpl instance unless the user
- wishes to use a custom bean). The controller is registered with the namespace's AuthenticationManager
- (ProviderManager). Other namespace-created beans which require a reference to the SessionRegistry
- will automatically have it injected.
-
-
- Note that the forceEagerSessionCreation of HttpSessionContextIntegrationFilter will
- be set to true if concurrent session control is in use.
-
-
+ 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, along with a ConcurrentSessionControllerImpl and an instance
+ of SessionRegistry (a
+ SessionRegistryImpl instance unless the user wishes to use a custom
+ bean). The controller is registered with the namespace's
+ AuthenticationManager
+ (ProviderManager). Other namespace-created beans which require a
+ reference to the SessionRegistry will automatically have it
+ injected.
+ Note that the forceEagerSessionCreation of
+ HttpSessionContextIntegrationFilter will be set to
+ true if concurrent session control is in use. The <literal>max-sessions</literal> attribute
- Maps to the maximumSessions property of ConcurrentSessionControllerImpl.
+ Maps to the maximumSessions property of
+ ConcurrentSessionControllerImpl.
-
The <literal>expired-url</literal> attribute
-
- The URL a user will be redirected to if they attempt to use a session which has been "expired" by
- the concurrent session controller because the user has exceeded the number of allowed sessions and has logged
- in again elsewhere. Should be set unless exception-if-maximum-exceeded is set.
- If no value is supplied, an expiry message will just be written directly back to the response.
-
+ The URL a user will be redirected to if they attempt to use a session which has been
+ "expired" by the concurrent session controller because the user has exceeded the number of
+ allowed sessions and has logged in again elsewhere. Should be set unless
+ exception-if-maximum-exceeded is set. If no value is supplied, an
+ expiry message will just be written directly back to the response.
-
The <literal>exception-if-maximum-exceeded</literal> attribute
- If set to "true" a ConcurrentLoginException should be raised when a user
- attempts to exceed the maximum allowed number of sessions. The default behaviour is to expire the original session.
-
+ If set to "true" a ConcurrentLoginException should 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
-
- 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.
-
-
- It can also be useful to have a reference to the internal session registry for use in your own
- beans or an admin interface. You can expose the interal bean using the session-registry-alias
- attribute, giving it a name that you can use elsewhere in your configuration.
-
+ The <literal>session-registry-alias</literal> and
+ <literal>session-registry-ref</literal> 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.
+ It can also be useful to have a reference to the internal session registry for use in
+ your own beans or an admin interface. You can expose the interal bean using the
+ session-registry-alias attribute, giving it a name that you can use
+ elsewhere in your configuration.
-
-
The <literal><anonymous></literal> Element
-
- Adds an AnonymousProcessingFilter to the stack and an AnonymousAuthenticationProvider.
- Required if you are using the IS_AUTHENTICATED_ANONYMOUSLY attribute.
-
+ Adds an AnonymousProcessingFilter to the stack and an
+ AnonymousAuthenticationProvider. Required if you are using the
+ IS_AUTHENTICATED_ANONYMOUSLY attribute.
-
The <literal><x509></literal> Element
-
- Adds support for X.509 authentication. An X509PreAuthenticatedProcessingFilter will be
- added to the stack and a PreAuthenticatedProcessingFilterEntryPoint 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.
-
+ Adds support for X.509 authentication. An
+ X509PreAuthenticatedProcessingFilter will be added to the stack and
+ a PreAuthenticatedProcessingFilterEntryPoint 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. 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).
-
+ Defines a regular expression which will be used to extract the username from the
+ certificate (for use with the UserDetailsService). The <literal>user-service-ref</literal> attribute
-
- Allows a specific UserDetailsService to be used with X.509 in the case where
- multiple instances are configured. If not set, an attempt will be made to locate a suitable instance automatically and
- use that.
-
+ Allows a specific UserDetailsService to be used with
+ X.509 in the case where multiple instances are configured. If not set, an attempt will be
+ made to locate a suitable instance automatically and use that.
-
The <literal><openid-login></literal> Element
-
- Similar to <form-login> and has the same attributes. The default value for login-processing-url
- is "/j_spring_openid_security_check". An OpenIDUsernamePasswordAuthenticationProcessingFilter 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.
-
+ Similar to <form-login> and has the same attributes. The
+ default value for login-processing-url is
+ "/j_spring_openid_security_check". An
+ OpenIDUsernamePasswordAuthenticationProcessingFilter 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><logout></literal> Element
-
- Adds a LogoutFilter to the filter stack. This is configured
- with a SecurityContextLogoutHandler.
-
+ Adds a LogoutFilter to the filter stack. This is configured with
+ a SecurityContextLogoutHandler. The <literal>logout-url</literal> attribute
-
- The URL which will cause a logout (i.e. which will be processed by the filter). Defaults to "/j_spring_security_logout".
-
+ The URL which will cause a logout (i.e. which will be processed by the filter).
+ Defaults to "/j_spring_security_logout". The <literal>logout-success-url</literal> attribute
-
- The destination URL which the user will be taken to after logging out. Defaults to "/".
-
+ The destination URL which the user will be taken to after logging out. Defaults to
+ "/". The <literal>invalidate-session</literal> attribute
-
- Maps to the invalidateHttpSession of the SecurityContextLogoutHandler.
- Defaults to "true", so the session will be invalidated on logout.
-
+ Maps to the invalidateHttpSession of the
+ SecurityContextLogoutHandler. Defaults to "true", so the session
+ will be invalidated on logout.
-
Authentication Services
-
- If you are using the namespace, an AuthenticationManager is
- automatically registered and will be used by all the namespace-created beans which need to reference it.
- The bean is an instance of Spring Security's ProviderManager class, which needs to be
- configured with a list of one or more AuthenticationProvider instances.
+ 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 configured
+ with a list of one or more 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
- custom-authentication-provider element.
-
-
-
- The <authentication-provider> Element
-
- This element is basically a shorthand syntax for configuring a 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.
-
-
-
- Using <literal><custom-authentication-provider></literal> to register an AuthenticationProvider
-
- 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:
-
-
-
- ]]>
-
-
-
+ standard bean definitions, marked for addition to the list using the
+ authentication-provider element. The <literal><authentication-manager></literal> Element
-
- Since the AuthenticationManager will be automatically registered in the application
- context, this element is entirely optional. It allows you to define an alias name for the internal instance for use
- in your own configuration and also to supply a link to a ConcurrentSessionController
- if you are configuring concurrent session control yourself rather than through the namespace (a rare requirement).
- Its use is described in the namespace introduction.
-
+ Every Spring Security application which uses the namespace must have include this
+ element somewhere. It is resposible 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.
+
+ The <authentication-provider> Element
+ This element is basically a shorthand syntax for configuring a 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.
+
+
+ Using <literal><authentication-provider></literal> to refer to an
+ <interfacename>AuthenticationProvider</interfacename> 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:
+
+
+
+ ]]>
+
-
-
Method Security
-
The <literal><global-method-security></literal> Element
-
- This element is the primary means of adding support for securing methods on Spring Security beans. Methods can
- be secured by the use of annotations (defined at 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.
-
+ This element is the primary means of adding support for securing methods on Spring
+ Security beans. Methods can be secured by the use of annotations (defined at 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.
- The <literal><secured-annotations></literal> and <literal><jsr250-annotations></literal> 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 annotations.
-
+ The <literal><secured-annotations></literal> and
+ <literal><jsr250-annotations></literal> 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 annotations. Securing Methods using <literal><protect-pointcut></literal>
-
- Rather than defining security attributes on an individual method or class basis using the
- @Secured annotation, you can define 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
-
- You can find an example in the namespace introduction.
-
+ Rather than defining security attributes on an individual method or class basis using
+ the @Secured annotation, you can define 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
+
+ You can find an example in the namespace introduction.
- The <literal><custom-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.
-
-
- The syntax is the same as for <custom-authentication-provider>.
-
+ 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. 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 namespace options map to Spring beans. The LDAP implementation uses
- Spring LDAP extensively, so some familiarity with that project's API may be useful.
-
+ LDAP is covered in some details in its own 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 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 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.
-
-
- 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 traditional Spring beans.
-
+ 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 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 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.
+ 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 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.
-
+ 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 authentication
+ providers, it must be included as a child of the
+ 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.
-
-
-
-
- The <literal>user-search-base</literal> and <literal>user-search-filter</literal> 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.
-
+ 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.
- <literal>group-search-filter</literal>, <literal>group-search-base</literal>, <literal>group-role-attribute</literal> and <literal>role-prefix</literal> Attributes
-
- The value of group-search-base is mapped to the 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". Similarly role-prefix
- maps to rolePrefix and defaults to "ROLE_".
-
+ The <literal>user-search-base</literal> and <literal>user-search-filter</literal>
+ 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.
+
+
+ <literal>group-search-filter</literal>, <literal>group-search-base</literal>,
+ <literal>group-role-attribute</literal> and <literal>role-prefix</literal>
+ Attributes
+ The value of group-search-base is mapped to the
+ 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". Similarly
+ role-prefix maps to 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.
-
+ 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. 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>.
-
+ 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>.
-
diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml
index f2213ddc7c..31a4491e94 100644
--- a/docs/manual/src/docbook/namespace-config.xml
+++ b/docs/manual/src/docbook/namespace-config.xml
@@ -293,23 +293,32 @@
]]>
You can also use standard
- AuthenticationProvider beans by adding the
- <custom-authentication-provider> element within the bean
- definition. See for more on this.
+ AuthenticationProvider beans as follows
+
+
+ ]]>
+ where myAuthenticationProvider is the name of a
+ bean in your application context which implements
+ AuthenticationProvider. See for more on information on how the Spring Security
+ AuthenticationManager is configured using the namespace.
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:
-
-
-
+
+
+
+
-
-
-
+
+
+
]]>
When using hashed passwords, it's also a good idea to use a salt value to protect
@@ -680,19 +689,24 @@
- The Default Authentication Manager
- We've touched on the idea that the namespace configuration automatically registers an
- authentication manager bean for you. This is 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 . You can't use a custom
+ 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 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 bean instance is registered using the
+ authentication-manager 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
- <custom-authentication-provider> element within the bean. 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:
+
+
@@ -703,11 +717,12 @@
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.
+
+ ...
+
-
...