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