This appendix provides a reference to the elements available in the security namespace and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document). If you haven't used the namespace before, please read the introductory chapter on namespace configuration, as this is intended as a supplement to the information there. Using a good quality XML editor while editing a configuration based on the schema is recommended as this will provide contextual information on which elements and attributes are available as well as comments explaining their purpose. The namespace is written in RELAX NG Compact format and later converted into an XSD schema. If you are familiar with this format, you may wish to examine the schema file directly.
Enables Spring Security debugging infrastructure. This will provide human-readable (multi-line) debugging information to monitor requests coming into the security filters. This may include sensitive information, such as request parameters or headers, and should only be used in a development environment.
If you use an <http> element within your application, a
FilterChainProxy bean named "springSecurityFilterChain" is
created and the configuration within the element is used to build a filter chain within
FilterChainProxy. As of Spring Security 3.1, additional
http elements can be used to add extra filter chains [25]. Some core filters are always created in a filter chain and others will be
added to the stack depending on the attributes and child elements which are present. The
positions of the standard filters are fixed (see the
filter order table in the namespace introduction), removing a common source of
errors with previous versions of the framework when users had to configure the filter
chain explicitly in the FilterChainProxy bean. You can, of course,
still do this if you need full control of the configuration.
All filters which require a reference to the
AuthenticationManager will be automatically injected with
the internal instance created by the namespace configuration (see the introductory chapter for more on the
AuthenticationManager).
Each <http> namespace block always creates an
SecurityContextPersistenceFilter, an
ExceptionTranslationFilter and a
FilterSecurityInterceptor. These are fixed and cannot be replaced
with alternatives.
The attributes on the <http> element control some of the
properties on the core filters.
Optional attribute specifying the ID of the
AccessDecisionManager implementation which should
be used for authorizing HTTP requests. By default an
AffirmativeBased implementation is used for with a
RoleVoter and an
AuthenticatedVoter.
Deprecated in favour of the access-denied-handler child element.
A reference to the AuthenticationManager used for the
FilterChain created by this http element.
Automatically registers a login form, BASIC authentication, logout services. If set to "true", all of these capabilities are added (although you can still customize the configuration of each by providing the respective element). If unspecified, defaults to "false". Use of this attribute is not recommended. Use explicit configuration elements instead to avoid confusion.
Controls the eagerness with which an HTTP session is created by Spring Security classes. Options include:
always - Spring Security will proactively create a session if one
does not exist.
ifRequired - Spring Security will only create a session only if one
is required (default value).
never - Spring Security will never create a session, but will
make use of one if the application does.stateless - Spring Security will not create a session and ignore the
session for obtaining a Spring Authentication.
Prevents session IDs from being appended to URLs in the application. Clients
must use cookies if this attribute is set to true. The default is
false.
Normally the AuthenticationEntryPoint used
will be set depending on which authentication mechanisms have been configured.
This attribute allows this behaviour to be overridden by defining a customized
AuthenticationEntryPoint bean which will start
the authentication process.
If available, runs the request as the Subject acquired from
the JaasAuthenticationToken which is implemented by
adding a JaasApiIntegrationFilter bean to the stack.
Defaults to false.
Corresponds to the observeOncePerRequest property of
FilterSecurityInterceptor. Defaults to true.
Deprecated in favor of request-matcher.
Defining a pattern for the http element controls the requests which will be filtered through the list of filters which it defines. The interpretation is dependent on the configured request-matcher. If no pattern is defined, all requests will be matched, so the most specific patterns should be declared first.
Sets the realm name used for basic authentication (if enabled). Corresponds
to the realmName property on
BasicAuthenticationEntryPoint.
Defines the RequestMatcher strategy used in
the FilterChainProxy and the beans created by the
intercept-url to match incoming requests. Options are
currently ant, regex and
ciRegex, for ant, regular-expression and case-insensitive
regular-expression repsectively. A separate instance is created for each
intercept-url element using its
pattern and
method attributes. Ant paths
are matched using an AntPathRequestMatcher and regular expressions
are matched using a RegexRequestMatcher. See the Javadoc
for these classes for more details on exactly how the matching is preformed. Ant
paths are the default strategy.
A referenece to a bean that implements RequestMatcher that
will determine if this FilterChain should be used. This is a more
powerful alternative to pattern.
A request pattern can be mapped to an empty filter chain, by setting this
attribute to none. No security will be applied and none of
Spring Security's features will be available.
Allows injection of a custom
SecurityContextRepository into the
SecurityContextPersistenceFilter.
Provides versions of HttpServletRequest security methods
such as isUserInRole() and getPrincipal()
which are implemented by adding a
SecurityContextHolderAwareRequestFilter bean to the
stack. Defaults to true.
Enables EL-expressions in the access attribute, as
described in the chapter on expression-based
access-control.
This element allows you to set the errorPage property for the
default AccessDeniedHandler used by the
ExceptionTranslationFilter, using the
error-page attribute, or
to supply your own implementation using the
ref attribute. This is discussed
in more detail in the section on the
ExceptionTranslationFilter.
This element allows for configuring additional (security) headers to be send with the response. It enables easy configuration for several headers and also allows for setting custom headers through the header element.
Cache-Control and Pragma - Can be set using the
cache-control element. This ensures that the
browser does not cache your secured pages.Strict-Transport-Security - Can be set using the
hsts element. This ensures that the
browser automatically requests HTTPS for future requests.X-Frame-Options - Can be set using the
frame-options element. The
X-Frame-Options
header can be used to prevent clickjacking attacks.X-XSS-Protection - Can be set using the
xss-protection element.
The X-XSS-Protection
header can be used by browser to do basic control.X-Content-Type-Options - Can be set using the
content-type-options element. The
<a>X-Content-Type-Options</a>
header prevents Internet Explorer from MIME-sniffing a response away from the declared
content-type. This also applies to Google Chrome, when downloading extensions.
Adds Cache-Control and Pragma headers to ensure that the
browser does not cache your secured pages.
When enabled adds the Strict-Transport-Security header to the response for any secure request. This allows the server to instruct browsers to automatically use HTTPS for future requests.
Specifies the maximum ammount of time the host should be considered a Known HSTS Host. Default one year.
When enabled adds the X-Frame-Options header to the response, this allows newer browsers to do some security checks and prevent clickjacking attacks.
DENY The page cannot be displayed in a frame, regardless of
the site attempting to do so. This is the default when frame-options-policy is specified.SAMEORIGIN The page can only be displayed in a frame on the
same origin as the page itselfALLOW-FROM origin
The page can only be displayed in a frame on the specified origin.
In other words, if you specify DENY, not only will attempts to load the page in a frame fail when loaded from other sites, attempts to do so will fail when loaded from the same site. On the other hand, if you specify SAMEORIGIN, you can still use the page in a frame as long as the site including it in a frame it is the same as the one serving the page.
Select the AllowFromStrategy to use when using the ALLOW-FROM policy.
static Use a single static ALLOW-FROM value. The value can be set
through the value attribute.
regexp Use a regelur expression to validate incoming requests and
if they are allowed. The regular expression can be set through the value
attribute. The request parameter used to retrieve the value to validate can be specified
using the from-parameter.
whitelistA comma-seperated list containing the allowed domains.
The comma-seperated list can be set through the value
attribute. The request parameter used to retrieve the value to validate can be specified
using the from-parameter.
Instead of using one of the predefined strategies it is also possible to use a custom AllowFromStrategy.
The reference to this bean can be specified through this ref attribute.
The value to use when ALLOW-FROM is used a strategy.
Adds the <a>X-XSS-Protection header</a> to the response to assist in protecting against <a>reflected / “Type-1” Cross-Site Scripting (XSS)</a> attacks. This is in no-way a full protection to XSS attacks!
Enable or Disable <a>reflected / “Type-1” Cross-Site Scripting (XSS)</a> protection.
When true and xss-protection-enabled is true, adds mode=block to the header. This indicates to the browser that the page should not be loaded at all. When false and xss-protection-enabled is true, the page will still be rendered when an reflected attack is detected but the response will be modified to protect against the attack. Note that there are sometimes ways of bypassing this mode which can often times make blocking the page more desirable.
Add the X-Content-Type-Options header with the value of nosniff to the response. This <a>disables MIME-sniffing</a> for IE8+ and Chrome extensions.
Add additional headers to the response, both the name and value need to be specified.
Adds an AnonymousAuthenticationFilter to the stack and an
AnonymousAuthenticationProvider. Required if you are using
the IS_AUTHENTICATED_ANONYMOUSLY attribute.
With the default namespace setup, the anonymous "authentication" facility is automatically enabled. You can disable it using this property.
The granted authority that should be assigned to the anonymous request. Commonly this is used
to assign the anonymous request particular roles, which can subsequently be used in authorization
decisions. If unset, defaults to ROLE_ANONYMOUS.
The key shared between the provider and filter. This generally does not need to be set. If unset, it will default to a secure randomly generated value. This means setting this value can improve startup time when using the anonymous functionality since secure random values can take a while to be generated.
This element will add <a>CSRF</a> to the application. It also updates the default RequestCache to only replay "GET" requests upon successful authentication.
This element is used to add a filter to the filter chain. It doesn't create any
additional beans but is used to select a bean of type
javax.servlet.Filter which is already defined in the
application 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.
The filter immediately after which the custom-filter should be placed in the chain. This feature will only be needed by advanced users who wish to mix their own filters into the security filter chain and have some knowledge of the standard Spring Security filters. The filter names map to specific Spring Security implementation filters.
The explicit position at which the custom-filter should be placed in the chain. Use if you are replacing a standard filter.
Defines the SecurityExpressionHandler instance which will be used if
expression-based access-control is enabled. A default implementation (with no ACL support) will be used
if not supplied.
Used to add an UsernamePasswordAuthenticationFilter to the
filter stack and an LoginUrlAuthenticationEntryPoint to the
application context to provide authentication on demand. This will always take
precedence over other namespace-created entry points. If no attributes are supplied,
a login page will be generated automatically at the URL "/spring_security_login" [26] The behaviour can be customized using the
<form-login> Attributes.
If set to true, the user will always start at the value given by
default-target-url, regardless
of how they arrived at the login page. Maps to the alwaysUseDefaultTargetUrl
property of UsernamePasswordAuthenticationFilter. Default value is
false.
Reference to an AuthenticationDetailsSource which will be used
by the authentication filter
Can be used as an alternative to
authentication-failure-url,
giving you full control over the navigation flow after an authentication failure. The value
should be he name of an AuthenticationFailureHandler bean in the
application context.
Maps to the authenticationFailureUrl property of
UsernamePasswordAuthenticationFilter. Defines the URL the
browser will be redirected to on login failure. Defaults to
/spring_security_login?login_error, which will be automatically handled by
the automatic login page generator, re-rendering the login page with an error message.
This can be used as an alternative to
default-target-url
and always-use-default-target,
giving you full control over the navigation flow after a successful authentication. The value
should be the name of an AuthenticationSuccessHandler bean in
the application context. By default, an implementation of
SavedRequestAwareAuthenticationSuccessHandler is used and
injected with the default-target-url
.
Maps to the defaultTargetUrl property of
UsernamePasswordAuthenticationFilter. If not set, the
default value is "/" (the application root). A user will be taken to this URL
after logging in, provided they were not asked to login while attempting to
access a secured resource, when they will be taken to the originally requested
URL.
The URL that should be used to render the login page. Maps to the
loginFormUrl property of the
LoginUrlAuthenticationEntryPoint. Defaults to
"/spring_security_login".
Maps to the filterProcessesUrl property of
UsernamePasswordAuthenticationFilter. The default value
is "/j_spring_security_check".
The name of the request parameter which contains the password. Defaults to "j_password".
Adds a BasicAuthenticationFilter and
BasicAuthenticationEntryPoint to the configuration. The
latter will only be used as the configuration entry point if form-based login is not
enabled.
This is a top-level element which can be used to inject a custom implementation of
HttpFirewall into the
FilterChainProxy created by the namespace. The default
implementation should be suitable for most applications.
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 FilterInvocationSecurityMetadataSource used by
the FilterSecurityInterceptor. It is also responsible for
configuring a ChannelProcessingFilter 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.
Lists the access attributes which will be stored in the
FilterInvocationSecurityMetadataSource for the
defined URL pattern/method combination. This should be a comma-separated list of
the security configuration attributes (such as role names).
Can only take the value “none”. This will cause any matching
request to bypass the Spring Security filter chain entirely. None of the rest of
the <http> 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.
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.
The pattern which defines the URL path. The content will depend on the
request-matcher attribute from the containing http element,
so will default to ant path syntax.
Can be “http” or “https” depending on whether a
particular URL pattern should be accessed over HTTP or HTTPS respectively.
Alternatively the value “any” can be used when there is no
preference. If this attribute is present on any
<intercept-url> element, then a
ChannelProcessingFilter will be added to the filter
stack and its additional dependencies added to the application
context.
If a <port-mappings> configuration is added, this
will be used to by the SecureChannelProcessor and
InsecureChannelProcessor beans to determine the ports
used for redirecting to HTTP/HTTPS.
Adds a J2eePreAuthenticatedProcessingFilter to the filter chain to provide integration with container authentication.
Adds a LogoutFilter to the filter stack. This is
configured with a SecurityContextLogoutHandler.
A comma-separated list of the names of cookies which should be deleted when the user logs out.
Maps to the invalidateHttpSession of the
SecurityContextLogoutHandler. Defaults to "true", so the
session will be invalidated on logout.
The destination URL which the user will be taken to after logging out. Defaults to "/".
Setting this attribute will inject the SessionManagementFilter
with a SimpleRedirectInvalidSessionStrategy configured with
the attribute value. When an invalid session ID is submitted, the strategy will be invoked,
redirecting to the configured URL.
The URL which will cause a logout (i.e. which will be processed by the filter). Defaults to "/j_spring_security_logout".
Similar to <form-login> and has the same attributes. The
default value for login-processing-url is
"/j_spring_openid_security_check". An
OpenIDAuthenticationFilter and
OpenIDAuthenticationProvider will be registered. The latter
requires a reference to a UserDetailsService. Again,
this can be specified by id, using the user-service-ref
attribute, or will be located automatically in the application context.
Whether the user should always be redirected to the default-target-url after login.
Reference to an AuthenticationDetailsSource which will be used by the authentication filter
Reference to an AuthenticationFailureHandler bean which should be used to handle a failed authentication request. Should not be used in combination with authentication-failure-url as the implementation should always deal with navigation to the subsequent destination
The URL for the login failure page. If no login failure URL is specified, Spring Security will automatically create a failure login URL at /spring_security_login?login_error and a corresponding filter to render that login failure URL when requested.
Reference to an AuthenticationSuccessHandler bean which should be used to handle a successful authentication request. Should not be used in combination with default-target-url (or always-use-default-target) as the implementation should always deal with navigation to the subsequent destination
The URL that will be redirected to after successful authentication, if the user's previous action could not be resumed. This generally happens if the user visits a login page without having first requested a secured operation that triggers authentication. If unspecified, defaults to the root of the application.
The URL for the login page. If no login URL is specified, Spring Security will automatically create a login URL at /spring_security_login and a corresponding filter to render that login URL when requested.
The URL that the login form is posted to. If unspecified, it defaults to /j_spring_security_check.
The name of the request parameter which contains the password. Defaults to "j_password".
The attribute-exchange element defines the list of
attributes which should be requested from the identity provider. An example can be found
in the OpenID Support section of the namespace configuration
chapter. More than one can be used, in which case each must have an identifier-match
attribute, containing a regular expression which is matched against the supplied
OpenID identifier. This allows different attribute lists to be fetched from
different providers (Google, Yahoo etc).
Attributes used when making an OpenID AX Fetch Request
Specifies the number of attributes that you wish to get back. For example, return 3 emails. The default value is 1.
Specifies if this attribute is required to the OP, but does not error out if the OP does not return the attribute. Default is false.
By default, an instance of PortMapperImpl will be added to
the configuration for use in redirecting to secure and insecure URLs. This element
can optionally be used to override the default mappings which that class defines.
Each child <port-mapping> element defines a pair of
HTTP:HTTPS ports. The default mappings are 80:443 and 8080:8443. An example of
overriding these can be found in the namespace introduction.
Provides a method to map http ports to https ports when forcing a redirect.
Adds the RememberMeAuthenticationFilter to the stack. This
in turn will be configured with either a
TokenBasedRememberMeServices, a
PersistentTokenBasedRememberMeServices or a user-specified
bean implementing RememberMeServices depending on the
attribute settings.
Sets the authenticationSuccessHandler property on the
RememberMeAuthenticationFilter if custom navigation is required.
The value should be the name of a AuthenticationSuccessHandler
bean in the application context.
A reference to a DataSource bean. If this is set,
PersistentTokenBasedRememberMeServices will be used and configured with a
JdbcTokenRepositoryImpl instance.
The name of the request parameter which toggles remember-me authentication. Defaults to "_spring_security_remember_me".
Maps to the "parameter" property of AbstractRememberMeServices.
Maps to the "key" property of
AbstractRememberMeServices. Should be set to a unique
value to ensure that remember-me cookies are only valid within the one
application [27]. If this is not set a secure random value will be generated. Since generating secure
random values can take a while, setting this value explicitly can help improve startup times when
using the remember me functionality.
Exports the internally defined RememberMeServices as a bean alias,
allowing it to be used by other beans in the application context.
Allows complete control of the
RememberMeServices implementation that will be
used by the filter. The value should be the id of a bean in the application
context which implements this interface. Should also implement
LogoutHandler if a logout filter is in use.
Configures a PersistentTokenBasedRememberMeServices
but allows the use of a custom
PersistentTokenRepository bean.
Maps to the tokenValiditySeconds property of
AbstractRememberMeServices. Specifies the period in
seconds for which the remember-me cookie should be valid. By default it will be
valid for 14 days.
It is recommended that remember-me cookies are only submitted over HTTPS and thus should
be flagged as “secure”. By default, a secure cookie will be used if the
connection over which the login request is made is secure (as it should be).
If you set this property to false, secure cookies will not be used.
Setting it to true will always set the secure flag on the cookie.
This attribute maps to the useSecureCookie property of
AbstractRememberMeServices.
The remember-me services implementations require access to a
UserDetailsService, so there has to be one
defined in the application context. If there is only one, it will be selected
and used automatically by the namespace configuration. If there are multiple
instances, you can specify a bean id explicitly using this attribute.
Sets the RequestCache instance which will be used
by the ExceptionTranslationFilter to store request
information before invoking an
AuthenticationEntryPoint.
Session-management related functionality is implemented by the addition of a
SessionManagementFilter to the filter stack.
Setting this attribute will inject the SessionManagementFilter
with a SimpleRedirectInvalidSessionStrategy configured with
the attribute value. When an invalid session ID is submitted, the strategy will be invoked,
redirecting to the configured URL.
Defines the URL of the error page which should be shown when the SessionAuthenticationStrategy raises an exception. If not set, an unauthorized (402) error code will be returned to the client. Note that this attribute doesn't apply if the error occurs during a form-based login, where the URL for authentication failure will take precedence.
Allows injection of the SessionAuthenticationStrategy instance used by the SessionManagementFilter
Indicates how session fixation protection will be applied when a user authenticates. If set to "none", no protection will be applied. "newSession" will create a new empty session, with only Spring Security-related attributes migrated. "migrateSession" will create a new session and copy all session attributes to the new session. In Servlet 3.1 (Java EE 7) and newer containers, specifying "changeSessionId" will keep the existing session and use the container-supplied session fixation protection (HttpServletRequest#changeSessionId()). Defaults to "changeSessionId" in Servlet 3.1 and newer containers, "migrateSession" in older containers. Throws an exception if "changeSessionId" is used in older containers.
If session fixation protection is enabled, the
SessionManagementFilter is injected with an appropriately
configured DefaultSessionAuthenticationStrategy. See the
Javadoc for this class for more details.
Adds support for concurrent session control, allowing limits to be placed on the
number of active sessions a user can have. A
ConcurrentSessionFilter will be created, and a
ConcurrentSessionControlAuthenticationStrategy will be used with the
SessionManagementFilter. If a form-login
element has been declared, the strategy object will also be injected into the
created authentication filter. An instance of
SessionRegistry (a
SessionRegistryImpl instance unless the user wishes to use a
custom bean) will be created for use by the strategy.
If set to "true" a
SessionAuthenticationException will be raised
when a user attempts to exceed the maximum allowed number of sessions. The
default behaviour is to expire the original session.
The URL a user will be redirected to if they attempt to use a session which
has been "expired" by the concurrent session controller because the user has
exceeded the number of allowed sessions and has logged in again elsewhere.
Should be set unless exception-if-maximum-exceeded is set. If
no value is supplied, an expiry message will just be written directly back to
the response.
Maps to the maximumSessions property of
ConcurrentSessionControlAuthenticationStrategy.
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 internal bean
using the session-registry-alias attribute, giving it a name
that you can use elsewhere in your configuration.
Adds support for X.509 authentication. An
X509AuthenticationFilter will be added to the stack and an
Http403ForbiddenEntryPoint bean will be created. The latter
will only be used if no other authentication mechanisms are in use (its only
functionality is to return an HTTP 403 error code). A
PreAuthenticatedAuthenticationProvider will also be created
which delegates the loading of user authorities to a
UserDetailsService.
Defines a regular expression which will be used to extract the username from
the certificate (for use with the
UserDetailsService).
Used to explicitly configure a FilterChainProxy instance with a FilterChainMap
Superseded by the request-matcher attribute
Used within to define a specific URL pattern and the list of filters which apply to the URLs matching that pattern. When multiple filter-chain elements are assembled in a list in order to configure a FilterChainProxy, the most specific patterns must be placed at the top of the list, with most general ones at the bottom.
A comma separated list of references to Spring beans that implement
Filter. The value "none" means that no
Filter's should be used for this
FilterChain.
A-pattern that creates RequestMatcher in combination with the request-matcher
Deprecated synonym for filter-security-metadata-source
Superseded by request-matcher
Supersedes the 'path-type' attribute. Defines the strategy use for matching incoming requests. Currently the options are 'ant' (for ant path patterns), 'regex' for regular expressions and 'ciRegex' for case-insensitive regular expressions.
Enables the use of expressions in the 'access' attributes in <intercept-url> elements rather than the traditional list of configuration attributes. Defaults to 'false'. If enabled, each attribute should contain a single boolean expression. If the expression evaluates to 'true', access will be granted.
Used to explicitly configure a FilterSecurityMetadataSource bean for use with a FilterSecurityInterceptor. Usually only needed if you are configuring a FilterChainProxy explicitly, rather than using the <http> element. The intercept-url elements used should only contain pattern, method and access attributes. Any others will result in a configuration error.
Superseded by request-matcher
Supersedes the 'path-type' attribute. Defines the strategy use for matching incoming requests. Currently the options are 'ant' (for ant path patterns), 'regex' for regular expressions and 'ciRegex' for case-insensitive regular expressions.
Enables the use of expressions in the 'access' attributes in <intercept-url> elements rather than the traditional list of configuration attributes. Defaults to 'false'. If enabled, each attribute should contain a single boolean expression. If the expression evaluates to 'true', access will be granted.
Before Spring Security 3.0, an AuthenticationManager
was automatically registered internally. Now you must register one explicitly using the
<authentication-manager> element. This creates an instance of
Spring Security's ProviderManager class, which needs to be
configured with a list of one or more
AuthenticationProvider instances. These can either be
created using syntax elements provided by the namespace, or they can be standard bean
definitions, marked for addition to the list using the
authentication-provider element.
Every Spring Security application which uses the namespace must have include this
element somewhere. It is responsible for registering the
AuthenticationManager which provides authentication
services to the application. All elements
which create AuthenticationProvider instances should
be children of this element.
This attribute allows you to define an alias name for the internal instance for use in your own configuration. Its use is described in the namespace introduction.
If set to true, the AuthenticationManger will attempt to clear any credentials data in the
returned Authentication object, once the user has been authenticated. Literally it maps to
the eraseCredentialsAfterAuthentication property of the
ProviderManager. This is discussed in the Core Services chapter.
Unless used with a ref attribute, this element is
shorthand for configuring a DaoAuthenticationProvider.
DaoAuthenticationProvider loads user information from a
UserDetailsService and compares the
username/password combination with the values supplied at login. The
UserDetailsService instance can be defined either
by using an available namespace element (jdbc-user-service or
by using the user-service-ref attribute to point to a bean
defined elsewhere in the application context). You can find examples of these
variations in the namespace
introduction.
Defines a reference to a Spring bean that implements AuthenticationProvider
.
If you have written your own
AuthenticationProvider implementation (or want to
configure one of Spring Security's own implementations as a traditional bean for
some reason, then you can use the following syntax to add it to the internal
ProviderManager's list:
<security:authentication-manager> <security:authentication-provider ref="myAuthenticationProvider" /> </security:authentication-manager> <bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider"/>
Causes creation of a JDBC-based UserDetailsService.
An SQL statement to query for a user's granted authorities given a username.
The default is
select username, authority from authorities where username = ?
An SQL statement to query user's group authorities given a username.
The default is
select g.id, g.group_name, ga.authority from groups g, group_members gm, group_authorities ga where gm.username = ? and g.id = ga.group_id and g.id = gm.group_id
A non-empty string prefix that will be added to role strings loaded from persistent storage (default is "ROLE_"). Use the value "none" for no prefix in cases where the default is non-empty.
Authentication providers can optionally be configured to use a password
encoder as described in the namespace introduction. This will result in the bean being injected
with the appropriate PasswordEncoder
instance, potentially with an accompanying
SaltSource bean to provide salt values for
hashing.
Defines the hashing algorithm used on user passwords. We recommend strongly against using MD4, as it is a very weak hashing algorithm.
Password salting strategy. A system-wide constant or a property from the UserDetails object can be used.
Creates an in-memory UserDetailsService from a properties file or a list of "user" child elements. Usernames are converted to lower-case internally to allow for case-insensitive lookups, so this should not be used if case-sensitivity is required.
Represents a user in the application.
One of more authorities granted to the user. Separate authorities with a comma (but no space). For example, "ROLE_USER,ROLE_ADMINISTRATOR"
The password assigned to the user. This may be hashed if the corresponding authentication provider supports hashing (remember to set the "hash" attribute of the "user-service" element). This attribute be omitted in the case where the data will not be used for authentication, but only for accessing authorities. If omitted, the namespace will generate a random value, preventing its accidental use for authentication. Cannot be empty.
This element is the primary means of adding support for securing methods on Spring Security beans. Methods can be secured by the use of annotations (defined at the interface or class level) or by defining a set of pointcuts as child elements, using AspectJ syntax.
Method security uses the same AccessDecisionManager
configuration as web security, but this can be overridden using this attribute. By default
an AffirmativeBased implementation is used for with a RoleVoter and an AuthenticatedVoter.
A reference to an AuthenticationManager
that should be used for method security.
Specifies whether JSR-250 style attributes are to be used (for example "RolesAllowed"). This
will require the javax.annotation.security classes on the classpath. Setting this to true also
adds a Jsr250Voter to the
AccessDecisionManager, so you need to make sure you do this if
you are using a custom implementation and want to use these annotations.
An external MethodSecurityMetadataSource
instance can be supplied which will take priority over other sources
(such as the default annotations).
This attribute can be set to “aspectj” to specify that AspectJ
should be used instead of the default Spring AOP. Secured methods must be woven
with the AnnotationSecurityAspect from the
spring-security-aspects module.
Specifies whether the use of Spring Security's pre and post invocation annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) should be enabled for this application context. Defaults to "disabled".
A reference to an optional RunAsManager implementation which
will be used by the configured MethodSecurityInterceptor
This element can be used to decorate an
AfterInvocationProvider for use by the security
interceptor maintained by the <global-method-security>
namespace. You can define zero or more of these within the
global-method-security element, each with a
ref attribute pointing to an
AfterInvocationProvider bean instance within your
application context.
Allows the default expression-based mechanism for handling Spring Security's pre and post invocation annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) to be replace entirely. Only applies if these annotations are enabled.
Defines the PrePostInvocationAttributeFactory instance which is used to generate pre and post invocation metadata from the annotated methods.
Customizes the PostInvocationAdviceProvider with the ref as the
PostInvocationAuthorizationAdvice for the <pre-post-annotation-handling>
element.
Customizes the PreInvocationAuthorizationAdviceVoter with the ref as the
PreInvocationAuthorizationAdviceVoter for the
<pre-post-annotation-handling> element.
Rather than defining security attributes on an individual method or class
basis using the @Secured annotation, you can define
cross-cutting security constraints across whole sets of methods and interfaces
in your service layer using the <protect-pointcut>
element. You can find an example in the namespace introduction.
Access configuration attributes list that applies to all methods matching the pointcut, e.g. "ROLE_A,ROLE_B"
Can be used inside a bean definition to add a security interceptor to the bean and set up access configuration attributes for the bean's methods
Creates a MethodSecurityMetadataSource instance
Enables the use of expressions in the 'access' attributes in <intercept-url> elements rather than the traditional list of configuration attributes. Defaults to 'false'. If enabled, each attribute should contain a single boolean expression. If the expression evaluates to 'true', access will be granted.
Defines a protected method and the access control configuration attributes that apply to it. We strongly advise you NOT to mix "protect" declarations with any services provided "global-method-security".
LDAP is covered in some details in its own chapter. We will expand on that here with some explanation of how the namespace options map to Spring beans. The LDAP implementation uses Spring LDAP extensively, so some familiarity with that project's API may be useful.
This element sets up a Spring LDAP
ContextSource for use by the other LDAP beans,
defining the location of the LDAP server and other information (such as a
username and password, if it doesn't allow anonymous access) for connecting to
it. It can also be used to create an embedded server for testing. Details of the
syntax for both options are covered in the LDAP
chapter. The actual ContextSource
implementation is DefaultSpringSecurityContextSource
which extends Spring LDAP's LdapContextSource class. The
manager-dn and manager-password attributes
map to the latter's userDn and password
properties respectively.
If you only have one server defined in your application context, the other
LDAP namespace-defined beans will use it automatically. Otherwise, you can give
the element an "id" attribute and refer to it from other namespace beans using
the server-ref attribute. This is actually the bean id of the
ContextSource instance, if you want to use it in other
traditional Spring beans.
Explicitly specifies an ldif file resource to load into an embedded LDAP server. The ldiff is should be a Spring resource pattern (i.e. classpath:init.ldiff). The default is classpath*:*.ldiff
Username (DN) of the "manager" user identity which will be used to authenticate to a (non-embedded) LDAP server. If omitted, anonymous access will be used.
Specifies an IP port number. Used to configure an embedded LDAP server, for example. The default value is 33389.
This element is shorthand for the creation of an
LdapAuthenticationProvider instance. By default this will
be configured with a BindAuthenticator instance and a
DefaultAuthoritiesPopulator. As with all namespace
authentication providers, it must be included as a child of the
authentication-provider element.
The LDAP attribute name which contains the role name which will be used within Spring
Security. Maps to the DefaultLdapAuthoritiesPopulator's
groupRoleAttribute property. Defaults to "cn".
Search base for group membership searches. Maps to the
DefaultLdapAuthoritiesPopulator's groupSearchBase
constructor argument. Defaults to "" (searching from the root).
Group search filter. Maps to the DefaultLdapAuthoritiesPopulator's
groupSearchFilter property. Defaults to (uniqueMember={0}).
The substituted parameter is the DN of the user.
A non-empty string prefix that will be added to role strings loaded from persistent.
Maps to the DefaultLdapAuthoritiesPopulator's
rolePrefix property. Defaults to "ROLE_". Use the value "none" for
no prefix in cases where the default is non-empty.
The optional server to use. If omitted, and a default LDAP server is registered (using <ldap-server> with no Id), that server will be used.
Allows explicit customization of the loaded user object by specifying a UserDetailsContextMapper bean which will be called with the context information from the user's directory entry
Allows the objectClass of the user entry to be specified. If set, the framework will attempt to load standard attributes for the defined class into the returned UserDetails object
If your users are at a fixed location in the directory (i.e. you can work
out the DN directly from the username without doing a directory search), you
can use this attribute to map directly to the DN. It maps directly to the
userDnPatterns property of
AbstractLdapAuthenticator. The value is a specific pattern
used to build the user's DN, for example "uid={0},ou=people". The key
"{0}" must be present and will be substituted with the username.
Search base for user searches. Defaults to "". Only used with a 'user-search-filter'.
If you need to perform a search to locate the user in the directory, then
you can set these attributes to control the search. The
BindAuthenticator will be configured with a
FilterBasedLdapUserSearch and the attribute values
map directly to the first two arguments of that bean's constructor. If these
attributes aren't set and no user-dn-pattern has been
supplied as an alternative, then the default search values of
user-search-filter="(uid={0})" and
user-search-base="" will be used.
The LDAP filter used to search for users (optional). For example "(uid={0})". The substituted parameter is the user's login name.
If you need to perform a search to locate the user in the directory, then
you can set these attributes to control the search. The
BindAuthenticator will be configured with a
FilterBasedLdapUserSearch and the attribute values
map directly to the first two arguments of that bean's constructor. If these
attributes aren't set and no user-dn-pattern has been
supplied as an alternative, then the default search values of
user-search-filter="(uid={0})" and
user-search-base="" will be used.
This is used as child element to <ldap-provider>
and switches the authentication strategy from
BindAuthenticator to
PasswordComparisonAuthenticator.
Defines the hashing algorithm used on user passwords. We recommend strongly against using MD4, as it is a very weak hashing algorithm.
This element configures an LDAP
UserDetailsService. The class used is
LdapUserDetailsService which is a combination of a
FilterBasedLdapUserSearch and a
DefaultLdapAuthoritiesPopulator. The attributes it supports
have the same usage as in <ldap-provider>.
The LDAP attribute name which contains the role name which will be used within Spring Security. Defaults to "cn".
Search base for group membership searches. Defaults to "" (searching from the root).
Group search filter. Defaults to (uniqueMember={0}). The substituted parameter is the DN of the user.
A non-empty string prefix that will be added to role strings loaded from persistent storage (e.g. "ROLE_"). Use the value "none" for no prefix in cases where the default is non-empty.
The optional server to use. If omitted, and a default LDAP server is registered (using <ldap-server> with no Id), that server will be used.
Allows explicit customization of the loaded user object by specifying a UserDetailsContextMapper bean which will be called with the context information from the user's directory entry
Allows the objectClass of the user entry to be specified. If set, the framework will attempt to load standard attributes for the defined class into the returned UserDetails object
Search base for user searches. Defaults to "". Only used with a 'user-search-filter'.
[25] See the introductory chapter for how to set
up the mapping from your web.xml
[26] This feature is really just provided for convenience and is not intended for
production (where a view technology will have been chosen and can be used to
render a customized login page). The class
DefaultLoginPageGeneratingFilter is responsible for
rendering the login page and will provide login forms for both normal form login
and/or OpenID if required.
[27] This doesn't affect the use of
PersistentTokenBasedRememberMeServices, where the
tokens are stored on the server side.