mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-09-08 20:51:41 +00:00
706 lines
49 KiB
XML
706 lines
49 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<appendix version="5.0" xml:id="appendix-namespace" xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<info>
|
|
<title>The Security Namespace</title>
|
|
</info>
|
|
<para> This appendix provides a reference to the elements available in the security namespace
|
|
and information on the underlying beans they create (a knowledge of the individual classes
|
|
and how they work together is assumed - you can find more information in the project Javadoc
|
|
and elsewhere in this document). If you haven't used the namespace before, please read the
|
|
<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="http://git.springsource.org/spring-security/spring-security/blobs/3.0.x/config/src/main/resources/org/springframework/security/config/spring-security-3.0.4.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
|
|
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>
|
|
</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
|
|
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>
|
|
<para> The <literal><http></literal> namespace block always creates an
|
|
<classname>SecurityContextPersistenceFilter</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
|
|
properties on the core filters. </para>
|
|
<section xml:id="nsa-servlet-api-provision">
|
|
<title><literal>servlet-api-provision</literal></title>
|
|
<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
|
|
stack. Defaults to "true". </para>
|
|
</section>
|
|
<section xml:id="nsa-path-type">
|
|
<title><literal>path-type</literal></title>
|
|
<para> Controls whether URL patterns are interpreted as ant paths (the default) or
|
|
regular expressions. In practice this sets a particular
|
|
<interfacename>UrlMatcher</interfacename> instance on the
|
|
<classname>FilterChainProxy</classname>. </para>
|
|
</section>
|
|
<section xml:id="nsa-lowercase-comparisons">
|
|
<title><literal>lowercase-comparisons</literal></title>
|
|
<para> Whether test URLs should be converted to lower case prior to comparing with
|
|
defined path patterns. If unspecified, defaults to "true" </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>
|
|
</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>
|
|
</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>
|
|
</section>
|
|
<section xml:id="nsa-access-denied-page">
|
|
<title><literal>access-denied-page</literal></title>
|
|
<para> Deprecated in favour of the <literal>access-denied-handler</literal> child
|
|
element. </para>
|
|
</section>
|
|
<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>
|
|
</section>
|
|
<section xml:id="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>SecurityContextPersistenceFilter</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>SecurityContextPersistenceFilter</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>
|
|
</section>
|
|
<section xml:id="nsa-disable-url-rewriting">
|
|
<title><literal>disable-url-rewriting</literal></title>
|
|
<para>Prevents session IDs from being appended to URLs in the application. Clients
|
|
must use cookies if this attribute is set to <literal>true</literal>. </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
|
|
section on <link xlink:href="#access-denied-handler">the
|
|
<classname>ExceptionTranslationFilter</classname></link>.</para>
|
|
</section>
|
|
<section>
|
|
<title>The <literal><intercept-url></literal> Element</title>
|
|
<para> This element is used to define the set of URL patterns that the application is
|
|
interested in and to configure how they should be handled. It is used to construct
|
|
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
|
|
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
|
|
general should come last.</para>
|
|
<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>path-type</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>
|
|
<para> The HTTP Method which will be used in combination with the pattern to match
|
|
an incoming request. If omitted, any method will match. If an identical pattern
|
|
is specified with and without a method, the method-specific match will take
|
|
precedence.</para>
|
|
</section>
|
|
<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>
|
|
</section>
|
|
<section xml:id="nsa-requires-channel">
|
|
<title><literal>requires-channel</literal></title>
|
|
<para> Can be <quote>http</quote> or <quote>https</quote> depending on whether a
|
|
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
|
|
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
|
|
used for redirecting to HTTP/HTTPS. </para>
|
|
</section>
|
|
<section>
|
|
<title><literal>filters</literal></title>
|
|
<para>Can only take the value <quote>none</quote>. This will cause any matching
|
|
request to bypass the Spring Security filter chain entirely. None of the rest of
|
|
the <literal><http></literal> configuration will have any effect on the
|
|
request and there will be no security context available for its duration. Access
|
|
to secured methods during the request will fail.</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>The <literal><port-mappings></literal> Element</title>
|
|
<para> By default, an instance of <classname>PortMapperImpl</classname> will be added to
|
|
the configuration for use in redirecting to secure and insecure URLs. This element
|
|
can optionally be used to override the default mappings which that class defines.
|
|
Each child <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>
|
|
</section>
|
|
<section xml:id="nsa-form-login">
|
|
<title>The <literal><form-login></literal> Element</title>
|
|
<para> Used to add an <classname>UsernamePasswordAuthenticationFilter</classname> to the
|
|
filter stack and an <classname>LoginUrlAuthenticationEntryPoint</classname> to the
|
|
application context to provide authentication on demand. This will always take
|
|
precedence over other namespace-created entry points. If no attributes are supplied,
|
|
a login page will be generated automatically at the URL "/spring-security-login" <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>
|
|
</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
|
|
"/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>
|
|
</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
|
|
default value is "/" (the application root). A user will be taken to this URL
|
|
after logging in, provided they were not asked to login while attempting to
|
|
access a secured resource, when they will be taken to the originally requested
|
|
URL. </para>
|
|
</section>
|
|
<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
|
|
login page. Maps to the <literal>alwaysUseDefaultTargetUrl</literal> property of
|
|
<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
|
|
"/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>
|
|
</section>
|
|
<section>
|
|
<title><literal>authentication-success-handler-ref</literal></title>
|
|
<para>This can be used as an alternative to <literal>default-target-url</literal>
|
|
and <literal>always-use-default-target</literal>, giving you full control over
|
|
the navigation flow after a successful authentication. The value should be he
|
|
name of an <interfacename>AuthenticationSuccessHandler</interfacename> bean in
|
|
the application context. </para>
|
|
</section>
|
|
<section>
|
|
<title><literal>authentication-failure-handler-ref</literal></title>
|
|
<para>Can be used as an alternative to
|
|
<literal>authentication-failure-url</literal>, giving you full control over the
|
|
navigation flow after an authentication failure. The value should be he name of
|
|
an <interfacename>AuthenticationFailureHandler</interfacename> bean in the
|
|
application context. </para>
|
|
</section>
|
|
</section>
|
|
<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
|
|
latter will only be used as the configuration entry point if form-based login is not
|
|
enabled. </para>
|
|
</section>
|
|
<section xml:id="nsa-remember-me">
|
|
<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>
|
|
<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>
|
|
</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>
|
|
</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
|
|
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>
|
|
</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
|
|
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>
|
|
</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
|
|
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
|
|
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>
|
|
</section>
|
|
</section>
|
|
<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>
|
|
<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
|
|
authenticates and a new session started. If set to "none" no change will be
|
|
made. "newSession" will create a new empty session. "migrateSession" will create
|
|
a new session and copy the session attributes to the new session. Defaults to
|
|
"migrateSession".</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>
|
|
</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>
|
|
<section>
|
|
<title>The <literal>max-sessions</literal> attribute</title>
|
|
<para>Maps to the <literal>maximumSessions</literal> property of
|
|
<classname>ConcurrentSessionControlStrategy</classname>.</para>
|
|
</section>
|
|
<section>
|
|
<title>The <literal>expired-url</literal> attribute</title>
|
|
<para> The URL a user will be redirected to if they attempt to use a session which
|
|
has been "expired" by the concurrent session controller because the user has
|
|
exceeded the number of allowed sessions and has logged in again elsewhere.
|
|
Should be set unless <literal>exception-if-maximum-exceeded</literal> is set. If
|
|
no value is supplied, an expiry message will just be written directly back to
|
|
the response. </para>
|
|
</section>
|
|
<section>
|
|
<title>The <literal>error-if-maximum-exceeded</literal> attribute</title>
|
|
<para>If set to "true" a
|
|
<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>
|
|
<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>
|
|
<para> It can also be useful to have a reference to the internal session registry
|
|
for use in your own beans or an admin interface. You can expose the interal bean
|
|
using the <literal>session-registry-alias</literal> attribute, giving it a name
|
|
that you can use elsewhere in your configuration. </para>
|
|
</section>
|
|
</section>
|
|
<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>
|
|
</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
|
|
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>
|
|
<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>
|
|
</section>
|
|
<section>
|
|
<title>The <literal>user-service-ref</literal> attribute</title>
|
|
<para> Allows a specific <interfacename>UserDetailsService</interfacename> to be
|
|
used with X.509 in the case where multiple instances are configured. If not set,
|
|
an attempt will be made to locate a suitable instance automatically and use
|
|
that. </para>
|
|
</section>
|
|
</section>
|
|
<section xml:id="nsa-openid-login">
|
|
<title>The <literal><openid-login></literal> Element</title>
|
|
<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>
|
|
attribute, or will be located automatically in the application context. </para>
|
|
</section>
|
|
<section xml:id="nsa-logout">
|
|
<title>The <literal><logout></literal> Element</title>
|
|
<para> Adds a <classname>LogoutFilter</classname> to the filter stack. This is
|
|
configured with a <classname>SecurityContextLogoutHandler</classname>. </para>
|
|
<section>
|
|
<title>The <literal>logout-url</literal> attribute</title>
|
|
<para> The URL which will cause a logout (i.e. which will be processed by the
|
|
filter). Defaults to "/j_spring_security_logout". </para>
|
|
</section>
|
|
<section>
|
|
<title>The <literal>logout-success-url</literal> attribute</title>
|
|
<para> The destination URL which the user will be taken to after logging out.
|
|
Defaults to "/". </para>
|
|
</section>
|
|
<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>
|
|
</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
|
|
maintained by Spring Security. Full details can be found in the namespace
|
|
chapter.</para>
|
|
</section>
|
|
<section xml:id="nsa-request-cache">
|
|
<title>The <literal>request-cache</literal> Element</title>
|
|
<para>Sets the <interfacename>RequestCache</interfacename> instance which will be used
|
|
by the <classname>ExceptionTranslationFilter</classname> to store request
|
|
information before invoking an
|
|
<interfacename>AuthenticationEntryPoint</interfacename>. </para>
|
|
</section>
|
|
<section>
|
|
<title>The <literal><http-firewall></literal> Element</title>
|
|
<para>This is a top-level element which can be used to inject a custom implementation of
|
|
<interfacename>HttpFirewall</interfacename> into the
|
|
<classname>FilterChainProxy</classname> created by the namespace. The default
|
|
implementation should be suitable for most applications.</para>
|
|
</section>
|
|
</section>
|
|
<section xml:id="nsa-authentication">
|
|
<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
|
|
configured with a list of one or more
|
|
<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>
|
|
<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>
|
|
<para> The element also exposes an <literal>erase-credentials</literal> attribute which
|
|
maps to the <literal>eraseCredentialsAfterAuthentication</literal> property of the
|
|
<classname>ProviderManager</classname>. This is discussed in the <link
|
|
xlink:href="#core-services-erasing-credentials">Core Services</link> chapter.</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
|
|
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>
|
|
<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>
|
|
instance, potentially with an accompanying
|
|
<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>
|
|
<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[
|
|
<security:authentication-manager>
|
|
<security:authentication-provider ref="myAuthenticationProvider" />
|
|
</security:authentication-manager>
|
|
<bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider"/>
|
|
]]></programlisting></para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<section xml:id="nsa-method-security">
|
|
<title>Method Security</title>
|
|
<section xml:id="nsa-gms">
|
|
<title>The <literal><global-method-security></literal> Element</title>
|
|
<para> This element is the primary means of adding support for securing methods on
|
|
Spring Security beans. Methods can be secured by the use of annotations (defined at
|
|
the interface or class level) or by defining a set of pointcuts as child elements,
|
|
using AspectJ syntax. </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>
|
|
<section>
|
|
<title>The <literal>secured-annotations</literal> and
|
|
<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
|
|
annotations. </para>
|
|
</section>
|
|
<section>
|
|
<title>Securing Methods using <literal><protect-pointcut></literal></title>
|
|
<para> Rather than defining security attributes on an individual method or class
|
|
basis using the <literal>@Secured</literal> annotation, you can define
|
|
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>
|
|
</itemizedlist> You can find an example in the <link
|
|
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>
|
|
</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
|
|
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
|
|
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>
|
|
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>
|
|
<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 <literal>id</literal> of the
|
|
<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
|
|
authentication providers, it must be included as a child of the
|
|
<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>
|
|
</section>
|
|
<section>
|
|
<title>The <literal>user-search-base</literal> and
|
|
<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>
|
|
</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>
|
|
<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
|
|
"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".
|
|
Similarly <literal>role-prefix</literal> maps to
|
|
<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>
|
|
</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>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</appendix>
|