@ -8,114 +8,111 @@
and information on the underlying beans they create (a knowledge of the individual classes 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 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 and elsewhere in this document). If you haven't used the namespace before, please read the
<link xlink:href= "#ns-config" > introductory chapter</link> on namespace configuration, as <link xlink:href= "#ns-config" > introductory chapter</link> on namespace configuration, as
this is intended as a supplement to the information there. Using a good quality XML editor 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 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 contextual information on which elements and attributes are available as well as comments
explaining their purpose. The namespace is written in <link explaining their purpose. The namespace is written in <link
xlink:href="http://www.relaxng.org/">RELAX NG</link> Compact format and later converted xlink:href="http://www.relaxng.org/">RELAX NG</link> Compact format and later converted into
into an XSD schema. If you are familiar with this format, you may wish to examine the <link an XSD schema. If you are familiar with this format, you may wish to examine the <link
xlink:href="https://src.springsource.org/svn/spring-security/trunk/config/src/main/resources/org/springframework/security/config/spring-security-3.0.rnc" xlink:href="https://src.springsource.org/svn/spring-security/trunk/config/src/main/resources/org/springframework/security/config/spring-security-3.0.rnc"
>schema file</link> directly.</para> >schema file</link> directly.</para>
<section xml:id= "nsa-http" > <section xml:id= "nsa-http" >
<title > Web Application Security - the <literal > < http> </literal> Element</title> <title > Web Application Security - the <literal > < http> </literal> Element</title>
<para > If you use an <literal > < http> </literal> element within your application, <para > If you use an <literal > < http> </literal> element within your application, a
a <classname > FilterChainProxy</classname> bean named "springSecurityFilterChain" is created and <classname > FilterChainProxy</classname> bean named "springSecurityFilterChain" is
the configuration within the element is used to build a filter chain within created and the configuration within the element is used to build a filter chain within
<classname > FilterChainProxy</classname> . As of Spring Security 3.1, additional <classname > FilterChainProxy</classname> . As of Spring Security 3.1, additional
<literal > http</literal> elements can be used to add extra filter chains <footnote > <literal > http</literal> elements can be used to add extra filter chains <footnote >
<para > See the <link xlink:href= "#ns-web-xml" > introductory chapter</link> for how to <para > See the <link xlink:href= "#ns-web-xml" > introductory chapter</link> for how to set
set up the mapping from your <literal > web.xml</literal> </para> up the mapping from your <literal > web.xml</literal> </para>
</footnote> . Some core filters are always created in a filter chain and others will be added </footnote> . Some core filters are always created in a filter chain and others will be
to the stack depending on the attributes and child elements which are present. The positions of t he added to the stack depending on the attributes and child elements which are present. The
standard filters are fixed (see <link xlink:href= "#filter-stack" > the filter order positions of the standard filters are fixed (see <link xlink:href= "#filter-stack" > the
table</link> in the namespace introduction), removing a common source of errors with filter order table</link> in the namespace introduction), removing a common source of
previous versions of the framework when users had to configure the filter chain errors with previous versions of the framework when users had to configure the filter
explicitly in the<classname > FilterChainProxy</classname> bean. You can, of course, still chain explicitly in the<classname > FilterChainProxy</classname> bean. You can, of course,
do this if you need full control of the configuration. </para> still do this if you need full control of the configuration. </para>
<para > All filters which require a reference to the <para > All filters which require a reference to the
<interfacename > AuthenticationManager</interfacename> will be automatically injected <interfacename > AuthenticationManager</interfacename> will be automatically injected with
with the internal instance created by the namespace configuration (see the <link the internal instance created by the namespace configuration (see the <link
xlink:href="#ns-auth-manager"> introductory chapter</link> for more on the xlink:href="#ns-auth-manager"> introductory chapter</link> for more on the
<interfacename > AuthenticationManager</interfacename> ). </para> <interfacename > AuthenticationManager</interfacename> ). </para>
<para > Each <literal > < http> </literal> namespace block always creates an <para > Each <literal > < http> </literal> namespace block always creates an
<classname > SecurityContextPersistenceFilter</classname> , an <classname > SecurityContextPersistenceFilter</classname> , an
<classname > ExceptionTranslationFilter</classname> and a <classname > ExceptionTranslationFilter</classname> and a
<classname > FilterSecurityInterceptor</classname> . These are fixed and cannot be <classname > FilterSecurityInterceptor</classname> . These are fixed and cannot be replaced
replaced with alternatives. </para> with alternatives. </para>
<section xml:id= "nsa-http-attributes" > <section xml:id= "nsa-http-attributes" >
<title > <literal > < http> </literal> Attributes</title> <title > <literal > < http> </literal> Attributes</title>
<para > The attributes on the <literal > < http> </literal> element control some of the <para > The attributes on the <literal > < http> </literal> element control some of the
properties on the core filters. </para> properties on the core filters. </para>
<section xml:id= "nsa-http-pattern" > <section xml:id= "nsa-http-pattern" >
<title > <literal > pattern</literal> </title> <title > <literal > pattern</literal> </title>
<para > Defining a pattern for the <literal > http</literal> element controls <para > Defining a pattern for the <literal > http</literal> element controls the
the requests which will be filtered through the list of filters which it defines. The requests which will be filtered through the list of filters which it defines.
interpretation is dependent on the configured <link xlink:href= "#nsa-path-type" > request-matcher</link> . The interpretation is dependent on the configured <link
If no pattern is defined, all requests will be matched, so the most specific patterns should be xlink:href="#nsa-path-type">request-matcher</link> . If no pattern is defined,
declared first. all requests will be matched, so the most specific patterns should be declared
</para> first. </para>
</section> </section>
<section xml:id= "nsa-http-secured" > <section xml:id= "nsa-http-secured" >
<title > <literal > secured</literal> </title> <title > <literal > security</literal> </title>
<para > A request pattern can be mapped to an empty filter chain, by setting <para > A request pattern can be mapped to an empty filter chain, by setting this
this attribute to <literal > false</literal> . No security will be applied and attribute to <literal > none</literal> . No security will be applied and none of
none of Spring Security's features will be available. Spring Security's features will be available. </para>
</para>
</section> </section>
<section xml:id= "nsa-servlet-api-provision" > <section xml:id= "nsa-servlet-api-provision" >
<title > <literal > servlet-api-provision</literal> </title> <title > <literal > servlet-api-provision</literal> </title>
<para > Provides versions of <literal > HttpServletRequest</literal> security methods <para > Provides versions of <literal > HttpServletRequest</literal> security methods
such as <literal > isUserInRole()</literal> and <literal > getPrincipal()</literal> such as <literal > isUserInRole()</literal> and <literal > getPrincipal()</literal>
which are implemented by adding a which are implemented by adding a
<classname > SecurityContextHolderAwareRequestFilter</classname> bean to the <classname > SecurityContextHolderAwareRequestFilter</classname> bean to the
stack. Defaults to "true".</para> stack. Defaults to "true".</para>
</section> </section>
<section xml:id= "nsa-path-type" > <section xml:id= "nsa-path-type" >
<title > <literal > request-matcher</literal> </title> <title > <literal > request-matcher</literal> </title>
<para > Defines the <interfacename > RequestMatcher</interfacename> strategy used in <para > Defines the <interfacename > RequestMatcher</interfacename> strategy used in
the <classname > FilterChainProxy</classname> and the beans created by the the <classname > FilterChainProxy</classname> and the beans created by the
<literal > intercept-url</literal> to match incoming requests. Options are <literal > intercept-url</literal> to match incoming requests. Options are
currently <literal > ant</literal> , <literal > regex</literal> and currently <literal > ant</literal> , <literal > regex</literal> and
<literal > ciRegex</literal> , for ant, regular-expression and case-insensitive <literal > ciRegex</literal> , for ant, regular-expression and case-insensitive
regular-expression repsectively. A separate instance is created for each regular-expression repsectively. A separate instance is created for each
<literal > intercept-url</literal> element using its <literal > intercept-url</literal> element using its <literal > pattern</literal>
<literal > pattern</literal> and <literal > method</literal> attributes (see and <literal > method</literal> attributes (see below). Ant paths are matched
below). Ant paths are matched using an using an <classname > AntPathRequestMatcher</classname> and regular expressions
<classname > AntPathRequestMatcher</classname> and regular expressions are are matched using a <classname > RegexRequestMatcher</classname> . See the Javadoc
matched using a <classname > RegexRequestMatcher</classname> . See the Javadoc for for these classes for more details on exactly how the matching is preformed. Ant
these classes for more details on exactly how the matching is preformed. Ant
paths are the default strategy.</para> paths are the default strategy.</para>
</section> </section>
<section xml:id= "nsa-realm" > <section xml:id= "nsa-realm" >
<title > <literal > realm</literal> </title> <title > <literal > realm</literal> </title>
<para > Sets the realm name used for basic authentication (if enabled). Corresponds <para > Sets the realm name used for basic authentication (if enabled). Corresponds
to the <literal > realmName</literal> property on to the <literal > realmName</literal> property on
<classname > BasicAuthenticationEntryPoint</classname> . </para> <classname > BasicAuthenticationEntryPoint</classname> . </para>
</section> </section>
<section xml:id= "nsa-entry-point-ref" > <section xml:id= "nsa-entry-point-ref" >
<title > <literal > entry-point-ref</literal> </title> <title > <literal > entry-point-ref</literal> </title>
<para > Normally the <interfacename > AuthenticationEntryPoint</interfacename> used <para > Normally the <interfacename > AuthenticationEntryPoint</interfacename> used
will be set depending on which authentication mechanisms have been configured. will be set depending on which authentication mechanisms have been configured.
This attribute allows this behaviour to be overridden by defining a customized This attribute allows this behaviour to be overridden by defining a customized
<interfacename > AuthenticationEntryPoint</interfacename> bean which will <interfacename > AuthenticationEntryPoint</interfacename> bean which will start
start the authentication process. </para> the authentication process. </para>
</section> </section>
<section xml:id= "nsa-security-context-repo-ref" > <section xml:id= "nsa-security-context-repo-ref" >
<title > <literal > security-context-repository-ref</literal> </title> <title > <literal > security-context-repository-ref</literal> </title>
<para > <para > Allows injection of a custom
Allows injection of a custom <interfacename > SecurityContextRepository</interfacename> <interfacename > SecurityContextRepository</interfacename> into the
into the <classname > SecurityContextPersistenceFilter</classname> . <classname > SecurityContextPersistenceFilter</classname> . </para>
</para>
</section> </section>
<section xml:id= "nsa-access-decision-manager-ref" > <section xml:id= "nsa-access-decision-manager-ref" >
<title > <literal > access-decision-manager-ref</literal> </title> <title > <literal > access-decision-manager-ref</literal> </title>
<para > Optional attribute specifying the ID of the <para > Optional attribute specifying the ID of the
<interfacename > AccessDecisionManager</interfacename> implementation which <interfacename > AccessDecisionManager</interfacename> implementation which should
should be used for authorizing HTTP requests. By default an be used for authorizing HTTP requests. By default an
<classname > AffirmativeBased</classname> implementation is used for with a <classname > AffirmativeBased</classname> implementation is used for with a
<classname > RoleVoter</classname> and an <classname > RoleVoter</classname> and an
<classname > AuthenticatedVoter</classname> . </para> <classname > AuthenticatedVoter</classname> . </para>
</section> </section>
<section xml:id= "nsa-access-denied-page" > <section xml:id= "nsa-access-denied-page" >
<title > <literal > access-denied-page</literal> </title> <title > <literal > access-denied-page</literal> </title>
@ -125,64 +122,62 @@
<section xml:id= "nsa-once-per-request" > <section xml:id= "nsa-once-per-request" >
<title > <literal > once-per-request</literal> </title> <title > <literal > once-per-request</literal> </title>
<para > Corresponds to the <literal > observeOncePerRequest</literal> property of <para > Corresponds to the <literal > observeOncePerRequest</literal> property of
<classname > FilterSecurityInterceptor</classname> . Defaults to "true". <classname > FilterSecurityInterceptor</classname> . Defaults to "true". </para>
</para>
</section> </section>
<section xml:id= "nsa-create-session" > <section xml:id= "nsa-create-session" >
<title > <literal > create-session</literal> </title> <title > <literal > create-session</literal> </title>
<para > Controls the eagerness with which an HTTP session is created. If not set, <para > 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 defaults to "ifRequired". Other options are "always" and "never". The setting of
this attribute affect the <literal > allowSessionCreation</literal> and this attribute affect the <literal > allowSessionCreation</literal> and
<literal > forceEagerSessionCreation</literal> properties of <literal > forceEagerSessionCreation</literal> properties of
<classname > HttpSessionContextIntegrationFilter</classname> . <classname > HttpSessionContextIntegrationFilter</classname> .
<literal > allowSessionCreation</literal> will always be true unless this <literal > allowSessionCreation</literal> will always be true unless this
attribute is set to "never". <literal > forceEagerSessionCreation</literal> is attribute is set to "never". <literal > forceEagerSessionCreation</literal> is
"false" unless it is set to "always". So the default configuration allows "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 session creation but does not force it. The exception is if concurrent session
control is enabled, when <literal > forceEagerSessionCreation</literal> will be control is enabled, when <literal > forceEagerSessionCreation</literal> will be
set to true, regardless of what the setting is here. Using "never" would then set to true, regardless of what the setting is here. Using "never" would then
cause an exception during the initialization of cause an exception during the initialization of
<classname > HttpSessionContextIntegrationFilter</classname> . </para> <classname > HttpSessionContextIntegrationFilter</classname> . </para>
</section> </section>
<section xml:id= "nsa-use-expressions" > <section xml:id= "nsa-use-expressions" >
<title > <literal > use-expressions</literal> </title> <title > <literal > use-expressions</literal> </title>
<para > Enables EL-expressions in the <literal > access</literal> attribute, as <para > Enables EL-expressions in the <literal > access</literal> attribute, as
described in the chapter on <link xlink:href= "#el-access-web" > expression-based described in the chapter on <link xlink:href= "#el-access-web" > expression-based
access-control</link> . </para> access-control</link> . </para>
</section> </section>
<section xml:id= "nsa-disable-url-rewriting" > <section xml:id= "nsa-disable-url-rewriting" >
<title > <literal > disable-url-rewriting</literal> </title> <title > <literal > disable-url-rewriting</literal> </title>
<para > Prevents session IDs from being appended to URLs in the application. <para > Prevents session IDs from being appended to URLs in the application. Clients
Clients must use cookies if this attribute is set to <literal > true</literal> . must use cookies if this attribute is set to <literal > true</literal> . </para>
</para>
</section> </section>
</section> </section>
<section xml:id= "nsa-access-denied-handler" > <section xml:id= "nsa-access-denied-handler" >
<title > <literal > < access-denied-handler></literal> </title> <title > <literal > < access-denied-handler></literal> </title>
<para > This element allows you to set the <literal > errorPage</literal> property for the <para > This element allows you to set the <literal > errorPage</literal> property for the
default <interfacename > AccessDeniedHandler</interfacename> used by the default <interfacename > AccessDeniedHandler</interfacename> used by the
<classname > ExceptionTranslationFilter</classname> , (using the <classname > ExceptionTranslationFilter</classname> , (using the
<literal > error-page</literal> attribute, or to supply your own implementation <literal > error-page</literal> attribute, or to supply your own implementation using
using the <literal > ref</literal> attribute. This is discussed in more detail in the the <literal > ref</literal> attribute. This is discussed in more detail in the
section on <link xlink:href= "#access-denied-handler" > the section on <link xlink:href= "#access-denied-handler" > the
<classname > ExceptionTranslationFilter</classname> </link> .</para> <classname > ExceptionTranslationFilter</classname> </link> .</para>
</section> </section>
<section > <section >
<title > The <literal > < intercept-url> </literal> Element</title> <title > The <literal > < intercept-url> </literal> Element</title>
<para > This element is used to define the set of URL patterns that the application is <para > 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 interested in and to configure how they should be handled. It is used to construct
the <interfacename > FilterInvocationSecurityMetadataSource</interfacename> used by the <interfacename > FilterInvocationSecurityMetadataSource</interfacename> used by
the <classname > FilterSecurityInterceptor</classname> . It is also responsible for configuring a the <classname > FilterSecurityInterceptor</classname> . It is also responsible for
<classname > ChannelAuthenticationFilter</classname> if particular URLs need to be configuring a <classname > ChannelAuthenticationFilter</classname> if particular URLs
accessed by HTTPS, for example. When matching the specified patterns against an need to be accessed by HTTPS, for example. When matching the specified patterns
incoming request, the matching is done in the order in which the elements are against an incoming request, the matching is done in the order in which the elements
declared. So the most specific matches patterns should come first and the most are declared. So the most specific matches patterns should come first and the most
general should come last.</para> general should come last.</para>
<section xml:id= "nsa-pattern" > <section xml:id= "nsa-pattern" >
<title > <literal > pattern</literal> </title> <title > <literal > pattern</literal> </title>
<para > The pattern which defines the URL path. The content will depend on the <para > The pattern which defines the URL path. The content will depend on the
<literal > request-matcher</literal> attribute from the containing http <literal > request-matcher</literal> attribute from the containing http element,
element, so will default to ant path syntax. </para> so will default to ant path syntax. </para>
</section> </section>
<section xml:id= "nsa-method" > <section xml:id= "nsa-method" >
<title > <literal > method</literal> </title> <title > <literal > method</literal> </title>
@ -194,9 +189,9 @@
<section xml:id= "nsa-access" > <section xml:id= "nsa-access" >
<title > <literal > access</literal> </title> <title > <literal > access</literal> </title>
<para > Lists the access attributes which will be stored in the <para > Lists the access attributes which will be stored in the
<interfacename > FilterInvocationSecurityMetadataSource</interfacename> for <interfacename > FilterInvocationSecurityMetadataSource</interfacename> for the
the defined URL pattern/method combination. This should be a comma-separated defined URL pattern/method combination. This should be a comma-separated list of
list of the security configuration attributes (such as role names). </para> the security configuration attributes (such as role names). </para>
</section> </section>
<section xml:id= "nsa-requires-channel" > <section xml:id= "nsa-requires-channel" >
<title > <literal > requires-channel</literal> </title> <title > <literal > requires-channel</literal> </title>
@ -204,15 +199,15 @@
particular URL pattern should be accessed over HTTP or HTTPS respectively. particular URL pattern should be accessed over HTTP or HTTPS respectively.
Alternatively the value <quote > any</quote> can be used when there is no Alternatively the value <quote > any</quote> can be used when there is no
preference. If this attribute is present on any preference. If this attribute is present on any
<literal > < intercept-url> </literal> element, then a <literal > < intercept-url> </literal> element, then a
<classname > ChannelAuthenticationFilter</classname> will be added to the <classname > ChannelAuthenticationFilter</classname> will be added to the filter
filter stack and its additional dependencies added to the application stack and its additional dependencies added to the application
context.<!-- See the chapter on <link context.<!-- See the chapter on <link
xlink:href="#channel-security-config">channel security</link> for an example xlink:href="#channel-security-config">channel security</link> for an example
configuration using traditional beans. --></para> configuration using traditional beans. --></para>
<para > If a <literal > < port-mappings> </literal> configuration is added, this <para > If a <literal > < port-mappings> </literal> configuration is added, this
will be used to by the <classname > SecureChannelProcessor</classname> and will be used to by the <classname > SecureChannelProcessor</classname> and
<classname > InsecureChannelProcessor</classname> beans to determine the ports <classname > InsecureChannelProcessor</classname> beans to determine the ports
used for redirecting to HTTP/HTTPS. </para> used for redirecting to HTTP/HTTPS. </para>
</section> </section>
<section > <section >
@ -232,7 +227,7 @@
Each child <literal > < port-mapping> </literal> element defines a pair of Each child <literal > < port-mapping> </literal> element defines a pair of
HTTP:HTTPS ports. The default mappings are 80:443 and 8080:8443. An example of HTTP:HTTPS ports. The default mappings are 80:443 and 8080:8443. An example of
overriding these can be found in the <link xlink:href= "#ns-requires-channel" overriding these can be found in the <link xlink:href= "#ns-requires-channel"
>namespace introduction</link> . </para> >namespace introduction</link> . </para>
</section> </section>
<section xml:id= "nsa-form-login" > <section xml:id= "nsa-form-login" >
<title > The <literal > < form-login> </literal> Element</title> <title > The <literal > < form-login> </literal> Element</title>
@ -241,30 +236,30 @@
application context to provide authentication on demand. This will always take application context to provide authentication on demand. This will always take
precedence over other namespace-created entry points. If no attributes are supplied, 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" <footnote > a login page will be generated automatically at the URL "/spring-security-login" <footnote >
<para > This feature is really just provided for convenience and is not intended <para > This feature is really just provided for convenience and is not intended for
for production (where a view technology will have been chosen and can be production (where a view technology will have been chosen and can be used to
used to render a customized login page). The class render a customized login page). The class
<classname > DefaultLoginPageGeneratingFilter</classname> is responsible <classname > DefaultLoginPageGeneratingFilter</classname> is responsible for
for rendering the login page and will provide login forms for both normal rendering the login page and will provide login forms for both normal form login
form login and/or OpenID if required.</para> and/or OpenID if required.</para>
</footnote> The behaviour can be customized using the following attributes. </para> </footnote> The behaviour can be customized using the following attributes. </para>
<section > <section >
<title > <literal > login-page</literal> </title> <title > <literal > login-page</literal> </title>
<para > The URL that should be used to render the login page. Maps to the <para > The URL that should be used to render the login page. Maps to the
<literal > loginFormUrl</literal> property of the <literal > loginFormUrl</literal> property of the
<classname > LoginUrlAuthenticationEntryPoint</classname> . Defaults to <classname > LoginUrlAuthenticationEntryPoint</classname> . Defaults to
"/spring-security-login". </para> "/spring-security-login". </para>
</section> </section>
<section > <section >
<title > <literal > login-processing-url</literal> </title> <title > <literal > login-processing-url</literal> </title>
<para > Maps to the <literal > filterProcessesUrl</literal> property of <para > Maps to the <literal > filterProcessesUrl</literal> property of
<classname > UsernamePasswordAuthenticationFilter</classname> . The default <classname > UsernamePasswordAuthenticationFilter</classname> . The default value
value is "/j_spring_security_check". </para> is "/j_spring_security_check". </para>
</section> </section>
<section > <section >
<title > <literal > default-target-url</literal> </title> <title > <literal > default-target-url</literal> </title>
<para > Maps to the <literal > defaultTargetUrl</literal> property of <para > Maps to the <literal > defaultTargetUrl</literal> property of
<classname > UsernamePasswordAuthenticationFilter</classname> . If not set, the <classname > UsernamePasswordAuthenticationFilter</classname> . If not set, the
default value is "/" (the application root). A user will be taken to this URL 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 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 access a secured resource, when they will be taken to the originally requested
@ -273,16 +268,16 @@
<section > <section >
<title > <literal > always-use-default-target</literal> </title> <title > <literal > always-use-default-target</literal> </title>
<para > If set to "true", the user will always start at the value given by <para > If set to "true", the user will always start at the value given by
<literal > default-target-url</literal> , regardless of how they arrived at the <literal > default-target-url</literal> , regardless of how they arrived at the
login page. Maps to the <literal > alwaysUseDefaultTargetUrl</literal> property of login page. Maps to the <literal > alwaysUseDefaultTargetUrl</literal> property of
<classname > UsernamePasswordAuthenticationFilter</classname> . Default value <classname > UsernamePasswordAuthenticationFilter</classname> . Default value is
is "false". </para> "false". </para>
</section> </section>
<section > <section >
<title > <literal > authentication-failure-url</literal> </title> <title > <literal > authentication-failure-url</literal> </title>
<para > Maps to the <literal > authenticationFailureUrl</literal> property of <para > Maps to the <literal > authenticationFailureUrl</literal> property of
<classname > UsernamePasswordAuthenticationFilter</classname> . Defines the URL <classname > UsernamePasswordAuthenticationFilter</classname> . Defines the URL the
the browser will be redirected to on login failure. Defaults to browser will be redirected to on login failure. Defaults to
"/spring_security_login?login_error", which will be automatically handled by the "/spring_security_login?login_error", which will be automatically handled by the
automatic login page generator, re-rendering the login page with an error automatic login page generator, re-rendering the login page with an error
message. </para> message. </para>
@ -294,8 +289,8 @@
the navigation flow after a successful authentication. The value should be the the navigation flow after a successful authentication. The value should be the
name of an <interfacename > AuthenticationSuccessHandler</interfacename> bean in name of an <interfacename > AuthenticationSuccessHandler</interfacename> bean in
the application context. By default, an imlementation of the application context. By default, an imlementation of
<classname > SavedRequestAwareAuthenticationSuccessHandler</classname> is used <classname > SavedRequestAwareAuthenticationSuccessHandler</classname> is used an d
and injected with the <literal > default-target-url</literal> .</para> injected with the <literal > default-target-url</literal> .</para>
</section> </section>
<section > <section >
<title > <literal > authentication-failure-handler-ref</literal> </title> <title > <literal > authentication-failure-handler-ref</literal> </title>
@ -309,7 +304,7 @@
<section xml:id= "nsa-http-basic" > <section xml:id= "nsa-http-basic" >
<title > The <literal > < http-basic> </literal> Element</title> <title > The <literal > < http-basic> </literal> Element</title>
<para > Adds a <classname > BasicAuthenticationFilter</classname> and <para > Adds a <classname > BasicAuthenticationFilter</classname> and
<classname > BasicAuthenticationEntryPoint</classname> to the configuration. The <classname > BasicAuthenticationEntryPoint</classname> to the configuration. The
latter will only be used as the configuration entry point if form-based login is not latter will only be used as the configuration entry point if form-based login is not
enabled. </para> enabled. </para>
</section> </section>
@ -317,57 +312,57 @@
<title > The <literal > < remember-me> </literal> Element</title> <title > The <literal > < remember-me> </literal> Element</title>
<para > Adds the <classname > RememberMeAuthenticationFilter</classname> to the stack. This <para > Adds the <classname > RememberMeAuthenticationFilter</classname> to the stack. This
in turn will be configured with either a in turn will be configured with either a
<classname > TokenBasedRememberMeServices</classname> , a <classname > TokenBasedRememberMeServices</classname> , a
<classname > PersistentTokenBasedRememberMeServices</classname> or a <classname > PersistentTokenBasedRememberMeServices</classname> or a user-specified
user-specified bean implementing <interfacename > RememberMeServices</interfacename> bean implementing <interfacename > RememberMeServices</interfacename> depending on the
depending on the attribute settings. </para> attribute settings. </para>
<section > <section >
<title > <literal > data-source-ref</literal> </title> <title > <literal > data-source-ref</literal> </title>
<para > If this is set, <classname > PersistentTokenBasedRememberMeServices</classname> <para > If this is set, <classname > PersistentTokenBasedRememberMeServices</classname>
will be used and configured with a will be used and configured with a
<classname > JdbcTokenRepositoryImpl</classname> instance. </para> <classname > JdbcTokenRepositoryImpl</classname> instance. </para>
</section> </section>
<section > <section >
<title > <literal > token-repository-ref</literal> </title> <title > <literal > token-repository-ref</literal> </title>
<para > Configures a <classname > PersistentTokenBasedRememberMeServices</classname> <para > Configures a <classname > PersistentTokenBasedRememberMeServices</classname>
but allows the use of a custom but allows the use of a custom
<interfacename > PersistentTokenRepository</interfacename> bean. </para> <interfacename > PersistentTokenRepository</interfacename> bean. </para>
</section> </section>
<section > <section >
<title > <literal > services-ref</literal> </title> <title > <literal > services-ref</literal> </title>
<para > Allows complete control of the <para > Allows complete control of the
<interfacename > RememberMeServices</interfacename> implementation that will <interfacename > RememberMeServices</interfacename> implementation that will be
be used by the filter. The value should be the Id of a bean in the application used by the filter. The value should be the Id of a bean in the application
context which implements this interface. </para> context which implements this interface. </para>
</section> </section>
<section > <section >
<title > <literal > token-repository-ref</literal> </title> <title > <literal > token-repository-ref</literal> </title>
<para > Configures a <classname > PersistentTokenBasedRememberMeServices</classname> <para > Configures a <classname > PersistentTokenBasedRememberMeServices</classname>
but allows the use of a custom but allows the use of a custom
<interfacename > PersistentTokenRepository</interfacename> bean. </para> <interfacename > PersistentTokenRepository</interfacename> bean. </para>
</section> </section>
<section > <section >
<title > The <literal > key</literal> Attribute</title> <title > The <literal > key</literal> Attribute</title>
<para > Maps to the "key" property of <para > Maps to the "key" property of
<classname > AbstractRememberMeServices</classname> . Should be set to a unique <classname > AbstractRememberMeServices</classname> . Should be set to a unique
value to ensure that remember-me cookies are only valid within the one value to ensure that remember-me cookies are only valid within the one
application <footnote > application <footnote >
<para > This doesn't affect the use of <para > This doesn't affect the use of
<classname > PersistentTokenBasedRememberMeServices</classname> , where <classname > PersistentTokenBasedRememberMeServices</classname> , where th e
the tokens are stored on the server side.</para> tokens are stored on the server side.</para>
</footnote> . </para> </footnote> . </para>
</section> </section>
<section > <section >
<title > <literal > token-validity-seconds</literal> </title> <title > <literal > token-validity-seconds</literal> </title>
<para > Maps to the <literal > tokenValiditySeconds</literal> property of <para > Maps to the <literal > tokenValiditySeconds</literal> property of
<classname > AbstractRememberMeServices</classname> . Specifies the period in <classname > AbstractRememberMeServices</classname> . Specifies the period in
seconds for which the remember-me cookie should be valid. By default it will be seconds for which the remember-me cookie should be valid. By default it will be
valid for 14 days. </para> valid for 14 days. </para>
</section> </section>
<section > <section >
<title > <literal > user-service-ref</literal> </title> <title > <literal > user-service-ref</literal> </title>
<para > The remember-me services implementations require access to a <para > The remember-me services implementations require access to a
<interfacename > UserDetailsService</interfacename> , so there has to be one <interfacename > UserDetailsService</interfacename> , so there has to be one
defined in the application context. If there is only one, it will be selected 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 and used automatically by the namespace configuration. If there are multiple
instances, you can specify a bean Id explicitly using this attribute. </para> instances, you can specify a bean Id explicitly using this attribute. </para>
@ -376,7 +371,7 @@
<section xml:id= "nsa-session-mgmt" > <section xml:id= "nsa-session-mgmt" >
<title > The <literal > < session-management> </literal> Element</title> <title > The <literal > < session-management> </literal> Element</title>
<para > Session-management related functionality is implemented by the addition of a <para > Session-management related functionality is implemented by the addition of a
<classname > SessionManagementFilter</classname> to the filter stack.</para> <classname > SessionManagementFilter</classname> to the filter stack.</para>
<section xml:id= "session-fixation-protection" > <section xml:id= "session-fixation-protection" >
<title > <literal > session-fixation-protection</literal> </title> <title > <literal > session-fixation-protection</literal> </title>
<para > Indicates whether an existing session should be invalidated when a user <para > Indicates whether an existing session should be invalidated when a user
@ -385,28 +380,27 @@
a new session and copy the session attributes to the new session. Defaults to a new session and copy the session attributes to the new session. Defaults to
"migrateSession".</para> "migrateSession".</para>
<para > If session fixation protection is enabled, the <para > If session fixation protection is enabled, the
<classname > SessionManagementFilter</classname> is inected with a <classname > SessionManagementFilter</classname> is inected with a appropriately
appropriately configured configured <classname > DefaultSessionAuthenticationStrategy</classname> . See the
<classname > DefaultSessionAuthenticationStrategy</classname> . See the Javadoc Javadoc for this class for more details. </para>
for this class for more details. </para>
</section> </section>
</section> </section>
<section xml:id= "nsa-concurrent-session-control" > <section xml:id= "nsa-concurrent-session-control" >
<title > The <literal > < concurrency-control> </literal> Element</title> <title > The <literal > < concurrency-control> </literal> Element</title>
<para > Adds support for concurrent session control, allowing limits to be placed on the <para > Adds support for concurrent session control, allowing limits to be placed on the
number of active sessions a user can have. A number of active sessions a user can have. A
<classname > ConcurrentSessionFilter</classname> will be created, and a <classname > ConcurrentSessionFilter</classname> will be created, and a
<classname > ConcurrentSessionControlStrategy</classname> will be used with the <classname > ConcurrentSessionControlStrategy</classname> will be used with the
<classname > SessionManagementFilter</classname> . If a <classname > SessionManagementFilter</classname> . If a <literal > form-login</literal>
<literal > form-login</literal> element has been declared, the strategy object element has been declared, the strategy object will also be injected into the
will also be injected into the created authentication filter. An instance of created authentication filter. An instance of
<interfacename > SessionRegistry</interfacename> (a <interfacename > SessionRegistry</interfacename> (a
<classname > SessionRegistryImpl</classname> instance unless the user wishes to <classname > SessionRegistryImpl</classname> instance unless the user wishes to use a
use a custom bean) will be created for use by the strategy.</para> custom bean) will be created for use by the strategy.</para>
<section > <section >
<title > The <literal > max-sessions</literal> attribute</title> <title > The <literal > max-sessions</literal> attribute</title>
<para > Maps to the <literal > maximumSessions</literal> property of <para > Maps to the <literal > maximumSessions</literal> property of
<classname > ConcurrentSessionControlStrategy</classname> .</para> <classname > ConcurrentSessionControlStrategy</classname> .</para>
</section> </section>
<section > <section >
<title > The <literal > expired-url</literal> attribute</title> <title > The <literal > expired-url</literal> attribute</title>
@ -420,13 +414,13 @@
<section > <section >
<title > The <literal > error-if-maximum-exceeded</literal> attribute</title> <title > The <literal > error-if-maximum-exceeded</literal> attribute</title>
<para > If set to "true" a <para > If set to "true" a
<exceptionname > SessionAuthenticationException</exceptionname> will be raised <exceptionname > SessionAuthenticationException</exceptionname> will be raised
when a user attempts to exceed the maximum allowed number of sessions. The when a user attempts to exceed the maximum allowed number of sessions. The
default behaviour is to expire the original session. </para> default behaviour is to expire the original session. </para>
</section> </section>
<section > <section >
<title > The <literal > session-registry-alias</literal> and <title > The <literal > session-registry-alias</literal> and
<literal > session-registry-ref</literal> attributes</title> <literal > session-registry-ref</literal> attributes</title>
<para > The user can supply their own <interfacename > SessionRegistry</interfacename> <para > The user can supply their own <interfacename > SessionRegistry</interfacename>
implementation using the <literal > session-registry-ref</literal> attribute. The implementation using the <literal > session-registry-ref</literal> attribute. The
other concurrent session control beans will be wired up to use it. </para> other concurrent session control beans will be wired up to use it. </para>
@ -439,24 +433,24 @@
<section xml:id= "nsa-anonymous" > <section xml:id= "nsa-anonymous" >
<title > The <literal > < anonymous> </literal> Element</title> <title > The <literal > < anonymous> </literal> Element</title>
<para > Adds an <classname > AnonymousAuthenticationFilter</classname> to the stack and an <para > Adds an <classname > AnonymousAuthenticationFilter</classname> to the stack and an
<classname > AnonymousAuthenticationProvider</classname> . Required if you are <classname > AnonymousAuthenticationProvider</classname> . Required if you are using
using the <literal > IS_AUTHENTICATED_ANONYMOUSLY</literal> attribute. </para> the <literal > IS_AUTHENTICATED_ANONYMOUSLY</literal> attribute. </para>
</section> </section>
<section xml:id= "nsa-x509" > <section xml:id= "nsa-x509" >
<title > The <literal > < x509> </literal> Element</title> <title > The <literal > < x509> </literal> Element</title>
<para > Adds support for X.509 authentication. An <para > Adds support for X.509 authentication. An
<classname > X509AuthenticationFilter</classname> will be added to the stack and <classname > X509AuthenticationFilter</classname> will be added to the stack and an
an <classname > Http403ForbiddenEntryPoint</classname> bean will be created. The <classname > Http403ForbiddenEntryPoint</classname> bean will be created. The latter
latter will only be used if no other authentication mechanisms are in use (it's only 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 functionality is to return an HTTP 403 error code). A
<classname > PreAuthenticatedAuthenticationProvider</classname> will also be <classname > PreAuthenticatedAuthenticationProvider</classname> will also be created
created which delegates the loading of user authorities to a which delegates the loading of user authorities to a
<interfacename > UserDetailsService</interfacename> . </para> <interfacename > UserDetailsService</interfacename> . </para>
<section > <section >
<title > The <literal > subject-principal-regex</literal> attribute</title> <title > The <literal > subject-principal-regex</literal> attribute</title>
<para > Defines a regular expression which will be used to extract the username from <para > Defines a regular expression which will be used to extract the username from
the certificate (for use with the the certificate (for use with the
<interfacename > UserDetailsService</interfacename> ). </para> <interfacename > UserDetailsService</interfacename> ). </para>
</section> </section>
<section > <section >
<title > The <literal > user-service-ref</literal> attribute</title> <title > The <literal > user-service-ref</literal> attribute</title>
@ -471,10 +465,10 @@
<para > Similar to <literal > < form-login> </literal> and has the same attributes. The <para > Similar to <literal > < form-login> </literal> and has the same attributes. The
default value for <literal > login-processing-url</literal> is default value for <literal > login-processing-url</literal> is
"/j_spring_openid_security_check". An "/j_spring_openid_security_check". An
<classname > OpenIDAuthenticationFilter</classname> and <classname > OpenIDAuthenticationFilter</classname> and
<classname > OpenIDAuthenticationProvider</classname> will be registered. The <classname > OpenIDAuthenticationProvider</classname> will be registered. The latter
latter requires a reference to a <interfacename > UserDetailsService</interfacename> . requires a reference to a <interfacename > UserDetailsService</interfacename> . Again,
Again, this can be specified by Id, using the <literal > user-service-ref</literal> this can be specified by Id, using the <literal > user-service-ref</literal>
attribute, or will be located automatically in the application context. </para> attribute, or will be located automatically in the application context. </para>
<section > <section >
<title > The <literal > < attribute-exchange></literal> Element</title> <title > The <literal > < attribute-exchange></literal> Element</title>
@ -503,86 +497,85 @@
<section > <section >
<title > The <literal > invalidate-session</literal> attribute</title> <title > The <literal > invalidate-session</literal> attribute</title>
<para > Maps to the <literal > invalidateHttpSession</literal> of the <para > Maps to the <literal > invalidateHttpSession</literal> of the
<classname > SecurityContextLogoutHandler</classname> . Defaults to "true", so <classname > SecurityContextLogoutHandler</classname> . Defaults to "true", so the
the session will be invalidated on logout. </para> session will be invalidated on logout. </para>
</section> </section>
</section> </section>
<section > <section >
<title > The <literal > < custom-filter></literal> Element</title> <title > The <literal > < custom-filter></literal> Element</title>
<para > This element is used to add a filter to the filter chain. It doesn't create any <para > 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 additional beans but is used to select a bean of type
<interfacename > javax.servlet.Filter</interfacename> which is already defined in <interfacename > javax.servlet.Filter</interfacename> which is already defined in the
the appllication context and add that at a particular position in the filter chain 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 maintained by Spring Security. Full details can be found in the namespace
chapter.</para> chapter.</para>
</section> </section>
<section xml:id= "nsa-request-cache" > <section xml:id= "nsa-request-cache" >
<title > The <literal > request-cache</literal> Element</title> <title > The <literal > request-cache</literal> Element</title>
<para > Sets the <interfacename > RequestCache</interfacename> instance which will be used <para > Sets the <interfacename > RequestCache</interfacename> instance which will be used
by the <classname > ExceptionTranslationFilter</classname> to store request information by the <classname > ExceptionTranslationFilter</classname> to store request
before invoking an <interfacename > AuthenticationEntryPoint</interfacename> . information before invoking an
</para> <interfacename > AuthenticationEntryPoint</interfacename> . </para>
</section> </section>
</section> </section>
<section xml:id= "nsa-authentication" > <section xml:id= "nsa-authentication" >
<title > Authentication Services</title> <title > Authentication Services</title>
<para > Before Spring Security 3.0, an <interfacename > AuthenticationManager</interfacename> <para > Before Spring Security 3.0, an <interfacename > AuthenticationManager</interfacename>
was automatically registered internally. Now you must register one explicitly using the was automatically registered internally. Now you must register one explicitly using the
<literal > < authentication-manager> </literal> element. This creates an instance <literal > < authentication-manager> </literal> element. This creates an instance of
of Spring Security's <classname > ProviderManager</classname> class, which needs to be Spring Security's <classname > ProviderManager</classname> class, which needs to be
configured with a list of one or more configured with a list of one or more
<interfacename > AuthenticationProvider</interfacename> instances. These can either be <interfacename > AuthenticationProvider</interfacename> instances. These can either be
created using syntax elements provided by the namespace, or they can be standard bean created using syntax elements provided by the namespace, or they can be standard bean
definitions, marked for addition to the list using the definitions, marked for addition to the list using the
<literal > authentication-provider</literal> element. </para> <literal > authentication-provider</literal> element. </para>
<section > <section >
<title > The <literal > < authentication-manager> </literal> Element</title> <title > The <literal > < authentication-manager> </literal> Element</title>
<para > Every Spring Security application which uses the namespace must have include this <para > Every Spring Security application which uses the namespace must have include this
element somewhere. It is responsible for registering the element somewhere. It is responsible for registering the
<interfacename > AuthenticationManager</interfacename> which provides <interfacename > AuthenticationManager</interfacename> which provides authentication
authentication services to the application. It also allows you to define an alias services to the application. It also allows you to define an alias name for the
name for the internal instance for use in your own configuration. Its use is internal instance for use in your own configuration. Its use is described in the
described in the <link xlink:href= "#ns-auth-manager" > namespace introduction</link> . <link xlink:href= "#ns-auth-manager" > namespace introduction</link> . All elements
All elements which create <interfacename > AuthenticationProvider</interfacename> which create <interfacename > AuthenticationProvider</interfacename> instances should
instances should be children of this element.</para> be children of this element.</para>
<para > <para > The element also exposes an <literal > erase-credentials</literal> attribute which
The element also exposes an <literal > erase-credentials</literal> attribute which maps maps to the <literal > eraseCredentialsAfterAuthentication</literal> property of the
to the <literal > eraseCredentialsAfterAuthentication</literal> property of <classname > ProviderManager</classname> . This is discussed in the <link
the <classname > ProviderManager</classname> . This is discussed in the xlink:href="#core-services-erasing-credentials">Core Services</link> chapter.</para>
<link xlink:href= "#core-services-erasing-credentials" > Core Services</link> chapter.</para>
<section > <section >
<title > The <literal > < authentication-provider> </literal> Element</title> <title > The <literal > < authentication-provider> </literal> Element</title>
<para > Unless used with a <literal > ref</literal> attribute, this element is <para > Unless used with a <literal > ref</literal> attribute, this element is
shorthand for configuring a <link xlink:href= "#core-services-dao-provider" shorthand for configuring a <link xlink:href= "#core-services-dao-provider"
><classname > DaoAuthenticationProvider</classname> </link> . ><classname > DaoAuthenticationProvider</classname> </link> .
<classname > DaoAuthenticationProvider</classname> loads user information from <classname > DaoAuthenticationProvider</classname> loads user information from a
a <interfacename > UserDetailsService</interfacename> and compares the <interfacename > UserDetailsService</interfacename> and compares the
username/password combination with the values supplied at login. The username/password combination with the values supplied at login. The
<interfacename > UserDetailsService</interfacename> instance can be defined <interfacename > UserDetailsService</interfacename> instance can be defined either
either by using an available namespace element by using an available namespace element (<literal > jdbc-user-service</literal> or
(<literal > jdbc-user-service</literal> or by using the by using the <literal > user-service-ref</literal> attribute to point to a bean
<literal > user-service-ref</literal> attribute to point to a bean defined defined elsewhere in the application context). You can find examples of these
elsewhere in the application context). You can find examples of these variations variations in the <link xlink:href= "#ns-auth-providers" > namespace
in the <link xlink:href= "#ns-auth-providers" > namespace in troduction</link> . </para> introduction</link> . </para>
<section > <section >
<title > The <literal > < password-encoder> </literal> Element</title> <title > The <literal > < password-encoder> </literal> Element</title>
<para > Authentication providers can optionally be configured to use a password <para > Authentication providers can optionally be configured to use a password
encoder as described in the <link xlink:href= "#ns-password-encoder" encoder as described in the <link xlink:href= "#ns-password-encoder"
>namespace introduction</link> . This will result in the bean being >namespace introduction</link> . This will result in the bean being injected
injected with the appropriate <interfacename > PasswordEncoder</interfacename> with the appropriate <interfacename > PasswordEncoder</interfacename>
instance, potentially with an accompanying instance, potentially with an accompanying
<interfacename > SaltSource</interfacename> bean to provide salt values <interfacename > SaltSource</interfacename> bean to provide salt values for
for hashing. </para> hashing. </para>
</section> </section>
</section> </section>
<section > <section >
<title > Using <literal > < authentication-provider> </literal> to refer to an <title > Using <literal > < authentication-provider> </literal> to refer to an
<interfacename > AuthenticationProvider</interfacename> Bean</title> <interfacename > AuthenticationProvider</interfacename> Bean</title>
<para > If you have written your own <para > If you have written your own
<interfacename > AuthenticationProvider</interfacename> implementation (or <interfacename > AuthenticationProvider</interfacename> implementation (or want to
want to configure one of Spring Security's own implementations as a traditional configure one of Spring Security's own implementations as a traditional bean for
bean for some reason, then you can use the following syntax to add it to the some reason, then you can use the following syntax to add it to the internal
internal <classname > ProviderManager</classname> 's list: <programlisting > < 
Luke Taylor
16 years ago