2045 lines
76 KiB
Plaintext
2045 lines
76 KiB
Plaintext
[[nsa-web]]
|
|
= Web Application Security
|
|
|
|
This section deals with the XML namespace elements and attributes that deal with the security of web applications.
|
|
|
|
[[nsa-debug]]
|
|
== <debug>
|
|
Enables Spring Security debugging infrastructure.
|
|
This element provides human-readable (multi-line) debugging information to monitor requests that come to the security filters.
|
|
This may include sensitive information (such as request parameters or headers) and should only be used in a development environment.
|
|
|
|
[[nsa-http]]
|
|
== <http>
|
|
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, you can use additional `http` elements to add extra filter chains. See the <<ns-web-xml,introductory chapter>> for how to set up the mapping from your `web.xml`.
|
|
Some core filters are always created in a filter chain and others are added to the stack depending on the attributes and child elements that are present.
|
|
The positions of the standard filters are fixed (see
|
|
xref:servlet/configuration/xml-namespace.adoc#filter-stack[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 still controle the order of the filters if you need full control of the configuration.
|
|
|
|
All filters that which require a reference to the xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] are automatically injected with the internal instance created by the namespace configuration.
|
|
|
|
Each `<http>` namespace block always creates an `SecurityContextPersistenceFilter`, an `ExceptionTranslationFilter`, and a `FilterSecurityInterceptor`.
|
|
These are fixed and cannot be replaced with alternatives.
|
|
|
|
|
|
[[nsa-http-attributes]]
|
|
=== <http> Attributes
|
|
The attributes on the `<http>` element control some of the properties on the core filters.
|
|
|
|
|
|
[[nsa-http-access-decision-manager-ref]]
|
|
`access-decision-manager-ref`::
|
|
Optional attribute specifying the ID of the `AccessDecisionManager` implementation that should be used for authorizing HTTP requests.
|
|
By default, an `AffirmativeBased` implementation is used for with a `RoleVoter` and an `AuthenticatedVoter`.
|
|
|
|
|
|
[[nsa-http-authentication-manager-ref]]
|
|
`authentication-manager-ref`::
|
|
A reference to the `AuthenticationManager` used for the `FilterChain` created by this http element.
|
|
|
|
|
|
[[nsa-http-auto-config]]
|
|
`auto-config`::
|
|
Automatically registers a login form, BASIC authentication, and logout services.
|
|
If set to `true`, all of these capabilities are added. (You can still customize the configuration of each by providing the respective element).
|
|
If unspecified, it defaults to `false`.
|
|
Use of this attribute is not recommended.
|
|
Instead, you should use explicit configuration elements to avoid confusion.
|
|
|
|
|
|
[[nsa-http-create-session]]
|
|
`create-session`::
|
|
Controls the eagerness with which an HTTP session is created by Spring Security classes.
|
|
Options include:
|
|
|
|
* `always`: Spring Security proactively creates a session if one does not exist.
|
|
* `ifRequired` (default): Spring Security creates a session only if one is required.
|
|
* `never`: Spring Security never creates a session, but it will make use of one if the application creates one.
|
|
* `stateless`: Spring Security does not create a session and ignores the session for obtaining a Spring `Authentication`.
|
|
|
|
[[nsa-http-disable-url-rewriting]]
|
|
`disable-url-rewriting`::
|
|
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 `true`.
|
|
|
|
|
|
[[nsa-http-entry-point-ref]]
|
|
`entry-point-ref`::
|
|
Normally, which `AuthenticationEntryPoint` is used depends on which authentication mechanisms have been configured.
|
|
This attribute lets this behavior be overridden by defining a customized `AuthenticationEntryPoint` bean, which starts the authentication process.
|
|
|
|
|
|
[[nsa-http-jaas-api-provision]]
|
|
`jaas-api-provision`::
|
|
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`.
|
|
|
|
|
|
[[nsa-http-name]]
|
|
`name`::
|
|
A bean identifier used for referring to the bean elsewhere in the context.
|
|
|
|
|
|
[[nsa-http-once-per-request]]
|
|
`once-per-request`::
|
|
Corresponds to the `observeOncePerRequest` property of `FilterSecurityInterceptor`.
|
|
Defaults to `true`.
|
|
|
|
|
|
[[nsa-http-pattern]]
|
|
`pattern`::
|
|
Defines a pattern for the <<nsa-http,http>> element controls the requests which are filtered through the list of filters that it defines.
|
|
The interpretation is dependent on the configured <<nsa-http-request-matcher,request-matcher>>.
|
|
If no pattern is defined, all requests are matched, so the most specific patterns should be declared first.
|
|
|
|
|
|
[[nsa-http-realm]]
|
|
`realm`::
|
|
Sets the realm name used for basic authentication (if enabled).
|
|
Corresponds to the `realmName` property on `BasicAuthenticationEntryPoint`.
|
|
|
|
|
|
[[nsa-http-request-matcher]]
|
|
`request-matcher`::
|
|
Defines the `RequestMatcher` strategy used in the `FilterChainProxy` and the beans created by the `intercept-url` to match incoming requests.
|
|
The current options are
|
|
|
|
* `mvc`: Spring MVC
|
|
* `ant` (default): Ant
|
|
* `regex`: Regular expression
|
|
* `ciRegex`: Case-insensitive regular-expression respectively.
|
|
A separate instance is created for each <<nsa-intercept-url,`intercept-url`>> element, by using its <<nsa-intercept-url-pattern,`pattern`>>, <<nsa-intercept-url-method,`method`>>, and <<nsa-intercept-url-servlet-path,`servlet-path`>> attributes.
|
|
Ant paths are matched by using an `AntPathRequestMatcher`. Regular expressions are matched by using a `RegexRequestMatcher`. For Spring MVC path matching, the `MvcRequestMatcher` is used.
|
|
See the Javadoc for these classes for more details on exactly how the matching is performed.
|
|
|
|
|
|
[[nsa-http-request-matcher-ref]]
|
|
`request-matcher-ref`::
|
|
A reference to a bean that implements `RequestMatcher`, which determines whenter this `FilterChain` should be used.
|
|
This is a more powerful alternative to <<nsa-http-pattern,`pattern`>>.
|
|
|
|
|
|
[[nsa-http-security]]
|
|
`security`::
|
|
A request pattern can be mapped to an empty filter chain by setting this attribute to `none`.
|
|
In that case, no security is applied and none of Spring Security's features are available.
|
|
|
|
|
|
[[nsa-http-security-context-repository-ref]]
|
|
`security-context-repository-ref`::
|
|
Allows injection of a custom `SecurityContextRepository` into the `SecurityContextPersistenceFilter`.
|
|
|
|
|
|
[[nsa-http-servlet-api-provision]]
|
|
`servlet-api-provision`::
|
|
Provides versions of `HttpServletRequest` security methods, such as `isUserInRole()` and `getPrincipal()`, which are implemented by adding a `SecurityContextHolderAwareRequestFilter` bean to the stack.
|
|
Default: `true`.
|
|
|
|
|
|
[[nsa-http-use-expressions]]
|
|
`use-expressions`::
|
|
Enables EL-expressions in the `access` attribute, as described in the chapter on xref:servlet/authorization/expression-based.adoc#el-access-web[expression-based access-control].
|
|
The default value is true.
|
|
|
|
|
|
[[nsa-http-children]]
|
|
=== Child Elements of <http>
|
|
|
|
The `<http>` element has the following child elements, which we describe later in this appendix:
|
|
|
|
* <<nsa-access-denied-handler,access-denied-handler>>
|
|
* <<nsa-anonymous,anonymous>>
|
|
* <<nsa-cors,cors>>
|
|
* <<nsa-csrf,csrf>>
|
|
* <<nsa-custom-filter,custom-filter>>
|
|
* <<nsa-expression-handler,expression-handler>>
|
|
* <<nsa-form-login,form-login>>
|
|
* <<nsa-headers,headers>>
|
|
* <<nsa-http-basic,http-basic>>
|
|
* <<nsa-intercept-url,intercept-url>>
|
|
* <<nsa-jee,jee>>
|
|
* <<nsa-logout,logout>>
|
|
* <<nsa-oauth2-client,oauth2-client>>
|
|
* <<nsa-oauth2-login,oauth2-login>>
|
|
* <<nsa-oauth2-resource-server,oauth2-resource-server>>
|
|
* <<nsa-openid-login,openid-login>>
|
|
* <<nsa-password-management,password-management>>
|
|
* <<nsa-port-mappings,port-mappings>>
|
|
* <<nsa-remember-me,remember-me>>
|
|
* <<nsa-request-cache,request-cache>>
|
|
* <<nsa-session-management,session-management>>
|
|
* <<nsa-x509,x509>>
|
|
|
|
|
|
[[nsa-access-denied-handler]]
|
|
== <access-denied-handler>
|
|
This element lets you set the `errorPage` property for the default `AccessDeniedHandler` used by the `ExceptionTranslationFilter` (by using the <<nsa-access-denied-handler-error-page,`error-page`>> attribute) or to supply your own implementation by using the<<nsa-access-denied-handler-ref,`ref`>> attribute.
|
|
This is discussed in more detail in the section on the xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[ExceptionTranslationFilter].
|
|
|
|
|
|
[[nsa-access-denied-handler-parents]]
|
|
=== Parent Elements of <access-denied-handler>
|
|
|
|
The parent element of the `<access-denied-handler>` element is <<nsa-http,`http`>>.
|
|
|
|
[[nsa-access-denied-handler-attributes]]
|
|
=== <access-denied-handler> Attributes
|
|
|
|
|
|
[[nsa-access-denied-handler-error-page]]
|
|
`error-page`::
|
|
The access denied page to which an authenticated user is redirected if they request a page to which they do not have access.
|
|
|
|
|
|
[[nsa-access-denied-handler-ref]]
|
|
`ref`::
|
|
Defines a reference to a Spring bean of type `AccessDeniedHandler`.
|
|
|
|
|
|
[[nsa-cors]]
|
|
== <cors>
|
|
This element allows for configuring a `CorsFilter`.
|
|
If no `CorsFilter` or `CorsConfigurationSource` is specified and Spring MVC is on the classpath, a `HandlerMappingIntrospector` is used as the `CorsConfigurationSource`.
|
|
|
|
[[nsa-cors-attributes]]
|
|
=== <cors> Attributes
|
|
The attributes on the `<cors>` element control the headers element are:
|
|
|
|
[[nsa-cors-ref]]
|
|
`ref`::
|
|
Optional attribute that specifies the bean name of a `CorsFilter`.
|
|
|
|
[[nsa-cors-configuration-source-ref]]
|
|
cors-configuration-source-ref::
|
|
Optional attribute that specifies the bean name of a `CorsConfigurationSource` to be injected into a `CorsFilter` created by the XML namespace.
|
|
|
|
[[nsa-cors-parents]]
|
|
=== Parent Elements of <cors>
|
|
|
|
The parent element of the `<cors>` element is <<nsa-http,`http`>>.
|
|
|
|
[[nsa-headers]]
|
|
== <headers>
|
|
This element allows for configuring additional (security) headers to be sent with the response.
|
|
It enables configuration for several headers and also allows for setting custom headers through the <<nsa-header,`header`>> element.
|
|
You can find additional information in the xref:features/exploits/headers.adoc#headers[Security Headers] section of the reference.
|
|
|
|
** `Cache-Control`, `Pragma`, and `Expires` - Can be set using the <<nsa-cache-control,cache-control>> element.
|
|
This ensures that the browser does not cache your secured pages.
|
|
** `Strict-Transport-Security` - Can be set using the <<nsa-hsts,hsts>> element.
|
|
This ensures that the browser automatically requests HTTPS for future requests.
|
|
** `X-Frame-Options` - Can be set using the <<nsa-frame-options,frame-options>> element.
|
|
The https://en.wikipedia.org/wiki/Clickjacking#X-Frame-Options[X-Frame-Options] header can be used to prevent clickjacking attacks.
|
|
** `X-XSS-Protection` - Can be set using the <<nsa-xss-protection,xss-protection>> element.
|
|
The https://en.wikipedia.org/wiki/Cross-site_scripting[X-XSS-Protection ] header can be used by browser to do basic control.
|
|
** `X-Content-Type-Options` - Can be set using the <<nsa-content-type-options,content-type-options>> element.
|
|
The https://blogs.msdn.com/b/ie/archive/2008/09/02/ie8-security-part-vi-beta-2-update.aspx[X-Content-Type-Options] header prevents Internet Explorer from MIME-sniffing a response away from the declared content-type.
|
|
This also applies to Google Chrome, when downloading extensions.
|
|
** `Public-Key-Pinning` or `Public-Key-Pinning-Report-Only` - Can be set using the <<nsa-hpkp,hpkp>> element.
|
|
This allows HTTPS websites to resist impersonation by attackers using mis-issued or otherwise fraudulent certificates.
|
|
** `Content-Security-Policy` or `Content-Security-Policy-Report-Only` - Can be set using the <<nsa-content-security-policy,content-security-policy>> element.
|
|
https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] is a mechanism that web applications can leverage to mitigate content injection vulnerabilities, such as cross-site scripting (XSS).
|
|
** `Referrer-Policy` - Can be set using the <<nsa-referrer-policy,referrer-policy>> element, https://www.w3.org/TR/referrer-policy/[Referrer-Policy] is a mechanism that web applications can leverage to manage the referrer field, which contains the last page the user was on.
|
|
** `Feature-Policy` - Can be set using the <<nsa-feature-policy,feature-policy>> element, https://wicg.github.io/feature-policy/[Feature-Policy] is a mechanism that allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
|
|
|
|
[[nsa-headers-attributes]]
|
|
=== <headers> Attributes
|
|
The attributes on the `<headers>` element control the `<headers>` element in the HTML output.
|
|
|
|
|
|
[[nsa-headers-defaults-disabled]]
|
|
`defaults-disabled`::
|
|
Optional attribute that specifies whether to disable the default Spring Security's HTTP response headers.
|
|
The default is `false` (the default headers are included).
|
|
|
|
[[nsa-headers-disabled]]
|
|
`disabled`::
|
|
Optional attribute that specifies whether to disable Spring Security's HTTP response headers.
|
|
The default is false (the headers are enabled).
|
|
|
|
|
|
[[nsa-headers-parents]]
|
|
=== Parent Elements of <headers>
|
|
|
|
The parent element of the `<headers>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
[[nsa-headers-children]]
|
|
=== Child Elements of <headers>
|
|
|
|
The `<headers>` element has the following possible children:
|
|
|
|
|
|
* <<nsa-cache-control,cache-control>>
|
|
* <<nsa-content-security-policy,content-security-policy>>
|
|
* <<nsa-content-type-options,content-type-options>>
|
|
* <<nsa-feature-policy,feature-policy>>
|
|
* <<nsa-frame-options,frame-options>>
|
|
* <<nsa-header,header>>
|
|
* <<nsa-hpkp,hpkp>>
|
|
* <<nsa-hsts,hsts>>
|
|
* <<nsa-permissions-policy,permission-policy>>
|
|
* <<nsa-referrer-policy,referrer-policy>>
|
|
* <<nsa-xss-protection,xss-protection>>
|
|
|
|
|
|
[[nsa-cache-control]]
|
|
== <cache-control>
|
|
The `<cache-control>` element adds the `Cache-Control`, `Pragma`, and `Expires` headers to ensure that the browser does not cache your secured pages.
|
|
|
|
|
|
[[nsa-cache-control-attributes]]
|
|
=== <cache-control> Attributes
|
|
|
|
The `<cache-control>` element can have the following attribute:
|
|
|
|
[[nsa-cache-control-disabled]]
|
|
`disabled`::
|
|
Specifies whether cache control should be disabled.
|
|
Default: `false`.
|
|
|
|
|
|
[[nsa-cache-control-parents]]
|
|
=== Parent Elements of <cache-control>
|
|
|
|
The parent of the `<cache-control>` element is the <<nsa-headers,headers>> element.
|
|
|
|
|
|
[[nsa-hsts]]
|
|
== <hsts>
|
|
When enabled, the `<hsts>` element adds the https://tools.ietf.org/html/rfc6797[Strict-Transport-Security] header to the response for any secure request.
|
|
This lets the server instruct browsers to automatically use HTTPS for future requests.
|
|
|
|
|
|
[[nsa-hsts-attributes]]
|
|
=== <hsts> Attributes
|
|
|
|
The `<hsts>` element has the following available attributes:
|
|
|
|
[[nsa-hsts-disabled]]
|
|
`disabled`::
|
|
Specifies whether Strict-Transport-Security should be disabled.
|
|
Default: `false`.
|
|
|
|
[[nsa-hsts-include-subdomains]]
|
|
`include-sub-domains`::
|
|
Specifies whether subdomains should be included.
|
|
Default: true.
|
|
|
|
|
|
[[nsa-hsts-max-age-seconds]]
|
|
`max-age-seconds`::
|
|
Specifies the maximum amount of time the host should be considered a Known HSTS Host.
|
|
Default one year.
|
|
|
|
|
|
[[nsa-hsts-request-matcher-ref]]
|
|
`request-matcher-ref`::
|
|
The `RequestMatcher` instance to be used to determine if the header should be set.
|
|
The default is to see whether `HttpServletRequest.isSecure()` is `true`.
|
|
|
|
[[nsa-hsts-preload]]
|
|
preload::
|
|
Specifies whether preload should be included.
|
|
Default: `false`.
|
|
|
|
[[nsa-hsts-parents]]
|
|
=== Parent Elements of <hsts>
|
|
|
|
The parent element of the `<hsts>` element is the <<nsa-headers,headers>> element.
|
|
|
|
|
|
[[nsa-hpkp]]
|
|
== <hpkp>
|
|
When enabled, the `<hpkp>` element adds the https://tools.ietf.org/html/rfc7469[Public Key Pinning Extension for HTTP] header to the response for any secure request.
|
|
This lets HTTPS websites resist impersonation by attackers that use mis-issued or otherwise fraudulent certificates.
|
|
|
|
|
|
[[nsa-hpkp-attributes]]
|
|
=== <hpkp> Attributes
|
|
|
|
The `<hpkp>` element can have the following elements:
|
|
|
|
[[nsa-hpkp-disabled]]
|
|
`disabled`::
|
|
Specifies if HTTP Public Key Pinning (HPKP) should be disabled.
|
|
Default: `true`.
|
|
|
|
[[nsa-hpkp-include-subdomains]]
|
|
`include-sub-domains`::
|
|
Specifies whether subdomains should be included.
|
|
Default: `false`.
|
|
|
|
|
|
[[nsa-hpkp-max-age-seconds]]
|
|
max-age-seconds::
|
|
Sets the value for the `max-age` directive of the `Public-Key-Pins` header.
|
|
Default: 60 days (5,184,000 seconds)
|
|
|
|
|
|
[[nsa-hpkp-report-only]]
|
|
`report-only`::
|
|
Specifies whether the browser should report only pin validation failures.
|
|
Default: `true`.
|
|
|
|
|
|
[[nsa-hpkp-report-uri]]
|
|
`report-uri`:
|
|
Specifies the URI to which the browser should report pin validation failures.
|
|
|
|
|
|
[[nsa-hpkp-parents]]
|
|
=== Parent Elements of <hpkp>
|
|
|
|
The parent element of the <hpkp> element is the <<nsa-headers,headers>> element.
|
|
|
|
|
|
[[nsa-pins]]
|
|
== <pins>
|
|
This section describes the attributes and child elements of the `<pins>` element.
|
|
|
|
|
|
[[nsa-pins-children]]
|
|
=== Child Elements of <pins>
|
|
|
|
The <pins> element has a single child element: <<nsa-pin,pin>>. There can be multiple <pin> elements.
|
|
|
|
|
|
[[nsa-pin]]
|
|
== <pin>
|
|
A <pin> element is specified by using the base64-encoded SPKI fingerprint as the value and the cryptographic hash algorithm as the attribute.
|
|
|
|
[[nsa-pin-attributes]]
|
|
=== <pin> Attributes
|
|
|
|
[[nsa-pin-algorithm]]
|
|
`algorithm`::
|
|
The cryptographic hash algorithm.
|
|
Default: SHA256.
|
|
|
|
|
|
[[nsa-pin-parents]]
|
|
=== Parent Elements of <pin>
|
|
|
|
The parent element of the <pin> element is the <<nsa-pins,pins>> element.
|
|
|
|
|
|
|
|
[[nsa-content-security-policy]]
|
|
== <content-security-policy>
|
|
When enabled, the `<content-security-policy>` element adds the https://www.w3.org/TR/CSP2/[Content Security Policy (CSP)] header to the response.
|
|
CSP is a mechanism that web applications can use to mitigate content injection vulnerabilities, such as cross-site scripting (XSS).
|
|
|
|
[[nsa-content-security-policy-attributes]]
|
|
=== <content-security-policy> Attributes
|
|
|
|
The <content-security-policy> element has the following attributes:
|
|
|
|
[[nsa-content-security-policy-policy-directives]]
|
|
`policy-directives`::
|
|
The security policy directive(s) for the Content-Security-Policy header. If report-only is set to `true`, the Content-Security-Policy-Report-Only header is used.
|
|
|
|
[[nsa-content-security-policy-report-only]]
|
|
`report-only`::
|
|
Whether to enable the Content-Security-Policy-Report-Only header for reporting policy violations only.
|
|
Default: `false`.
|
|
|
|
[[nsa-content-security-policy-parents]]
|
|
=== Parent Elements of <content-security-policy>
|
|
|
|
The parent element of the <content-security-policy> element is <<nsa-headers,headers>>.
|
|
|
|
|
|
|
|
[[nsa-referrer-policy]]
|
|
== <referrer-policy>
|
|
When enabled, the `<referrer-policy>` element adds the https://www.w3.org/TR/referrer-policy/[Referrer Policy] header to the response.
|
|
|
|
[[nsa-referrer-policy-attributes]]
|
|
=== <referrer-policy> Attributes
|
|
|
|
The `<referrer-policy>` element has the following attribute:
|
|
|
|
[[nsa-referrer-policy-policy]]
|
|
policy::
|
|
The policy for the `Referrer-Policy` header.
|
|
Default: `no-referrer`.
|
|
|
|
[[nsa-referrer-policy-parents]]
|
|
=== Parent Elements of <referrer-policy>
|
|
|
|
The parent element of the `<referrer-policy>` element is the <<nsa-headers,headers>> element.
|
|
|
|
|
|
|
|
[[nsa-feature-policy]]
|
|
== <feature-policy>
|
|
When enabled, the `<feature-policy>` element adds the https://wicg.github.io/feature-policy/[Feature Policy] header to the response.
|
|
|
|
[[nsa-feature-policy-attributes]]
|
|
=== <feature-policy> Attributes
|
|
|
|
The `<feature-policy>` element has the following attribute:
|
|
|
|
[[nsa-feature-policy-policy-directives]]
|
|
`policy-directives`::
|
|
The security policy directive(s) for the Feature-Policy header.
|
|
|
|
[[nsa-feature-policy-parents]]
|
|
=== Parent Elements of <feature-policy>
|
|
|
|
The parent element of the <feature-policy> element is the <<nsa-headers,headers>> element.
|
|
|
|
|
|
|
|
[[nsa-frame-options]]
|
|
== <frame-options>
|
|
When enabled, the `<frame-options>` element adds the https://tools.ietf.org/html/draft-ietf-websec-x-frame-options[X-Frame-Options header] to the response. Doing so lets newer browsers do some security checks and prevent https://en.wikipedia.org/wiki/Clickjacking[clickjacking] attacks.
|
|
|
|
|
|
[[nsa-frame-options-attributes]]
|
|
=== <frame-options> Attributes
|
|
|
|
The `<frame-options>` element has the following attributes:
|
|
|
|
[[nsa-frame-options-disabled]]
|
|
`disabled`::
|
|
If disabled, the X-Frame-Options header is not included.
|
|
Default: `false`.
|
|
|
|
[[nsa-frame-options-policy]]
|
|
`policy`::
|
|
* `DENY` (default): The page cannot be displayed in a frame, regardless of the site attempting to do so.
|
|
* `SAMEORIGIN` The page can only be displayed in a frame on the same origin as the page itself
|
|
|
|
In other words, if you specify `DENY`, not only do attempts to load the page in a frame fail when loaded from other sites, attempts to do so 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 is the same site as the one serving the page.
|
|
|
|
|
|
|
|
[[nsa-frame-options-parents]]
|
|
=== Parent Elements of <frame-options>
|
|
|
|
The parent element of the `<frame-options>` element is the <<nsa-headers,headers>> element.
|
|
|
|
[[nsa-permissions-policy]]
|
|
== <permissions-policy>
|
|
The `<xss-protection>` adds the https://blogs.msdn.com/b/ie/archive/2008/07/02/ie8-security-part-iv-the-xss-filter.aspx[X-XSS-Protection header] to the response, to assist in protecting against https://en.wikipedia.org/wiki/Cross-site_scripting#Non-Persistent[reflected / Type-1 Cross-Site Scripting (XSS)] attacks.
|
|
|
|
[NOTE]
|
|
====
|
|
Full protection against XSS attacks is not possible.
|
|
====
|
|
|
|
[[nsa-permissions-policy-attributes]]
|
|
=== <permissions-policy> Attributes
|
|
|
|
[[nsa-permissions-policy-policy]]
|
|
* **policy**
|
|
The policy value to write for the `Permissions-Policy` header
|
|
|
|
[[nsa-permissions-policy-parents]]
|
|
=== Parent Elements of <permissions-policy>
|
|
|
|
* <<nsa-headers,headers>>
|
|
|
|
[[nsa-xss-protection]]
|
|
== <xss-protection>
|
|
Adds the https://blogs.msdn.com/b/ie/archive/2008/07/02/ie8-security-part-iv-the-xss-filter.aspx[X-XSS-Protection header] to the response to assist in protecting against https://en.wikipedia.org/wiki/Cross-site_scripting#Non-Persistent[reflected / Type-1 Cross-Site Scripting (XSS)] attacks.
|
|
This is in no-way a full protection to XSS attacks!
|
|
|
|
|
|
[[nsa-xss-protection-attributes]]
|
|
=== <xss-protection> Attributes
|
|
|
|
The `<xss-protection>` element has the following attributes:
|
|
|
|
[[nsa-xss-protection-disabled]]
|
|
`xss-protection-disabled`::
|
|
If set to `true`, do not include the header for https://en.wikipedia.org/wiki/Cross-site_scripting#Non-Persistent[reflected / Type-1 Cross-Site Scripting (XSS)] protection.
|
|
|
|
|
|
[[nsa-xss-protection-enabled]]
|
|
`xss-protection-enabled`::
|
|
Whether to explicitly enable or disable https://en.wikipedia.org/wiki/Cross-site_scripting#Non-Persistent[reflected / Type-1 Cross-Site Scripting (XSS)] protection.
|
|
|
|
|
|
[[nsa-xss-protection-block]]
|
|
`xss-protection-block`::
|
|
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 is still rendered when a reflected attack is detected, but the response is 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.
|
|
|
|
|
|
[[nsa-xss-protection-parents]]
|
|
=== Parent Elements of <xss-protection>
|
|
|
|
The parent element of the `<xss-protection>` is the <<nsa-headers,headers>> element.
|
|
|
|
|
|
|
|
[[nsa-content-type-options]]
|
|
== <content-type-options>
|
|
The `<content-type-options>` element adds the `X-Content-Type-Options` header with a value of `nosniff` to the response.
|
|
This https://blogs.msdn.com/b/ie/archive/2008/09/02/ie8-security-part-vi-beta-2-update.aspx[disables MIME-sniffing] for IE8+ and Chrome extensions.
|
|
|
|
|
|
[[nsa-content-type-options-attributes]]
|
|
=== <content-type-options> Attributes
|
|
|
|
The `<content-type-options>` element has the following attribute:
|
|
|
|
[[nsa-content-type-options-disabled]]
|
|
`disabled`::
|
|
Specifies whether Content Type Options should be disabled.
|
|
Default: `false`.
|
|
|
|
[[nsa-content-type-options-parents]]
|
|
=== Parent Elements of <content-type-options>
|
|
|
|
|
|
* <<nsa-headers,headers>>
|
|
|
|
The parent element of the `<content-type-options>` element is the <<nsa-headers,headers>> element.
|
|
|
|
[[nsa-header]]
|
|
== <header>
|
|
The `<header>` element adds additional headers to the response. Both the name and value of each added header need to be specified in a `<header-attributes>` element (a child of the `<header>` element). To add multiple headers, add multiple `<header-attributes>` elements.
|
|
|
|
[[nsa-header-attributes]]
|
|
=== <header-attributes> Attributes
|
|
|
|
The `<header-attributes>` element has the following attributes:
|
|
|
|
[[nsa-header-name]]
|
|
`header-name`::
|
|
The `name` of the header to add.
|
|
|
|
|
|
[[nsa-header-value]]
|
|
value::
|
|
The `value` of the header to add.
|
|
|
|
|
|
[[nsa-header-ref]]
|
|
`ref`::
|
|
Reference to a custom implementation of the `HeaderWriter` interface.
|
|
|
|
|
|
[[nsa-header-parents]]
|
|
=== Parent Elements of <header>
|
|
|
|
|
|
The parent element of the `<header>` is the <<nsa-headers,headers>> element.
|
|
|
|
|
|
|
|
[[nsa-anonymous]]
|
|
== <anonymous>
|
|
The `<anonymous>` element adds an `AnonymousAuthenticationFilter` to the stack and adds an `AnonymousAuthenticationProvider`.
|
|
This element is required if you use the `IS_AUTHENTICATED_ANONYMOUSLY` attribute.
|
|
|
|
|
|
[[nsa-anonymous-parents]]
|
|
=== Parent Elements of <anonymous>
|
|
|
|
|
|
The parent element of the `<anonymous>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
|
|
[[nsa-anonymous-attributes]]
|
|
=== <anonymous> Attributes
|
|
|
|
The `<anonymous>` element has the following attributes:
|
|
|
|
[[nsa-anonymous-enabled]]
|
|
`enabled`::
|
|
With the default namespace setup, the anonymous "`authentication`" facility is automatically enabled.
|
|
You can disable it by setting this property.
|
|
|
|
|
|
[[nsa-anonymous-granted-authority]]
|
|
`granted-authority`::
|
|
The granted authority that should be assigned to the anonymous request.
|
|
Commonly, this attribute is used to assign the anonymous request particular roles, which can subsequently be used in authorization decisions.
|
|
If unset, it defaults to `ROLE_ANONYMOUS`.
|
|
|
|
|
|
[[nsa-anonymous-key]]
|
|
`key`::
|
|
The key shared between the provider and the filter.
|
|
This generally does not need to be set.
|
|
If unset, it defaults to a secure randomly generated value.
|
|
This means that setting this value can improve startup time when using the anonymous functionality, since secure random values can take a while to be generated.
|
|
|
|
|
|
[[nsa-anonymous-username]]
|
|
username::
|
|
The username that should be assigned to the anonymous request.
|
|
This lets the principal be identified, which may be important for logging and auditing.
|
|
Defaults: `anonymousUser`
|
|
|
|
|
|
[[nsa-csrf]]
|
|
== <csrf>
|
|
The `<csrf` element adds https://en.wikipedia.org/wiki/Cross-site_request_forgery[Cross Site Request Forger (CSRF)] protection to the application.
|
|
It also updates the default `RequestCache` to replay only `GET` requests upon successful authentication.
|
|
You can find additional information in the <<csrf,Cross Site Request Forgery (CSRF)>> section of the reference.
|
|
|
|
|
|
[[nsa-csrf-parents]]
|
|
=== Parent Elements of <csrf>
|
|
|
|
|
|
The parent element of the `<csrf>` element is the <<nsa-http,`http`>> element.
|
|
|
|
|
|
|
|
[[nsa-csrf-attributes]]
|
|
=== <csrf> Attributes
|
|
|
|
The `<csrf>` element has the following attributes:
|
|
|
|
[[nsa-csrf-disabled]]
|
|
`disabled`::
|
|
Optional attribute that specifies whether to disable Spring Security's CSRF protection.
|
|
Default: `false` (CSRF protection is enabled)
|
|
We highly recommended leaving CSRF protection enabled.
|
|
|
|
[[nsa-csrf-token-repository-ref]]
|
|
`token-repository-ref`::
|
|
The `CsrfTokenRepository` to use.
|
|
Default: `HttpSessionCsrfTokenRepository`
|
|
|
|
|
|
[[nsa-csrf-request-matcher-ref]]
|
|
request-matcher-ref::
|
|
The `RequestMatcher` instance to be used to determine whether CSRF should be applied.
|
|
The default is any HTTP method except `GET`, `TRACE`, `HEAD`, `OPTIONS`.
|
|
|
|
|
|
[[nsa-custom-filter]]
|
|
== <custom-filter>
|
|
The `<custom-filter>` element adds a filter to the filter chain.
|
|
It does not 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 xref:servlet/configuration/xml-namespace.adoc#ns-custom-filters[ namespace chapter].
|
|
|
|
|
|
[[nsa-custom-filter-parents]]
|
|
=== Parent Elements of <custom-filter>
|
|
|
|
|
|
The parent element of the `<custom-filter>` is the <<nsa-http,http>> element.
|
|
|
|
|
|
|
|
[[nsa-custom-filter-attributes]]
|
|
=== <custom-filter> Attributes
|
|
|
|
The `<custom-filter>` element has the following attributes:
|
|
|
|
[[nsa-custom-filter-after]]
|
|
`after`::
|
|
The filter immediately after which the custom filter should be placed in the chain.
|
|
This feature is needed only 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.
|
|
|
|
|
|
[[nsa-custom-filter-before]]
|
|
`position`::
|
|
The explicit position at which the custom filter should be placed in the chain.
|
|
Use this attribute to replace a standard filter.
|
|
|
|
|
|
[[nsa-custom-filter-position]]
|
|
* **position**
|
|
The explicit position at which the custom-filter should be placed in the chain.
|
|
Use if you are replacing a standard filter.
|
|
|
|
|
|
[[nsa-custom-filter-ref]]
|
|
ref::
|
|
Defines a reference to a Spring bean that implements `Filter`.
|
|
|
|
|
|
[[nsa-expression-handler]]
|
|
== <expression-handler>
|
|
Defines the `SecurityExpressionHandler` instance to be used if expression-based access control is enabled.
|
|
A default implementation (with no ACL support) is used if none is supplied.
|
|
|
|
|
|
[[nsa-expression-handler-parents]]
|
|
=== Parent Elements of <expression-handler>
|
|
|
|
The `<expression-handler>` has the following parent elements:
|
|
|
|
* xref:servlet/appendix/namespace/method-security.adoc#nsa-global-method-security[global-method-security]
|
|
* <<nsa-http,http>>
|
|
* xref:servlet/appendix/namespace/method-security.adoc#nsa-method-security[method-security]
|
|
* xref:servlet/appendix/namespace/websocket.adoc#nsa-websocket-message-broker[websocket-message-broker]
|
|
|
|
|
|
|
|
[[nsa-expression-handler-attributes]]
|
|
=== <expression-handler> Attributes
|
|
|
|
|
|
[[nsa-expression-handler-ref]]
|
|
`ref`::
|
|
Defines a reference to a Spring bean that implements `SecurityExpressionHandler`.
|
|
|
|
|
|
[[nsa-form-login]]
|
|
== <form-login>
|
|
Used to add an `UsernamePasswordAuthenticationFilter` to the filter stack and a `LoginUrlAuthenticationEntryPoint` to the application context, to provide authentication on demand.
|
|
This always takes precedence over other namespace-created entry points.
|
|
If no attributes are supplied, a login page is generated automatically at the `/login` URL.
|
|
You can customize this behavior by setting the <<nsa-form-login-attributes, `<form-login>` Attributes>>.
|
|
|
|
[NOTE]
|
|
====
|
|
This feature is provided for convenience and is not intended for production (where a view technology should have been chosen and can be used to render a customized login page).
|
|
The class `DefaultLoginPageGeneratingFilter` class is responsible for rendering the login page and provide login forms for both normal form login and OpenID if required.
|
|
====
|
|
|
|
|
|
[[nsa-form-login-parents]]
|
|
=== Parent Elements of <form-login>
|
|
|
|
|
|
The parent element of the `<form-login>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
|
|
[[nsa-form-login-attributes]]
|
|
=== <form-login> Attributes
|
|
The `form-login` element has the following attributes:
|
|
|
|
|
|
[[nsa-form-login-always-use-default-target]]
|
|
`always-use-default-target`::
|
|
If set to `true`, the user always starts at the value given by <<nsa-form-login-default-target-url,`default-target-url`>>, regardless of how they arrived at the login page.
|
|
Maps to the `alwaysUseDefaultTargetUrl` property of `UsernamePasswordAuthenticationFilter`.
|
|
Default: `false`.
|
|
|
|
[[nsa-form-login-authentication-details-source-ref]]
|
|
`authentication-failure-handler-ref`::
|
|
Can be used as an alternative to <<nsa-form-login-authentication-failure-url,`authentication-failure-url`>>, giving you full control over the navigation flow after an authentication failure.
|
|
|
|
|
|
[[nsa-form-login-authentication-failure-handler-ref]]
|
|
* **authentication-failure-handler-ref**
|
|
Can be used as an alternative to <<nsa-form-login-authentication-failure-url,authentication-failure-url>>, giving you full control over the navigation flow after an authentication failure.
|
|
The value should be the name of an `AuthenticationFailureHandler` bean in the application context.
|
|
|
|
|
|
[[nsa-form-login-authentication-failure-url]]
|
|
* **authentication-failure-url**
|
|
Maps to the `authenticationFailureUrl` property of `UsernamePasswordAuthenticationFilter`.
|
|
Defines the URL to which the browser is redirected on login failure.
|
|
Defaults to `/login?error`, which is automatically handled by the automatic login page generator, re-rendering the login page with an error message.
|
|
|
|
|
|
[[nsa-form-login-authentication-success-handler-ref]]
|
|
`authentication-success-handler-ref`::
|
|
You an use this as an alternative to <<nsa-form-login-default-target-url,`default-target-url`>> and <<nsa-form-login-always-use-default-target,`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 <<nsa-form-login-default-target-url,`default-target-url` >>.
|
|
|
|
[[nsa-form-login-default-target-url]]
|
|
default-target-url::
|
|
Maps to the `defaultTargetUrl` property of `UsernamePasswordAuthenticationFilter`.
|
|
If not set, the default value is `/` (the application root).
|
|
A user is 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.
|
|
|
|
|
|
[[nsa-form-login-login-page]]
|
|
`login-page`::
|
|
The URL that should be used to render the login page.
|
|
Maps to the `loginFormUrl` property of the `LoginUrlAuthenticationEntryPoint`.
|
|
Default: `/login`.
|
|
|
|
|
|
|
|
[[nsa-form-login-login-processing-url]]
|
|
* **login-processing-url**
|
|
Maps to the `filterProcessesUrl` property of `UsernamePasswordAuthenticationFilter`.
|
|
The default value is "/login".
|
|
|
|
|
|
[[nsa-form-login-password-parameter]]
|
|
* **password-parameter**
|
|
The name of the request parameter that contains the password.
|
|
Default: `password`.
|
|
|
|
|
|
[[nsa-form-login-username-parameter]]
|
|
username-parameter::
|
|
The name of the request parameter that contains the username.
|
|
Default: `username`.
|
|
|
|
[[nsa-form-login-authentication-success-forward-url]]
|
|
`authentication-success-forward-url`::
|
|
Maps a `ForwardAuthenticationSuccessHandler` to the `authenticationSuccessHandler` property of `UsernamePasswordAuthenticationFilter`.
|
|
|
|
|
|
[[nsa-form-login-authentication-failure-forward-url]]
|
|
`authentication-failure-forward-url`::
|
|
Maps a `ForwardAuthenticationFailureHandler` to the `authenticationFailureHandler` property of `UsernamePasswordAuthenticationFilter`.
|
|
|
|
|
|
[[nsa-oauth2-login]]
|
|
== <oauth2-login>
|
|
The xref:servlet/oauth2/login/index.adoc#oauth2login[OAuth 2.0 Login] feature configures authentication support by using an OAuth 2.0 or OpenID Connect 1.0 Provider.
|
|
|
|
|
|
[[nsa-oauth2-login-parents]]
|
|
=== Parent Elements of <oauth2-login>
|
|
|
|
The parent element of the `<oauth2-login>` element is the <<nsa-http,http>> element.
|
|
|
|
[[nsa-oauth2-login-attributes]]
|
|
=== <oauth2-login> Attributes
|
|
|
|
The `<oauth2-login>` has the following attributes:
|
|
|
|
[[nsa-oauth2-login-client-registration-repository-ref]]
|
|
`client-registration-repository-ref`::
|
|
Reference to the `ClientRegistrationRepository`.
|
|
|
|
|
|
[[nsa-oauth2-login-authorized-client-repository-ref]]
|
|
`authorized-client-repository-ref`::
|
|
Reference to the `OAuth2AuthorizedClientRepository`.
|
|
|
|
|
|
[[nsa-oauth2-login-authorized-client-service-ref]]
|
|
`authorized-client-service-ref`::
|
|
Reference to the `OAuth2AuthorizedClientService`.
|
|
|
|
|
|
[[nsa-oauth2-login-authorization-request-repository-ref]]
|
|
`authorization-request-repository-ref`::
|
|
Reference to the `AuthorizationRequestRepository`.
|
|
|
|
|
|
[[nsa-oauth2-login-authorization-request-resolver-ref]]
|
|
`authorization-request-resolver-ref`::
|
|
Reference to the `OAuth2AuthorizationRequestResolver`.
|
|
|
|
|
|
[[nsa-oauth2-login-access-token-response-client-ref]]
|
|
`access-token-response-client-ref`::
|
|
Reference to the `OAuth2AccessTokenResponseClient`.
|
|
|
|
|
|
[[nsa-oauth2-login-user-authorities-mapper-ref]]
|
|
`user-authorities-mapper-ref`::
|
|
Reference to the `GrantedAuthoritiesMapper`.
|
|
|
|
|
|
[[nsa-oauth2-login-user-service-ref]]
|
|
`user-service-ref`::
|
|
Reference to the `OAuth2UserService`.
|
|
|
|
|
|
[[nsa-oauth2-login-oidc-user-service-ref]]
|
|
`oidc-user-service-ref`::
|
|
Reference to the OpenID Connect `OAuth2UserService`.
|
|
|
|
|
|
[[nsa-oauth2-login-login-processing-url]]
|
|
`login-processing-url`::
|
|
The URI where the filter processes authentication requests.
|
|
|
|
|
|
[[nsa-oauth2-login-login-page]]
|
|
`login-page`::
|
|
The URI to which to send users to login.
|
|
|
|
|
|
[[nsa-oauth2-login-authentication-success-handler-ref]]
|
|
`authentication-success-handler-ref`::
|
|
Reference to the `AuthenticationSuccessHandler`.
|
|
|
|
|
|
[[nsa-oauth2-login-authentication-failure-handler-ref]]
|
|
`authentication-failure-handler-ref`::
|
|
Reference to the `AuthenticationFailureHandler`.
|
|
|
|
|
|
[[nsa-oauth2-login-jwt-decoder-factory-ref]]
|
|
`jwt-decoder-factory-ref`::
|
|
Reference to the `JwtDecoderFactory` used by `OidcAuthorizationCodeAuthenticationProvider`.
|
|
|
|
|
|
[[nsa-oauth2-client]]
|
|
== <oauth2-client>
|
|
Configures xref:servlet/oauth2/client/index.adoc#oauth2client[OAuth 2.0 Client] support.
|
|
|
|
|
|
[[nsa-oauth2-client-parents]]
|
|
=== Parent Elements of <oauth2-client>
|
|
|
|
The parent of the `<oauth2-client>` is the <<nsa-http,http>> element.
|
|
|
|
[[nsa-oauth2-client-attributes]]
|
|
=== <oauth2-client> Attributes
|
|
|
|
The `<oauth2-client>` element has the following attributes:
|
|
|
|
[[nsa-oauth2-client-client-registration-repository-ref]]
|
|
`client-registration-repository-ref`::
|
|
Reference to the `ClientRegistrationRepository`.
|
|
|
|
|
|
[[nsa-oauth2-client-authorized-client-repository-ref]]
|
|
`authorized-client-repository-ref`::
|
|
Reference to the `OAuth2AuthorizedClientRepository`.
|
|
|
|
|
|
[[nsa-oauth2-client-authorized-client-service-ref]]
|
|
`authorized-client-service-ref`::
|
|
Reference to the `OAuth2AuthorizedClientService`.
|
|
|
|
|
|
[[nsa-oauth2-client-children]]
|
|
=== Child Elements of <oauth2-client>
|
|
|
|
The `<oauth2-client>` has one child element: <<nsa-authorization-code-grant,authorization-code-grant>>.
|
|
|
|
|
|
[[nsa-authorization-code-grant]]
|
|
== <authorization-code-grant>
|
|
Configures xref:servlet/oauth2/client/authorization-grants.adoc#oauth2Client-auth-grant-support[OAuth 2.0 Authorization Code Grant].
|
|
|
|
|
|
[[nsa-authorization-code-grant-parents]]
|
|
=== Parent Elements of <authorization-code-grant>
|
|
|
|
The parent element of the `<authorization-code-grant>` element is the <<nsa-oauth2-client,`oauth2-client`>> element.
|
|
|
|
|
|
[[nsa-authorization-code-grant-attributes]]
|
|
=== <authorization-code-grant> Attributes
|
|
|
|
The `<authorization-code-grant>` element has the following attributes:
|
|
|
|
[[nsa-authorization-code-grant-authorization-request-repository-ref]]
|
|
`authorization-request-repository-ref`::
|
|
Reference to the `AuthorizationRequestRepository`.
|
|
|
|
|
|
[[nsa-authorization-code-grant-authorization-request-resolver-ref]]
|
|
`authorization-request-resolver-ref`::
|
|
Reference to the `OAuth2AuthorizationRequestResolver`.
|
|
|
|
|
|
[[nsa-authorization-code-grant-access-token-response-client-ref]]
|
|
`access-token-response-client-ref`::
|
|
Reference to the `OAuth2AccessTokenResponseClient`.
|
|
|
|
|
|
[[nsa-client-registrations]]
|
|
== <client-registrations>
|
|
The `<client-registrations>` is a container element for client(s) registered (xref:servlet/oauth2/client/index.adoc#oauth2Client-client-registration[ClientRegistration]) with an OAuth 2.0 or OpenID Connect 1.0 Provider.
|
|
|
|
|
|
[[nsa-client-registrations-children]]
|
|
=== Child Elements of <client-registrations>
|
|
|
|
The `<client-registration>` represents a client registered with an OAuth 2.0 or OpenID Connect 1.0 Provider. You can have multiple `<client-registration>` elements.
|
|
|
|
* <<nsa-client-registration,client-registration>>
|
|
* <<nsa-provider,provider>>
|
|
|
|
|
|
[[nsa-client-registration]]
|
|
== <client-registration>
|
|
Represents a client registered with an OAuth 2.0 or OpenID Connect 1.0 Provider.
|
|
|
|
|
|
[[nsa-client-registration-parents]]
|
|
=== Parent Elements of <client-registration>
|
|
|
|
The parent element of the `<client-registration>` is the <<nsa-client-registrations,client-registrations>>.
|
|
|
|
|
|
[[nsa-client-registration-attributes]]
|
|
=== <client-registration> Attributes
|
|
|
|
|
|
[[nsa-client-registration-registration-id]]
|
|
registration-`id`::
|
|
The ID that uniquely identifies the `ClientRegistration`.
|
|
|
|
|
|
[[nsa-client-registration-client-id]]
|
|
`client-id`::
|
|
The client identifier.
|
|
|
|
|
|
[[nsa-client-registration-client-secret]]
|
|
`client-secret`::
|
|
The client secret.
|
|
|
|
|
|
[[nsa-client-registration-client-authentication-method]]
|
|
`client-authentication-method`::
|
|
The method used to authenticate the Client with the Provider.
|
|
The supported values are *client_secret_basic*, *client_secret_post*, *private_key_jwt*, *client_secret_jwt* and *none* https://tools.ietf.org/html/rfc6749#section-2.1[(public clients)].
|
|
|
|
|
|
[[nsa-client-registration-authorization-grant-type]]
|
|
`authorization-grant-type`::
|
|
The OAuth 2.0 Authorization Framework defines four https://tools.ietf.org/html/rfc6749#section-1.3[Authorization Grant] types.
|
|
The supported values are `authorization_code`, `client_credentials`, `password`, as well as, extension grant type `urn:ietf:params:oauth:grant-type:jwt-bearer`.
|
|
|
|
|
|
[[nsa-client-registration-redirect-uri]]
|
|
`redirect-uri`::
|
|
The client's registered redirect URI to which the _Authorization Server_ redirects the end-user's user-agent after the end-user has authenticated and authorized access to the client.
|
|
|
|
|
|
[[nsa-client-registration-scope]]
|
|
`scope`::
|
|
The scope(s) requested by the client during the Authorization Request flow, such as `openid`, `email`, or `profile`.
|
|
|
|
|
|
[[nsa-client-registration-client-name]]
|
|
`client-name`::
|
|
A descriptive name used for the client.
|
|
The name may be used in certain scenarios, such as when displaying the name of the client in the auto-generated login page.
|
|
|
|
[[nsa-client-registration-provider-id]]
|
|
`provider-id`::
|
|
A reference to the associated provider. May reference a `<provider>` element or use one of the common providers (Google, Github, Facebook, Okta, and others).
|
|
|
|
|
|
[[nsa-provider]]
|
|
== <provider>
|
|
The `<provider>` element contains the configuration information for an OAuth 2.0 or OpenID Connect 1.0 Provider.
|
|
|
|
|
|
[[nsa-provider-parents]]
|
|
=== Parent Elements of <provider>
|
|
|
|
The parent element of the `<provider>` element is the <<nsa-client-registrations,client-registrations>> element.
|
|
|
|
[[nsa-provider-attributes]]
|
|
=== <provider> Attributes
|
|
|
|
The `<provider>` element has the following attributes:
|
|
|
|
[[nsa-provider-provider-id]]
|
|
`provider-id`::
|
|
The ID that uniquely identifies the provider.
|
|
|
|
|
|
[[nsa-provider-authorization-uri]]
|
|
`authorization-uri`::
|
|
The authorization endpoint URI for the authorization server.
|
|
|
|
|
|
[[nsa-provider-token-uri]]
|
|
`token-uri`::
|
|
The token endpoint URI for the authorization server.
|
|
|
|
|
|
[[nsa-provider-user-info-uri]]
|
|
`user-info-uri`::
|
|
The UserInfo endpoint URI used to access the claims and attributes of the authenticated end user.
|
|
|
|
|
|
[[nsa-provider-user-info-authentication-method]]
|
|
`user-info-authentication-method`::
|
|
The authentication method used when sending the access token to the UserInfo endpoint.
|
|
The supported values are `header`, `form`, and `query`.
|
|
|
|
|
|
[[nsa-provider-user-info-user-name-attribute]]
|
|
* **user-info-user-name-attribute**
|
|
`user-info-user-name-attribute`::
|
|
The name of the attribute returned in the UserInfo response that references the name or edentifier of the end-user.
|
|
|
|
|
|
[[nsa-provider-jwk-set-uri]]
|
|
`jwk-set-uri`::
|
|
The URI used to retrieve the https://tools.ietf.org/html/rfc7517[JSON Web Key (JWK)] set from the authorization server, which contains the cryptographic key(s) used to verify the https://tools.ietf.org/html/rfc7515[JSON Web Signature (JWS)] of the ID Token and (optionally) the UserInfo response.
|
|
|
|
|
|
[[nsa-provider-issuer-uri]]
|
|
issuer-uri::
|
|
The URI used to initially configure a `ClientRegistration` by using discovery of an OpenID Connect Provider's https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[configuration endpoint] or an Authorization Server's https://tools.ietf.org/html/rfc8414#section-3[metadata endpoint].
|
|
|
|
[[nsa-oauth2-resource-server]]
|
|
== <oauth2-resource-server>
|
|
Adds a `BearerTokenAuthenticationFilter`, a `BearerTokenAuthenticationEntryPoint`, and a `BearerTokenAccessDeniedHandler` to the configuration.
|
|
In addition, either `<jwt>` or `<opaque-token>` must be specified.
|
|
|
|
[[nsa-oauth2-resource-server-parents]]
|
|
=== Parents Elements of <oauth2-resource-server>
|
|
|
|
The parent element of the `<oauth2-resource-server>` is the <<nsa-http,http>> element.
|
|
|
|
[[nsa-oauth2-resource-server-children]]
|
|
=== Child Elements of <oauth2-resource-server>
|
|
|
|
The `<oauth2-resource-server>` element has the following attributes:
|
|
|
|
* <<nsa-jwt,jwt>>
|
|
* <<nsa-opaque-token,opaque-token>>
|
|
|
|
[[nsa-oauth2-resource-server-attributes]]
|
|
=== <oauth2-resource-server> Attributes
|
|
|
|
[[nsa-oauth2-resource-server-authentication-manager-resolver-ref]]
|
|
`authentication-manager-resolver-ref`::
|
|
Reference to an `AuthenticationManagerResolver`, which resolves the `AuthenticationManager` at request time.
|
|
|
|
[[nsa-oauth2-resource-server-bearer-token-resolver-ref]]
|
|
`bearer-token-resolver-ref`::
|
|
Reference to a `BearerTokenResolver`, which retrieves the bearer token from the request.
|
|
|
|
[[nsa-oauth2-resource-server-entry-point-ref]]
|
|
`entry-point-ref`::
|
|
Reference to a `AuthenticationEntryPoint`, which handles unauthorized requests.
|
|
|
|
[[nsa-jwt]]
|
|
== <jwt>
|
|
The `<jwt>` element represents an OAuth 2.0 Resource Server that authorizes JWTs (JSON Web Tokens).
|
|
|
|
|
|
[[nsa-jwt-parents]]
|
|
=== Parent Elements of <jwt>
|
|
|
|
The parent element of the `<jwt>` element is the <<nsa-oauth2-resource-server,oauth2-resource-server>> element.
|
|
|
|
|
|
[[nsa-jwt-attributes]]
|
|
=== <jwt> Attributes
|
|
|
|
The `<jwt>` element has the following attributes:
|
|
|
|
[[nsa-jwt-jwt-authentication-converter-ref]]
|
|
`jwt-authentication-converter-ref`::
|
|
Reference to a `Converter<Jwt, AbstractAuthenticationToken>`.
|
|
|
|
[[nsa-jwt-decoder-ref]]
|
|
`jwt-decoder-ref`::
|
|
Reference to a `JwtDecoder`. This is a larger component that overrides `jwk-set-uri`.
|
|
|
|
[[nsa-jwt-jwk-set-uri]]
|
|
`jwk-set-uri`::
|
|
The JWK Set URI used to load signing verification keys from an OAuth 2.0 Authorization Server.
|
|
|
|
[[nsa-opaque-token]]
|
|
== <opaque-token>
|
|
Represents an OAuth 2.0 Resource Server that authorizes opaque tokens.
|
|
|
|
[[nsa-opaque-token-parents]]
|
|
=== Parent Elements of <opaque-token>
|
|
|
|
The parent element of the `<opaque-token` element is the <<nsa-oauth2-resource-server,`oauth2-resource-server`>> element.
|
|
|
|
[[nsa-opaque-token-attributes]]
|
|
=== <opaque-token> Attributes
|
|
|
|
[[nsa-opaque-token-introspector-ref]]
|
|
`introspector-ref`::
|
|
Reference to an `OpaqueTokenIntrospector`. This is a larger component that overrides `introspection-uri`, `client-id`, and `client-secret`.
|
|
|
|
[[nsa-opaque-token-introspection-uri]]
|
|
`introspection-uri`::
|
|
The Introspection URI used to introspect the details of an opaque token. It should be accompanied by a `client-id` and `client-secret`.
|
|
|
|
[[nsa-opaque-token-client-id]]
|
|
`client-id`::
|
|
The client ID to use for client authentication against the provided `introspection-uri`.
|
|
|
|
[[nsa-opaque-token-client-secret]]
|
|
`client-secret`::
|
|
The client secret to use for client authentication against the provided `introspection-uri`.
|
|
|
|
[[nsa-http-basic]]
|
|
== <http-basic>
|
|
The <http-basic element> adds a `BasicAuthenticationFilter` and `BasicAuthenticationEntryPoint` to the configuration.
|
|
The latter is used as the configuration entry point only if form-based login is not enabled.
|
|
|
|
|
|
[[nsa-http-basic-parents]]
|
|
=== Parent Elements of <http-basic>
|
|
|
|
|
|
The parent element of the `<http-basic>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
|
|
[[nsa-http-basic-attributes]]
|
|
=== <http-basic> Attributes
|
|
|
|
The `<http-basic>` element has the following attributes:
|
|
|
|
[[nsa-http-basic-authentication-details-source-ref]]
|
|
`authentication-details-source-ref`::
|
|
Reference to an `AuthenticationDetailsSource`, which is used by the authentication filter.
|
|
|
|
|
|
[[nsa-http-basic-entry-point-ref]]
|
|
`entry-point-ref`::
|
|
Sets the `AuthenticationEntryPoint`, which is used by the `BasicAuthenticationFilter`.
|
|
|
|
|
|
[[nsa-http-firewall]]
|
|
== <http-firewall> Element
|
|
`<http-firewall>` is a top-level element that you can use to inject a custom implementation of `HttpFirewall` into the `FilterChainProxy` created by the namespace.
|
|
|
|
|
|
[[nsa-http-firewall-attributes]]
|
|
=== <http-firewall> Attributes
|
|
|
|
`<http-firewall>` has a single attribute:
|
|
|
|
[[nsa-http-firewall-ref]]
|
|
`ref`::
|
|
Defines a reference to a Spring bean that implements `HttpFirewall`.
|
|
|
|
|
|
[[nsa-intercept-url]]
|
|
== <intercept-url>
|
|
`<intercept-url>` element defines the set of URL patterns that the application is interested in and configures how they should be handled.
|
|
It constructs 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 patterns should come first and the most general should come last.
|
|
|
|
|
|
[[nsa-intercept-url-parents]]
|
|
=== Parent Elements of <intercept-url>
|
|
|
|
The parent elements of the `<intercept-url>` element are:
|
|
|
|
* <<nsa-filter-security-metadata-source,filter-security-metadata-source>>
|
|
* <<nsa-http,http>>
|
|
|
|
|
|
|
|
[[nsa-intercept-url-attributes]]
|
|
=== <intercept-url> Attributes
|
|
|
|
The `<intercept-url>` element has the following parameters:
|
|
|
|
[[nsa-intercept-url-access]]
|
|
`access`::
|
|
Lists the access attributes, which are stored in the `FilterInvocationSecurityMetadataSource` for the defined URL pattern and method combination.
|
|
This should be a comma-separated list of the security configuration attributes (such as role names).
|
|
|
|
|
|
[[nsa-intercept-url-method]]
|
|
`method`::
|
|
The HTTP Method that is used in combination with the pattern and servlet path (optional) to match an incoming request.
|
|
If omitted, any method matchs.
|
|
If an identical pattern is specified with and without a method, the method-specific match takes precedence.
|
|
|
|
|
|
[[nsa-intercept-url-pattern]]
|
|
`pattern`::
|
|
The pattern that defines the URL path.
|
|
The content depends on the `request-matcher` attribute from the containing `<http>` element, so it defaults to Ant path syntax.
|
|
|
|
|
|
[[nsa-intercept-url-request-matcher-ref]]
|
|
`request-matcher-ref`::
|
|
A reference to a `RequestMatcher` that is used to determine if this `<intercept-url>` is used.
|
|
|
|
|
|
[[nsa-intercept-url-requires-channel]]
|
|
`requires-channel`::
|
|
Can be `http` or `https`, depending on whether a particular URL pattern should be accessed over HTTP or HTTPS, respectively.
|
|
Alternatively, you can use a value of `any` when you have no preference.
|
|
If this attribute is present on any `<intercept-url>` element, a `ChannelProcessingFilter` is added to the filter stack and its additional dependencies are added to the application context.
|
|
|
|
If a `<port-mappings>` configuration is added, it is used by the `SecureChannelProcessor` and `InsecureChannelProcessor` beans to determine the ports used for redirecting to HTTP and HTTPS.
|
|
|
|
[NOTE]
|
|
====
|
|
This property is invalid for <<nsa-filter-security-metadata-source,`filter-security-metadata-source`>>
|
|
====
|
|
|
|
[[nsa-intercept-url-servlet-path]]
|
|
`servlet-path`::
|
|
The servlet path to be used, in combination with the pattern and HTTP method, to match an incoming request.
|
|
This attribute is only applicable when <<nsa-http-request-matcher,request-matcher>> is `mvc`.
|
|
In addition, the value is only required in the following two use cases:
|
|
* Two or more `HttpServlet` instances that have mappings starting with `/` and are different are registered in the `ServletContext`.
|
|
* The pattern starts with the same value of a registered `HttpServlet` path, excluding the default (root) `HttpServlet` `/`.
|
|
|
|
[NOTE]
|
|
====
|
|
This property is invalid for <<nsa-filter-security-metadata-source,`filter-security-metadata-source`>>
|
|
====
|
|
|
|
[[nsa-jee]]
|
|
== <jee>
|
|
The `<jee>` element adds a `J2eePreAuthenticatedProcessingFilter` to the filter chain to provide integration with container authentication.
|
|
|
|
|
|
[[nsa-jee-parents]]
|
|
=== Parent Elements of <jee>
|
|
|
|
The parent element of the `<jee>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
[[nsa-jee-attributes]]
|
|
=== <jee> Attributes
|
|
|
|
The `<jee>` element has the following attributes:
|
|
|
|
[[nsa-jee-mappable-roles]]
|
|
`mappable-roles`::
|
|
A comma-separated list of roles to look for in the incoming `HttpServletRequest`.
|
|
|
|
|
|
[[nsa-jee-user-service-ref]]
|
|
`user-service-ref`::
|
|
A reference to a user-service (or `UserDetailsService` bean) ID.
|
|
|
|
[[nsa-logout]]
|
|
== <logout>
|
|
The `<logout>` element adds a `LogoutFilter` to the filter stack.
|
|
It is configured by a `SecurityContextLogoutHandler`.
|
|
|
|
|
|
|
|
[[nsa-logout-parents]]
|
|
=== Parent Elements of <logout>
|
|
|
|
|
|
The parent element of the `<logout>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
|
|
[[nsa-logout-attributes]]
|
|
=== <logout> Attributes
|
|
|
|
The `<logout>` element has the following attributes:
|
|
|
|
[[nsa-logout-delete-cookies]]
|
|
`delete-cookies`::
|
|
A comma-separated list of the names of cookies that should be deleted when the user logs out.
|
|
|
|
|
|
[[nsa-logout-invalidate-session]]
|
|
`invalidate-session`::
|
|
Maps to the `invalidateHttpSession` of the `SecurityContextLogoutHandler`.
|
|
Default: `true` (the session is invalidated on logout)
|
|
|
|
|
|
[[nsa-logout-logout-success-url]]
|
|
`logout-success-url`::
|
|
The destination URL to which the user is taken after logging out.
|
|
|
|
+
|
|
|
|
Setting this attribute injects the `SessionManagementFilter` with a `SimpleRedirectInvalidSessionStrategy` configured with the attribute value.
|
|
When an invalid session ID is submitted, the strategy is invoked, redirecting to the configured URL.
|
|
|
|
|
|
[[nsa-logout-logout-url]]
|
|
`logout-url`::
|
|
The URL that causes a logout (which is processed by the filter).
|
|
Default: `/logout`
|
|
|
|
|
|
[[nsa-logout-success-handler-ref]]
|
|
`success-handler-ref`::
|
|
Can be used to supply an instance of `LogoutSuccessHandler` that is invoked to control the navigation after logging out.
|
|
|
|
|
|
[[nsa-openid-login]]
|
|
== <openid-login>
|
|
The `<openid-login>` element is similar to the `<form-login>` element and has the same attributes.
|
|
The default value for `login-processing-url` is `/login/openid`.
|
|
An `OpenIDAuthenticationFilter` and a `OpenIDAuthenticationProvider` are registered.
|
|
The latter requires a reference to a `UserDetailsService`.
|
|
You can specify this reference by `id`, by using the `user-service-ref` attribute, or you can let it be automatically located in the application context.
|
|
|
|
|
|
[[nsa-openid-login-parents]]
|
|
=== Parent Elements of <openid-login>
|
|
|
|
The parent element of the `<openid-login>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
[[nsa-openid-login-attributes]]
|
|
=== <openid-login> Attributes
|
|
|
|
The `<openid-login>` element has the following attributes:
|
|
|
|
[[nsa-openid-login-always-use-default-target]]
|
|
`always-use-default-target`::
|
|
Whether the user should always be redirected to the `default-target-url` after login.
|
|
|
|
|
|
[[nsa-openid-login-authentication-details-source-ref]]
|
|
`authentication-details-source-ref`::
|
|
Reference to an `AuthenticationDetailsSource` that is used by the authentication filter.
|
|
|
|
|
|
[[nsa-openid-login-authentication-failure-handler-ref]]
|
|
`authentication-failure-handler-ref`::
|
|
Reference to an `AuthenticationFailureHandler` bean that should be used to handle a failed authentication request.
|
|
It should not be used in combination with `authentication-failure-url`, as the implementation should always deal with navigation to the subsequent destination.
|
|
|
|
|
|
[[nsa-openid-login-authentication-failure-url]]
|
|
authentication-failure-url::
|
|
The URL for the login failure page.
|
|
If no login failure URL is specified, Spring Security automatically creates a failure login URL at `/login?login_error` and a corresponding filter to render that login failure URL when requested.
|
|
|
|
|
|
[[nsa-openid-login-authentication-success-forward-url]]
|
|
authentication-success-forward-url::
|
|
Maps a `ForwardAuthenticationSuccessHandler` to `authenticationSuccessHandler` property of `UsernamePasswordAuthenticationFilter`.
|
|
|
|
|
|
[[nsa-openid-login-authentication-failure-forward-url]]
|
|
`authentication-failure-forward-url`::
|
|
Maps a `ForwardAuthenticationFailureHandler` to `authenticationFailureHandler` property of `UsernamePasswordAuthenticationFilter`.
|
|
|
|
|
|
[[nsa-openid-login-authentication-success-handler-ref]]
|
|
`authentication-success-handler-ref`::
|
|
Reference to an `AuthenticationSuccessHandler` bean that should be used to handle a successful authentication request.
|
|
Should not be used in combination with <<nsa-openid-login-default-target-url,default-target-url>> (or <<nsa-openid-login-always-use-default-target,`always-use-default-target`>>) as the implementation should always deal with navigation to the subsequent destination
|
|
|
|
|
|
[[nsa-openid-login-default-target-url]]
|
|
`default-target-url`::
|
|
The URL to which to redirect 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, it defaults to the root of the application.
|
|
|
|
|
|
[[nsa-openid-login-login-page]]
|
|
`login-page`::
|
|
The URL for the login page.
|
|
If no login URL is specified, Spring Security automatically creates a login URL at `/login` and a corresponding filter to render that login URL when requested.
|
|
|
|
[[nsa-openid-login-login-processing-url]]
|
|
`login-processing-url`::
|
|
The URL to which the login form is posted.
|
|
If unspecified, it defaults to `/login`.
|
|
|
|
|
|
[[nsa-openid-login-password-parameter]]
|
|
`password-parameter`::
|
|
The name of the request parameter that contains the password.
|
|
Default: `password`
|
|
|
|
|
|
[[nsa-openid-login-user-service-ref]]
|
|
`user-service-ref`::
|
|
A reference to a user-service (or `UserDetailsService` bean) ID
|
|
|
|
|
|
[[nsa-openid-login-username-parameter]]
|
|
`username-parameter`::
|
|
The name of the request parameter that contains the username.
|
|
Default: `username`
|
|
|
|
|
|
[[nsa-openid-login-children]]
|
|
=== Child Elements of <openid-login>
|
|
The `<openid-login>` element has only one child attribute: <<nsa-attribute-exchange,attribute-exchange>>.
|
|
|
|
|
|
|
|
[[nsa-attribute-exchange]]
|
|
== <attribute-exchange>
|
|
The `<attribute-exchange>` element defines the list of attributes to request from the identity provider.
|
|
You can find an example in the xref:servlet/authentication/openid.adoc#servlet-openid[OpenID Support] section of the namespace configuration chapter.
|
|
You can use more than one. In that case, each must have an `identifier-match` attribute that contains a regular expression, which is matched against the supplied OpenID identifier.
|
|
This lets different attribute lists be fetched from different providers (Google, Yahoo, and others).
|
|
|
|
|
|
[[nsa-attribute-exchange-parents]]
|
|
=== Parent Elements of <attribute-exchange>
|
|
|
|
The parent element of the `<attribute-exchange>` element is the <<nsa-openid-login,openid-login>> element.
|
|
|
|
[[nsa-attribute-exchange-attributes]]
|
|
=== <attribute-exchange> Attributes
|
|
|
|
The `<attribute-exchange>` element has a single attribute:
|
|
|
|
[[nsa-attribute-exchange-identifier-match]]
|
|
`identifier-match`::
|
|
A regular expression that is compared against the claimed identity when deciding which `attribute-exchange` configuration to use during authentication.
|
|
|
|
|
|
[[nsa-attribute-exchange-children]]
|
|
=== Child Elements of <attribute-exchange>
|
|
|
|
|
|
The `<attribute-exchange>` element has a single child attribute: <<nsa-openid-attribute,openid-attribute>>.
|
|
|
|
|
|
[[nsa-openid-attribute]]
|
|
== <openid-attribute>
|
|
The `<openid-attribute>` element defines the attributes to use when making an OpenID AX https://openid.net/specs/openid-attribute-exchange-1_0.html#fetch_request[ Fetch Request].
|
|
|
|
[[nsa-openid-attribute-parents]]
|
|
=== Parent Elements of <openid-attribute>
|
|
|
|
The parent element of the `<openid-attribute>` element is the <<nsa-attribute-exchange,`attribute-exchange`>> element.
|
|
|
|
|
|
[[nsa-openid-attribute-attributes]]
|
|
=== <openid-attribute> Attributes
|
|
|
|
The `<openid-attribute>` element has the following attributes:
|
|
|
|
[[nsa-openid-attribute-count]]
|
|
`count`::
|
|
Specifies the number of attributes that you wish to get back -- for example, return three emails.
|
|
Default: 1
|
|
|
|
|
|
[[nsa-openid-attribute-name]]
|
|
`name`::
|
|
Specifies the name of the attribute that you wish to get back -- for example, `email`.
|
|
|
|
|
|
[[nsa-openid-attribute-required]]
|
|
`required`::
|
|
Specifies whether this attribute is required to the OP but does not error out if the OP does not return the attribute.
|
|
Default: `false`
|
|
|
|
|
|
[[nsa-openid-attribute-type]]
|
|
`type`::
|
|
Specifies the attribute type -- for example, `https://axschema.org/contact/email`.
|
|
See your OP's documentation for valid attribute types.
|
|
|
|
[[nsa-password-management]]
|
|
== <password-management>
|
|
This element configures password management.
|
|
|
|
[[nsa-password-management-parents]]
|
|
=== Parent Elements of <password-management>
|
|
|
|
* <<nsa-http,http>>
|
|
|
|
[[nsa-password-management-attributes]]
|
|
=== <password-management> Attributes
|
|
|
|
[[nsa-password-management-change-password-page]]
|
|
`hange-password-page`::
|
|
The change password page. Defaults to "/change-password".
|
|
|
|
[[nsa-port-mappings]]
|
|
== <port-mappings>
|
|
By default, an instance of `PortMapperImpl` is added to the configuration for use in redirecting to secure and insecure URLs.
|
|
You can optionally use the `<port-mappings>` element to override the default mappings that `PortMapperImpl` defines.
|
|
Each child `<port-mapping>` element defines a pair of HTTP:HTTPS ports.
|
|
The default mappings are `80:443` and `8080:8443`.
|
|
You can find an example of overriding these values in << xref:servlet/exploits/http.adoc#servlet-http-redirect[Redirect to HTTPS].
|
|
|
|
|
|
[[nsa-port-mappings-parents]]
|
|
=== Parent Elements of <port-mappings>
|
|
|
|
|
|
The parent element of the `<port-mappings>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
[[nsa-port-mappings-children]]
|
|
=== Child Elements of <port-mappings>
|
|
|
|
|
|
The `<port-mappings>` element has a single child element: <<nsa-port-mapping,`port-mapping`>>.
|
|
|
|
|
|
[[nsa-port-mapping]]
|
|
== <port-mapping>
|
|
Provides a method to map http ports to https ports when forcing a redirect.
|
|
|
|
|
|
[[nsa-port-mapping-parents]]
|
|
=== Parent Elements of <port-mapping>
|
|
|
|
|
|
The parent element of the `<port-mapping>` element is the <<nsa-port-mappings,port-mappings>> element.
|
|
|
|
|
|
|
|
[[nsa-port-mapping-attributes]]
|
|
=== <port-mapping> Attributes
|
|
|
|
The `<port-mapping>` element has the following attributes:
|
|
|
|
[[nsa-port-mapping-http]]
|
|
`http`::
|
|
The HTTP port to use.
|
|
|
|
|
|
[[nsa-port-mapping-https]]
|
|
`https`::
|
|
The HTTPS port to use.
|
|
|
|
|
|
[[nsa-remember-me]]
|
|
== <remember-me>
|
|
The `<remember-me>` element adds the `RememberMeAuthenticationFilter` to the stack.
|
|
This filter is, in turn, configured with either a `TokenBasedRememberMeServices`, a `PersistentTokenBasedRememberMeServices`, or a user-specified bean that implements `RememberMeServices`, depending on the attribute settings.
|
|
|
|
|
|
[[nsa-remember-me-parents]]
|
|
=== Parent Elements of <remember-me>
|
|
|
|
The parent element of the `<remember-me>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
[[nsa-remember-me-attributes]]
|
|
=== <remember-me> Attributes
|
|
|
|
The `<remember-me>` element has the following attributes:
|
|
|
|
[[nsa-remember-me-authentication-success-handler-ref]]
|
|
`authentication-success-handler-ref`::
|
|
Sets the `authenticationSuccessHandler` property on the `RememberMeAuthenticationFilter` when custom navigation is required.
|
|
The value should be the name of a `AuthenticationSuccessHandler` bean in the application context.
|
|
|
|
|
|
[[nsa-remember-me-data-source-ref]]
|
|
`data-source-ref`::
|
|
A reference to a `DataSource` bean.
|
|
If this attribute is set, `PersistentTokenBasedRememberMeServices` is used and configured with a `JdbcTokenRepositoryImpl` instance.
|
|
|
|
|
|
[[nsa-remember-me-remember-me-parameter]]
|
|
`remember-me-parameter`::
|
|
The name of the request parameter that toggles remember-me authentication.
|
|
Defaults: `remember-me`
|
|
Maps to the `parameter` property of `AbstractRememberMeServices`.
|
|
|
|
|
|
[[nsa-remember-me-remember-me-cookie]]
|
|
`remember-me-cookie`::
|
|
The name of the cookie that stores the token for remember-me authentication.
|
|
Defaults: `remember-me`
|
|
This attribute maps to the `cookieName` property of `AbstractRememberMeServices`.
|
|
|
|
|
|
[[nsa-remember-me-key]]
|
|
`key`::
|
|
Maps to the `key` property of `AbstractRememberMeServices`.
|
|
Should be set to a unique value to ensure that remember-me cookies are valid only within one application
|
|
This key does not affect the use of `PersistentTokenBasedRememberMeServices`, where the tokens are stored on the server side.
|
|
If this key is not set, a secure random value is generated.
|
|
Since generating secure random values can take a while, explicitly setting this value can help improve startup times when you use the remember-me functionality.
|
|
|
|
|
|
[[nsa-remember-me-services-alias]]
|
|
`services-alias`::
|
|
Exports the internally defined `RememberMeServices` as a bean alias, letting it be used by other beans in the application context.
|
|
|
|
|
|
[[nsa-remember-me-services-ref]]
|
|
`services-ref`::
|
|
Allows complete control of the `RememberMeServices` implementation that is used by the filter.
|
|
The value should be the `id` of a bean in the application context that implements this interface.
|
|
It should also implement `LogoutHandler` if a logout filter is in use.
|
|
|
|
|
|
[[nsa-remember-me-token-repository-ref]]
|
|
`token-repository-ref`::
|
|
Configures a `PersistentTokenBasedRememberMeServices` but allows the use of a custom `PersistentTokenRepository` bean.
|
|
|
|
|
|
[[nsa-remember-me-token-validity-seconds]]
|
|
`token-validity-seconds`::
|
|
Maps to the `tokenValiditySeconds` property of `AbstractRememberMeServices`.
|
|
Specifies the period in seconds for which the remember-me cookie should be valid.
|
|
By default, it is valid for 14 days.
|
|
|
|
|
|
[[nsa-remember-me-use-secure-cookie]]
|
|
`use-secure-cookie`::
|
|
We recommend that you submit remember-me cookies over HTTPS and that you flag as "`secure`".
|
|
By default, a secure cookie is used if the connection for the login request is secure (as it should be).
|
|
If you set this property to `false`, secure cookies are not used.
|
|
Setting it to `true` always sets the secure flag on the cookie.
|
|
This attribute maps to the `useSecureCookie` property of `AbstractRememberMeServices`.
|
|
|
|
|
|
[[nsa-remember-me-user-service-ref]]
|
|
`user-service-ref`::
|
|
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 is selected and automatically used by the namespace configuration.
|
|
If there are multiple instances, you can specify a bean `id` explicitly by setting this attribute.
|
|
|
|
|
|
[[nsa-request-cache]]
|
|
== <request-cache> Element
|
|
Sets the `RequestCache` instance, which is used by the `ExceptionTranslationFilter` to store request information before invoking an `AuthenticationEntryPoint`.
|
|
|
|
[[nsa-request-cache-parents]]
|
|
=== Parent Elements of <request-cache>
|
|
|
|
The parent element of the `<request-cache>` element is the <<nsa-http,http>> element.
|
|
|
|
[[nsa-request-cache-attributes]]
|
|
=== <request-cache> Attributes
|
|
|
|
The `<request-cache>` element has only one attribute:
|
|
|
|
[[nsa-request-cache-ref]]
|
|
`ref`::
|
|
Defines a reference to a Spring bean that is a `RequestCache`.
|
|
|
|
|
|
[[nsa-session-management]]
|
|
== <session-management>
|
|
Session-management functionality is implemented by the addition of a `SessionManagementFilter` to the filter stack. This element adds that filter.
|
|
|
|
|
|
[[nsa-session-management-parents]]
|
|
=== Parent Elements of <session-management>
|
|
|
|
The parent element of the `<session-management>` element is the <<nsa-http,http>> element.
|
|
|
|
[[nsa-session-management-attributes]]
|
|
=== <session-management> Attributes
|
|
|
|
The `<session-management>` has the following attributes:
|
|
|
|
[[nsa-session-management-invalid-session-url]]
|
|
`invalid-session-url`::
|
|
Setting this attribute injects a `SessionManagementFilter` with a `SimpleRedirectInvalidSessionStrategy` that is configured with the attribute value.
|
|
When an invalid session ID is submitted, the strategy is invoked, redirecting to the configured URL.
|
|
|
|
[[nsa-session-management-invalid-session-strategy-ref]]
|
|
`invalid-session-url`::
|
|
Allows injection of the `InvalidSessionStrategy` instance, which is used by the `SessionManagementFilter`.
|
|
Use either this attribute or the `invalid-session-url` attribute but not both.
|
|
|
|
[[nsa-session-management-session-authentication-error-url]]
|
|
`session-authentication-error-url`
|
|
Defines the URL of the error page, which should be shown when the `SessionAuthenticationStrategy` raises an exception.
|
|
If not set, an unauthorized (401) error code is returned to the client.
|
|
Note that this attribute does not apply if the error occurs during a form-based login, where the URL for authentication failure takes precedence.
|
|
|
|
|
|
[[nsa-session-management-session-authentication-strategy-ref]]
|
|
`session-authentication-strategy-ref`::
|
|
Allows injection of a `SessionAuthenticationStrategy` instance, which is used by the `SessionManagementFilter`.
|
|
|
|
|
|
[[nsa-session-management-session-fixation-protection]]
|
|
* **session-fixation-protection**
|
|
session-fixation-protection::
|
|
Indicates how session fixation protection is applied when a user authenticates.
|
|
If set to `none`, no protection is applied.
|
|
`newSession` creates a new empty session, with only Spring Security-related attributes migrated.
|
|
`migrateSession` creates a new session and copies all session attributes to the new session.
|
|
In Servlet 3.1 (Java EE 7) and newer containers, specifying `changeSessionId` keeps the existing session and uses the container-supplied session fixation protection (`HttpServletRequest#changeSessionId()`).
|
|
It defaults to `changeSessionId` in Servlet 3.1 and newer containers, `migrateSession` in older containers.
|
|
It 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 {security-api-url}org/springframework/security/web/session/SessionManagementFilter.html[Javadoc for `SessionManagementFilter`] for more details.
|
|
|
|
[[nsa-session-management-children]]
|
|
=== Child Elements of <session-management>
|
|
|
|
The `<session-management>` element has only one child element: <<nsa-concurrency-control,concurrency-control>>
|
|
|
|
|
|
[[nsa-concurrency-control]]
|
|
== <concurrency-control>
|
|
The `<concurrency-control>` adds support for concurrent session control, letting limits be placed on the number of active sessions a user can have.
|
|
A `ConcurrentSessionFilter` is created, and a `ConcurrentSessionControlAuthenticationStrategy` is used with the `SessionManagementFilter`.
|
|
If a `form-login` element has been declared, the strategy object is also injected into the created authentication filter.
|
|
An instance of `SessionRegistry` (a `SessionRegistryImpl` instance unless the user wishes to use a custom bean) is created for use by the strategy.
|
|
|
|
|
|
[[nsa-concurrency-control-parents]]
|
|
=== Parent Elements of <concurrency-control>
|
|
|
|
|
|
The parent element of the `<concurrency-control>` element is the <<nsa-session-management,session-management>> element.
|
|
|
|
|
|
|
|
[[nsa-concurrency-control-attributes]]
|
|
=== <concurrency-control> Attributes
|
|
|
|
The `<concurrency-control>` element has the following attributes:
|
|
|
|
[[nsa-concurrency-control-error-if-maximum-exceeded]]
|
|
`error-if-maximum-exceeded`::
|
|
If set to `true`, a `SessionAuthenticationException` is raised when a user attempts to exceed the maximum allowed number of sessions.
|
|
The default behavior is to expire the original session.
|
|
|
|
|
|
[[nsa-concurrency-control-expired-url]]
|
|
`expired-url`::
|
|
The URL to which a user is redirected 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.
|
|
This attribute should be set unless `exception-if-maximum-exceeded` is set.
|
|
If no value is supplied, an expiry message is written directly back to the response.
|
|
|
|
[[nsa-concurrency-control-expired-session-strategy-ref]]
|
|
`expired-session-strategy-ref`::
|
|
Allows injection of an `ExpiredSessionStrategy` instance, which is used by the `ConcurrentSessionFilter`.
|
|
|
|
[[nsa-concurrency-control-max-sessions]]
|
|
`max-sessions`::
|
|
Maps to the `maximumSessions` property of `ConcurrentSessionControlAuthenticationStrategy`.
|
|
Specify `-1` as the value to support unlimited sessions.
|
|
|
|
|
|
[[nsa-concurrency-control-session-registry-alias]]
|
|
`session-registry-alias`::
|
|
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.
|
|
|
|
|
|
[[nsa-concurrency-control-session-registry-ref]]
|
|
`session-registry-ref`::
|
|
Specifies a `SessionRegistry` implementation to use.
|
|
The other concurrent session control beans are wired up to use it.
|
|
|
|
|
|
[[nsa-x509]]
|
|
== <x509>
|
|
The `<x509>` element adds support for X.509 authentication.
|
|
An `X509AuthenticationFilter` is added to the stack, and an `Http403ForbiddenEntryPoint` bean is created.
|
|
The latter is used only if no other authentication mechanisms are in use. (Its only functionality is to return an HTTP 403 error code.)
|
|
A `PreAuthenticatedAuthenticationProvider` is also created. It delegates the loading of user authorities to a `UserDetailsService`.
|
|
|
|
|
|
[[nsa-x509-parents]]
|
|
=== Parent Elements of <x509>
|
|
|
|
The parent element of the `<x509>` element is the <<nsa-http,http>> element.
|
|
|
|
|
|
[[nsa-x509-attributes]]
|
|
=== <x509> Attributes
|
|
|
|
The `<x509>` element has the following attributes:
|
|
|
|
[[nsa-x509-authentication-details-source-ref]]
|
|
`authentication-details-source-ref`::
|
|
A reference to an `AuthenticationDetailsSource`.
|
|
|
|
|
|
[[nsa-x509-subject-principal-regex]]
|
|
`subject-principal-regex`::
|
|
Defines a regular expression, which is used to extract the username from the certificate (for use with the `UserDetailsService`).
|
|
|
|
|
|
[[nsa-x509-user-service-ref]]
|
|
`user-service-ref`::
|
|
Lets a specific `UserDetailsService` be used with X.509 when where multiple instances are configured.
|
|
If not set, an attempt is made to locate a suitable instance automatically and use that.
|
|
|
|
|
|
[[nsa-filter-chain-map]]
|
|
== <filter-chain-map>
|
|
The `<filter-chain-map>` explicitly configures a `FilterChainProxy` instance with a `FilterChainMap`.
|
|
|
|
|
|
[[nsa-filter-chain-map-attributes]]
|
|
=== <filter-chain-map> Attributes
|
|
|
|
The `<filter-chain-map>` element has one attribute:
|
|
|
|
[[nsa-filter-chain-map-request-matcher]]
|
|
`request-matcher`::
|
|
Defines the strategy to 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).
|
|
|
|
[[nsa-filter-chain-map-children]]
|
|
=== Child Elements of <filter-chain-map>
|
|
|
|
The `<filter-chain-map>` element has one child element: <<nsa-filter-chain,filter-chain>>.
|
|
|
|
[[nsa-filter-chain]]
|
|
== <filter-chain>
|
|
The `<filter-chain>` element is used within a `<filter-chain-map>` to define a specific URL pattern and the list of filters that apply to the URLs that match that pattern.
|
|
When multiple `<filter-chain>` elements are assembled in a list, to configure a `FilterChainProxy`, the most specific patterns must be placed at the top of the list, with the most general ones at the bottom.
|
|
|
|
|
|
[[nsa-filter-chain-parents]]
|
|
=== Parent Elements of <filter-chain>
|
|
|
|
The parent element of the `<filter-chain>` element is the <<nsa-filter-chain-map,filter-chain-map>> element.
|
|
|
|
|
|
[[nsa-filter-chain-attributes]]
|
|
=== <filter-chain> Attributes
|
|
|
|
The `<filter-chain>` element has the following attributes:
|
|
|
|
[[nsa-filter-chain-filters]]
|
|
`filters`::
|
|
A comma-separated list of references to Spring beans that implement `Filter`.
|
|
A value of `none` means that no `Filter` should be used for this `FilterChain`.
|
|
|
|
|
|
[[nsa-filter-chain-pattern]]
|
|
`pattern`::
|
|
A pattern that creates `RequestMatcher` in combination with the <<nsa-filter-chain-map-request-matcher,request-matcher>> element.
|
|
|
|
|
|
[[nsa-filter-chain-request-matcher-ref]]
|
|
`request-matcher-ref`::
|
|
A reference to a `RequestMatcher` that is used to determine if any `Filter` from the `filters` attribute should be invoked.
|
|
|
|
|
|
[[nsa-filter-security-metadata-source]]
|
|
== <filter-security-metadata-source>
|
|
The `<filter-security-metadata-source>` is used to explicitly configure a `FilterSecurityMetadataSource` bean for use with a `FilterSecurityInterceptor`.
|
|
The `<filter-security-metadata-source>` is usually only needed if you explicitly configure a `FilterChainProxy` rather than use the `<http>` element.
|
|
The `<intercept-url>` elements should contain only pattern, method, and access attributes.
|
|
Any others result in a configuration error.
|
|
|
|
|
|
[[nsa-filter-security-metadata-source-attributes]]
|
|
=== <filter-security-metadata-source> Attributes
|
|
|
|
The `<filter-security-metadata-source>` element has the following attributes:
|
|
|
|
[[nsa-filter-security-metadata-source-id]]
|
|
`id`::
|
|
A bean identifier, which is used for referring to the bean elsewhere in the context.
|
|
|
|
|
|
[[nsa-filter-security-metadata-source-request-matcher]]
|
|
`request-matcher`::
|
|
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).
|
|
|
|
|
|
[[nsa-filter-security-metadata-source-use-expressions]]
|
|
use-expressions::
|
|
Enables the use of expressions in the `access` attributes in `<intercept-url>` elements rather than the traditional list of configuration attributes.
|
|
Default: `true`
|
|
If enabled, each attribute should contain a single Boolean expression.
|
|
If the expression evaluates to `true`, access is granted.
|
|
|
|
|
|
[[nsa-filter-security-metadata-source-children]]
|
|
=== Child Elements of <filter-security-metadata-source>
|
|
|
|
|
|
The `<filter-security-metadata-source>` has a single child element: <<nsa-intercept-url,intercept-url>>.
|