Remove include servlet/saml2/index.adoc

docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc

@@ -1,5 +1,5 @@
 [[concurrency]]
-== Concurrency Support
+= Concurrency Support
 
 In most environments, Security is stored on a per `Thread` basis.
 This means that when work is done on a new `Thread`, the `SecurityContext` is lost.
@@ -7,7 +7,7 @@ Spring Security provides some infrastructure to help make this much easier for u
 Spring Security provides low level abstractions for working with Spring Security in multi-threaded environments.
 In fact, this is what Spring Security builds on to integration with <<servletapi-start-runnable>> and <<mvc-async>>.
 
-=== DelegatingSecurityContextRunnable
+== DelegatingSecurityContextRunnable
 
 One of the most fundamental building blocks within Spring Security's concurrency support is the `DelegatingSecurityContextRunnable`.
 It wraps a delegate `Runnable` in order to initialize the `SecurityContextHolder` with a specified `SecurityContext` for the delegate.
@@ -122,7 +122,7 @@ Thread(wrappedRunnable).start()
 The code we have is simple to use, but it still requires knowledge that we are using Spring Security.
 In the next section we will take a look at how we can utilize `DelegatingSecurityContextExecutor` to hide the fact that we are using Spring Security.
 
-=== DelegatingSecurityContextExecutor
+== DelegatingSecurityContextExecutor
 
 In the previous section we found that it was easy to use the `DelegatingSecurityContextRunnable`, but it was not ideal since we had to be aware of Spring Security in order to use it.
 Let's take a look at how `DelegatingSecurityContextExecutor` can shield our code from any knowledge that we are using Spring Security.
@@ -244,7 +244,7 @@ val executor = DelegatingSecurityContextExecutor(delegateExecutor)
 Now anytime `executor.execute(Runnable)` is executed the `SecurityContext` is first obtained by the `SecurityContextHolder` and then that `SecurityContext` is used to create our `DelegatingSecurityContextRunnable`.
 This means that we are running our `Runnable` with the same user that was used to invoke the `executor.execute(Runnable)` code.
 
-=== Spring Security Concurrency Classes
+== Spring Security Concurrency Classes
 
 Refer to the Javadoc for additional integrations with both the Java concurrent APIs and the Spring Task abstractions.
 They are quite self-explanatory once you understand the previous code.

docs/modules/ROOT/pages/servlet/integrations/cors.adoc

@@ -1,5 +1,5 @@
 [[cors]]
-== CORS
+= CORS
 
 Spring Framework provides https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-cors[first class support for CORS].
 CORS must be processed before Spring Security because the pre-flight request will not contain any cookies (i.e. the `JSESSIONID`).

docs/modules/ROOT/pages/servlet/integrations/data.adoc

@@ -1,11 +1,11 @@
 [[data]]
-== Spring Data Integration
+= Spring Data Integration
 
 Spring Security provides Spring Data integration that allows referring to the current user within your queries.
 It is not only useful but necessary to include the user in the queries to support paged results since filtering the results afterwards would not scale.
 
 [[data-configuration]]
-=== Spring Data & Spring Security Configuration
+== Spring Data & Spring Security Configuration
 
 To use this support, add `org.springframework.security:spring-security-data` dependency and provide a bean of type `SecurityEvaluationContextExtension`.
 In Java Configuration, this would look like:
@@ -38,7 +38,7 @@ In XML Configuration, this would look like:
 ----
 
 [[data-query]]
-=== Security Expressions within @Query
+== Security Expressions within @Query
 
 Now Spring Security can be used within your queries.
 For example:

docs/modules/ROOT/pages/servlet/integrations/jackson.adoc

@@ -1,5 +1,5 @@
 [[jackson]]
-== Jackson Support
+= Jackson Support
 
 Spring Security provides Jackson support for persisting Spring Security related classes.
 This can improve the performance of serializing Spring Security related classes when working with distributed sessions (i.e. session replication, Spring Session, etc).

docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc

@@ -1,9 +1,9 @@
 [[taglibs]]
-== JSP Tag Libraries
+= JSP Tag Libraries
 Spring Security has its own taglib which provides basic support for accessing security information and applying security constraints in JSPs.
 
 
-=== Declaring the Taglib
+== Declaring the Taglib
 To use any of the tags, you must have the security taglib declared in your JSP:
 
 [source,xml]
@@ -12,7 +12,7 @@ To use any of the tags, you must have the security taglib declared in your JSP:
 ----
 
 [[taglibs-authorize]]
-=== The authorize Tag
+== The authorize Tag
 This tag is used to determine whether its contents should be evaluated or not.
 In Spring Security 3.0, it can be used in two ways footnote:[
 The legacy options from Spring Security 2.0 are also supported, but discouraged.
@@ -65,7 +65,7 @@ This approach can also be combined with a `method` attribute, supplying the HTTP
 The Boolean result of evaluating the tag (whether it grants or denies access) can be stored in a page context scope variable by setting the `var` attribute to the variable name, avoiding the need for duplicating and re-evaluating the condition at other points in the page.
 
 
-==== Disabling Tag Authorization for Testing
+=== Disabling Tag Authorization for Testing
 Hiding a link in a page for unauthorized users doesn't prevent them from accessing the URL.
 They could just type it into their browser directly, for example.
 As part of your testing process, you may want to reveal the hidden areas in order to check that links really are secured at the back end.
@@ -77,7 +77,7 @@ Try running the "tutorial" sample application with this property enabled, for ex
 You can also set the properties `spring.security.securedUIPrefix` and `spring.security.securedUISuffix` if you want to change surrounding text from the default `span` tags (or use empty strings to remove it completely).
 
 
-=== The authentication Tag
+== The authentication Tag
 This tag allows access to the current `Authentication` object stored in the security context.
 It renders a property of the object directly in the JSP.
 So, for example, if the `principal` property of the `Authentication` is an instance of Spring Security's `UserDetails` object, then using `<sec:authentication property="principal.username" />` will render the name of the current user.
@@ -86,7 +86,7 @@ Of course, it isn't necessary to use JSP tags for this kind of thing and some pe
 You can access the `Authentication` object in your MVC controller (by calling `SecurityContextHolder.getContext().getAuthentication()`) and add the data directly to your model for rendering by the view.
 
 
-=== The accesscontrollist Tag
+== The accesscontrollist Tag
 This tag is only valid when used with Spring Security's ACL module.
 It checks a comma-separated list of required permissions for a specified domain object.
 If the current user has all of those permissions, then the tag body will be evaluated.
@@ -113,7 +113,7 @@ The `Acl` will be invoked with the required permissions to check if all of them
 This tag also supports the `var` attribute, in the same way as the `authorize` tag.
 
 [[taglibs-csrfinput]]
-=== The csrfInput Tag
+== The csrfInput Tag
 If CSRF protection is enabled, this tag inserts a hidden form field with the correct name and value for the CSRF protection token.
 If CSRF protection is not enabled, this tag outputs nothing.
 
@@ -134,7 +134,7 @@ Spring Security handles Spring forms automatically.
 ----
 
 [[taglibs-csrfmeta]]
-=== The csrfMetaTags Tag
+== The csrfMetaTags Tag
 If CSRF protection is enabled, this tag inserts meta tags containing the CSRF protection token form field and header names and CSRF protection token value.
 These meta tags are useful for employing CSRF protection within JavaScript in your applications.
 

docs/modules/ROOT/pages/servlet/integrations/localization.adoc

@@ -1,5 +1,5 @@
 [[localization]]
-== Localization
+= Localization
 Spring Security supports localization of exception messages that end users are likely to see.
 If your application is designed for English-speaking users, you don't need to do anything as by default all Security messages are in English.
 If you need to support other locales, everything you need to know is contained in this section.

docs/modules/ROOT/pages/servlet/integrations/mvc.adoc

@@ -1,11 +1,11 @@
 [[mvc]]
-== Spring MVC Integration
+= Spring MVC Integration
 
 Spring Security provides a number of optional integrations with Spring MVC.
 This section covers the integration in further detail.
 
 [[mvc-enablewebmvcsecurity]]
-=== @EnableWebMvcSecurity
+== @EnableWebMvcSecurity
 
 NOTE: As of Spring Security 4.0, `@EnableWebMvcSecurity` is deprecated.
 The replacement is `@EnableWebSecurity` which will determine adding the Spring MVC features based upon the classpath.
@@ -16,7 +16,7 @@ NOTE: Spring Security provides the configuration using Spring MVC's https://docs
 This means that if you are using more advanced options, like integrating with `WebMvcConfigurationSupport` directly, then you will need to manually provide the Spring Security configuration.
 
 [[mvc-requestmatcher]]
-=== MvcRequestMatcher
+== MvcRequestMatcher
 
 Spring Security provides deep integration with how Spring MVC matches on URLs with `MvcRequestMatcher`.
 This is helpful to ensure your Security rules match the logic used to handle your requests.
@@ -212,7 +212,7 @@ or in XML
 ----
 
 [[mvc-authentication-principal]]
-=== @AuthenticationPrincipal
+== @AuthenticationPrincipal
 
 Spring Security provides `AuthenticationPrincipalArgumentResolver` which can automatically resolve the current `Authentication.getPrincipal()` for Spring MVC arguments.
 By using `@EnableWebSecurity` you will automatically have this added to your Spring MVC configuration.
@@ -448,7 +448,7 @@ open fun findMessagesForUser(@CurrentUser customUser: CustomUser?): ModelAndView
 
 
 [[mvc-async]]
-=== Spring MVC Async Integration
+== Spring MVC Async Integration
 
 Spring Web MVC 3.2+ has excellent support for https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/mvc.html#mvc-ann-async[Asynchronous Request Processing].
 With no additional configuration, Spring Security will automatically setup the `SecurityContext` to the `Thread` that invokes a `Callable` returned by your controllers.
@@ -495,9 +495,9 @@ This is because `DeferredResult` is processed by the users and thus there is no
 However, you can still use <<concurrency,Concurrency Support>> to provide transparent integration with Spring Security.
 
 [[mvc-csrf]]
-=== Spring MVC and CSRF Integration
+== Spring MVC and CSRF Integration
 
-==== Automatic Token Inclusion
+=== Automatic Token Inclusion
 
 Spring Security will automatically <<servlet-csrf-include,include the CSRF Token>> within forms that use the https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/view.html#view-jsp-formtaglib-formtag[Spring MVC form tag].
 For example, the following JSP:
@@ -541,7 +541,7 @@ Will output HTML that is similar to the following:
 ----
 
 [[mvc-csrf-resolver]]
-==== Resolving the CsrfToken
+=== Resolving the CsrfToken
 
 Spring Security provides `CsrfTokenArgumentResolver` which can automatically resolve the current `CsrfToken` for Spring MVC arguments.
 By using <<jc-hello-wsca,@EnableWebSecurity>> you will automatically have this added to your Spring MVC configuration.

docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc

@@ -1,14 +1,14 @@
 [[servletapi]]
-== Servlet API integration
+= Servlet API integration
 This section describes how Spring Security is integrated with the Servlet API.
 
 
 [[servletapi-25]]
-=== Servlet 2.5+ Integration
+== Servlet 2.5+ Integration
 
 
 [[servletapi-remote-user]]
-==== HttpServletRequest.getRemoteUser()
+=== HttpServletRequest.getRemoteUser()
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()[HttpServletRequest.getRemoteUser()] will return the result of `SecurityContextHolder.getContext().getAuthentication().getName()` which is typically the current username.
 This can be useful if you want to display the current username in your application.
 Additionally, checking if this is null can be used to indicate if a user has authenticated or is anonymous.
@@ -16,7 +16,7 @@ Knowing if the user is authenticated or not can be useful for determining if cer
 
 
 [[servletapi-user-principal]]
-==== HttpServletRequest.getUserPrincipal()
+=== HttpServletRequest.getUserPrincipal()
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getUserPrincipal()[HttpServletRequest.getUserPrincipal()] will return the result of `SecurityContextHolder.getContext().getAuthentication()`.
 This means it is an `Authentication` which is typically an instance of `UsernamePasswordAuthenticationToken` when using username and password based authentication.
 This can be useful if you need additional information about your user.
@@ -55,7 +55,7 @@ Instead, one should centralize it to reduce any coupling of Spring Security and
 ====
 
 [[servletapi-user-in-role]]
-==== HttpServletRequest.isUserInRole(String)
+=== HttpServletRequest.isUserInRole(String)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)[HttpServletRequest.isUserInRole(String)] will determine if `SecurityContextHolder.getContext().getAuthentication().getAuthorities()` contains a `GrantedAuthority` with the role passed into `isUserInRole(String)`.
 Typically users should not pass in the "ROLE_" prefix into this method since it is added automatically.
 For example, if you want to determine if the current user has the authority "ROLE_ADMIN", you could use the following:
@@ -78,18 +78,18 @@ This might be useful to determine if certain UI components should be displayed.
 For example, you might display admin links only if the current user is an admin.
 
 [[servletapi-3]]
-=== Servlet 3+ Integration
+== Servlet 3+ Integration
 The following section describes the Servlet 3 methods that Spring Security integrates with.
 
 
 [[servletapi-authenticate]]
-==== HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)
+=== HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#authenticate%28javax.servlet.http.HttpServletResponse%29[HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse)] method can be used to ensure that a user is authenticated.
 If they are not authenticated, the configured AuthenticationEntryPoint will be used to request the user to authenticate (i.e. redirect to the login page).
 
 
 [[servletapi-login]]
-==== HttpServletRequest.login(String,String)
+=== HttpServletRequest.login(String,String)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#login%28java.lang.String,%20java.lang.String%29[HttpServletRequest.login(String,String)] method can be used to authenticate the user with the current `AuthenticationManager`.
 For example, the following would attempt to authenticate with the username "user" and password "password":
 
@@ -121,7 +121,7 @@ It is not necessary to catch the ServletException if you want Spring Security to
 ====
 
 [[servletapi-logout]]
-==== HttpServletRequest.logout()
+=== HttpServletRequest.logout()
 The https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#logout%28%29[HttpServletRequest.logout()] method can be used to log the current user out.
 
 Typically this means that the SecurityContextHolder will be cleared out, the HttpSession will be invalidated, any "Remember Me" authentication will be cleaned up, etc.
@@ -130,7 +130,7 @@ It is important to note that after HttpServletRequest.logout() has been invoked,
 Typically this would involve a redirect to the welcome page.
 
 [[servletapi-start-runnable]]
-==== AsyncContext.start(Runnable)
+=== AsyncContext.start(Runnable)
 The https://docs.oracle.com/javaee/6/api/javax/servlet/AsyncContext.html#start%28java.lang.Runnable%29[AsyncContext.start(Runnable)] method that ensures your credentials will be propagated to the new Thread.
 Using Spring Security's concurrency support, Spring Security overrides the AsyncContext.start(Runnable) to ensure that the current SecurityContext is used when processing the Runnable.
 For example, the following would output the current user's Authentication:
@@ -174,7 +174,7 @@ async.start {
 ====
 
 [[servletapi-async]]
-==== Async Servlet Support
+=== Async Servlet Support
 If you are using Java Based configuration, you are ready to go.
 If you are using XML configuration, there are a few updates that are necessary.
 The first step is to ensure you have updated your web.xml to use at least the 3.0 schema as shown below:
@@ -265,9 +265,9 @@ When Spring Security automatically saved the SecurityContext on committing the H
 Since version 3.2, Spring Security is smart enough to no longer automatically save the SecurityContext on committing the HttpServletResponse as soon as HttpServletRequest.startAsync() is invoked.
 
 [[servletapi-31]]
-=== Servlet 3.1+ Integration
+== Servlet 3.1+ Integration
 The following section describes the Servlet 3.1 methods that Spring Security integrates with.
 
 [[servletapi-change-session-id]]
-==== HttpServletRequest#changeSessionId()
+=== HttpServletRequest#changeSessionId()
 The https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServletRequest.html#changeSessionId()[HttpServletRequest.changeSessionId()] is the default method for protecting against <<ns-session-fixation,Session Fixation>> attacks in Servlet 3.1 and higher.

docs/modules/ROOT/pages/servlet/integrations/websocket.adoc

@@ -1,5 +1,5 @@
 [[websocket]]
-== WebSocket Security
+= WebSocket Security
 
 Spring Security 4 added support for securing https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html[Spring's WebSocket support].
 This section describes how to use Spring Security's WebSocket support.
@@ -12,7 +12,7 @@ Additionally, JSR-356 does not provide a way to intercept messages, so security
 ****
 
 [[websocket-configuration]]
-=== WebSocket Configuration
+== WebSocket Configuration
 
 Spring Security 4.0 has introduced authorization support for WebSockets through the Spring Messaging abstraction.
 To configure authorization using Java Configuration, simply extend the `AbstractSecurityWebSocketMessageBrokerConfigurer` and configure the `MessageSecurityMetadataSourceRegistry`.
@@ -69,7 +69,7 @@ This will ensure that:
 <3> Our messages require the proper authorization. Specifically, any inbound message that starts with "/user/" will require ROLE_USER. Additional details on authorization can be found in <<websocket-authorization>>
 
 [[websocket-authentication]]
-=== WebSocket Authentication
+== WebSocket Authentication
 
 WebSockets reuse the same authentication information that is found in the HTTP request when the WebSocket connection was made.
 This means that the `Principal` on the `HttpServletRequest` will be handed off to WebSockets.
@@ -78,7 +78,7 @@ If you are using Spring Security, the `Principal` on the `HttpServletRequest` is
 More concretely, to ensure a user has authenticated to your WebSocket application, all that is necessary is to ensure that you setup Spring Security to authenticate your HTTP based web application.
 
 [[websocket-authorization]]
-=== WebSocket Authorization
+== WebSocket Authorization
 
 Spring Security 4.0 has introduced authorization support for WebSockets through the Spring Messaging abstraction.
 To configure authorization using Java Configuration, simply extend the `AbstractSecurityWebSocketMessageBrokerConfigurer` and configure the `MessageSecurityMetadataSourceRegistry`.
@@ -168,12 +168,12 @@ This will ensure that:
 <6> Any other message with a destination is rejected. This is a good idea to ensure that you do not miss any messages.
 
 [[websocket-authorization-notes]]
-==== WebSocket Authorization Notes
+=== WebSocket Authorization Notes
 
 In order to properly secure your application it is important to understand Spring's WebSocket support.
 
 [[websocket-authorization-notes-messagetypes]]
-===== WebSocket Authorization on Message Types
+==== WebSocket Authorization on Message Types
 
 It is important to understand the distinction between SUBSCRIBE and MESSAGE types of messages and how it works within Spring.
 
@@ -188,7 +188,7 @@ If we allowed sending a MESSAGE to "/topic/system/notifications", then clients c
 In general, it is common for applications to deny any MESSAGE sent to a destination that starts with the https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-stomp[broker prefix] (i.e. "/topic/" or "/queue/").
 
 [[websocket-authorization-notes-destinations]]
-===== WebSocket Authorization on Destinations
+==== WebSocket Authorization on Destinations
 
 It is also is important to understand how destinations are transformed.
 
@@ -206,7 +206,7 @@ In general, it is common for applications to deny any SUBSCRIBE sent to a messag
 Of course we may provide exceptions to account for things like
 
 [[websocket-authorization-notes-outbound]]
-==== Outbound Messages
+=== Outbound Messages
 
 Spring contains a section titled https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-stomp-message-flow[Flow of Messages] that describes how messages flow through the system.
 It is important to note that Spring Security only secures the `clientInboundChannel`.
@@ -217,13 +217,13 @@ For every message that goes in, there are typically many more that go out.
 Instead of securing the outbound messages, we encourage securing the subscription to the endpoints.
 
 [[websocket-sameorigin]]
-=== Enforcing Same Origin Policy
+== Enforcing Same Origin Policy
 
 It is important to emphasize that the browser does not enforce the https://en.wikipedia.org/wiki/Same-origin_policy[Same Origin Policy] for WebSocket connections.
 This is an extremely important consideration.
 
 [[websocket-sameorigin-why]]
-==== Why Same Origin?
+=== Why Same Origin?
 
 Consider the following scenario.
 A user visits bank.com and authenticates to their account.
@@ -238,13 +238,13 @@ Since SockJS tries to emulate WebSockets it also bypasses the Same Origin Policy
 This means developers need to explicitly protect their applications from external domains when using SockJS.
 
 [[websocket-sameorigin-spring]]
-==== Spring WebSocket Allowed Origin
+=== Spring WebSocket Allowed Origin
 
 Fortunately, since Spring 4.1.5 Spring's WebSocket and SockJS support restricts access to the https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-server-allowed-origins[current domain].
 Spring Security adds an additional layer of protection to provide https://en.wikipedia.org/wiki/Defense_in_depth_(computing)[defence in depth].
 
 [[websocket-sameorigin-csrf]]
-==== Adding CSRF to Stomp Headers
+=== Adding CSRF to Stomp Headers
 
 By default Spring Security requires the <<csrf,CSRF token>> in any CONNECT message type.
 This ensures that only a site that has access to the CSRF token can connect.
@@ -310,7 +310,7 @@ stompClient.connect(headers, function(frame) {
 ----
 
 [[websocket-sameorigin-disable]]
-==== Disable CSRF within WebSockets
+=== Disable CSRF within WebSockets
 
 If you want to allow other domains to access your site, you can disable Spring Security's protection.
 For example, in Java Configuration you can use the following:
@@ -348,13 +348,13 @@ open class WebSocketSecurityConfig : AbstractSecurityWebSocketMessageBrokerConfi
 
 
 [[websocket-sockjs]]
-=== Working with SockJS
+== Working with SockJS
 
 https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-fallback[SockJS] provides fallback transports to support older browsers.
 When using the fallback options we need to relax a few security constraints to allow SockJS to work with Spring Security.
 
 [[websocket-sockjs-sameorigin]]
-==== SockJS & frame-options
+=== SockJS & frame-options
 
 SockJS may use an https://github.com/sockjs/sockjs-client/tree/v0.3.4[transport that leverages an iframe].
 By default Spring Security will <<headers-frame-options,deny>> the site from being framed to prevent Clickjacking attacks.
@@ -418,7 +418,7 @@ open class WebSecurityConfig : WebSecurityConfigurerAdapter() {
 ====
 
 [[websocket-sockjs-csrf]]
-==== SockJS & Relaxing CSRF
+=== SockJS & Relaxing CSRF
 
 SockJS uses a POST on the CONNECT messages for any HTTP based transport.
 Typically we need to include the CSRF token in an HTTP header or an HTTP parameter.