Polish Authentication

docs/manual/src/docs/asciidoc/_includes/reactive/rsocket.adoc

@@ -32,7 +32,7 @@ public class HelloRSocketSecurityConfig {
 }
 -----
 
-This configuration enables <<rsocket-authentication-simple,simple authentication>> and sets up <<authorization,rsocket-authorization>> to require an authenticated user for any request.
+This configuration enables <<rsocket-authentication-simple,simple authentication>> and sets up <<rsocket-authorization,rsocket-authorization>> to require an authenticated user for any request.
 
 == Adding SecuritySocketAcceptorInterceptor
 

docs/manual/src/docs/asciidoc/_includes/reactive/x509.adoc

@@ -1,7 +1,7 @@
 [[reactive-x509]]
 = Reactive X.509 Authentication
 
-Similar to <<x509,Servlet X.509 authentication>>, reactive x509 authentication filter allows extracting an authentication token from a certificate provided by a client.
+Similar to <<servlet-x509,Servlet X.509 authentication>>, reactive x509 authentication filter allows extracting an authentication token from a certificate provided by a client.
 
 Below is an example of a reactive x509 security configuration:
 [source,java]

docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc

@@ -1536,7 +1536,7 @@ Defaults to "username".
 [[nsa-attribute-exchange]]
 ==== <attribute-exchange>
 The `attribute-exchange` element defines the list of attributes which should be requested from the identity provider.
-An example can be found in the <<ns-openid,OpenID Support>> section of the namespace configuration chapter.
+An example can be found in the <<servlet-openid,OpenID Support>> section of the namespace configuration chapter.
 More than one can be used, in which case each must have an `identifier-match` attribute, containing a regular expression which is matched against the supplied OpenID identifier.
 This allows different attribute lists to be fetched from different providers (Google, Yahoo etc).
 

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc

@@ -1,11 +1,11 @@
 [[servlet-delegatingfilterproxy]]
 = DelegatingFilterProxy
 
-Spring provides a `Filter` implementation named `DelegatingFilterProxy` that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
+Spring provides a `Filter` implementation named {security-api-url}org/springframework/web/filter/DelegatingFilterProxy.html/[`DelegatingFilterProxy`] that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
 The Servlet container allows registering ``Filter``s using its own standards, but it is not aware of Spring defined Beans.
 `DelegatingFilterProxy` can be registered via standard Servlet container mechanisms, but delegate all the work to a Spring Bean that implements `Filter`.
 
-Here is a picture of how `DelegatingFilterProxy` fits into the <<servlet-filterchain-figure>>.
+Here is a picture of how `DelegatingFilterProxy` fits into the <<servlet-filters-review,``Filter``s and the `FilterChain`>>.
 
 .DelegatingFilterProxy
 [[servlet-delegatingfilterproxy-figure]]

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/index.adoc

@@ -1,10 +1,9 @@
 [[servlet-architecture]]
-= Architecture and Implementation
-// FIXME: change to something like Servlet Security: The Big Picture
+= Servlet Security: The Big Picture
 :figures: images/servlet/architecture
 
 This section discusses Spring Security's high level architecture within Servlet based applications.
-We build on this high level understanding within each section of the reference.
+We build on this high level understanding within <<servlet-authentication>>, <<servlet-authorization>>, <<servlet-exploits>> sections of the reference.
 // FIXME: Add links to other sections of architecture
 
 include::filters.adoc[leveloffset=+1]

docs/manual/src/docs/asciidoc/_includes/servlet/architecture/security-filters.adoc

@@ -23,14 +23,14 @@ Below is a comprehensive list of Spring Security Filter ordering:
 * CasAuthenticationFilter
 * OAuth2LoginAuthenticationFilter
 * Saml2WebSsoAuthenticationFilter
-* UsernamePasswordAuthenticationFilter
+* <<servlet-authentication-usernamepasswordauthenticationfilter,`UsernamePasswordAuthenticationFilter`>>
 * ConcurrentSessionFilter
 * OpenIDAuthenticationFilter
 * DefaultLoginPageGeneratingFilter
 * DefaultLogoutPageGeneratingFilter
-* DigestAuthenticationFilter
+* <<servlet-authentication-digest,`DigestAuthenticationFilter`>>
 * BearerTokenAuthenticationFilter
-* BasicAuthenticationFilter
+* <<servlet-authentication-basic,`BasicAuthenticationFilter`>>
 * RequestCacheAwareFilter
 * SecurityContextHolderAwareRequestFilter
 * JaasApiIntegrationFilter

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/abstract-authentication-processing-filter.adoc

@@ -12,11 +12,9 @@ image::{figures}/abstractauthenticationprocessingfilter.png[]
 
 image:{icondir}/number_1.png[] When the user submits their credentials, the `AbstractAuthenticationProcessingFilter` creates an <<servlet-authentication-authentication,`Authentication`>> from the `HttpServletRequest` to be authenticated.
 The type of `Authentication` created depends on the subclass of `AbstractAuthenticationProcessingFilter`.
-For example, `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` from a __username__ and __password__ that are submitted in the `HttpServletRequest`.
-// FIXME: link UsernamePasswordAuthenticationFilter
+For example, <<servlet-authentication-usernamepasswordauthenticationfilter,`UsernamePasswordAuthenticationFilter`>> creates a `UsernamePasswordAuthenticationToken` from a __username__ and __password__ that are submitted in the `HttpServletRequest`.
 
-image:{icondir}/number_2.png[] Next, the `Authentication` is passed into the `AuthenticationManager` to be authenticated.
-// FIXME: link to AuthenticationManager
+image:{icondir}/number_2.png[] Next, the <<servlet-authentication-authentication,`Authentication`>> is passed into the <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> to be authenticated.
 
 image:{icondir}/number_3.png[] If authentication fails, then __Failure__
 

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-entry-point.adoc

@@ -9,6 +9,6 @@ In these cases, Spring Security does not need to provide an HTTP response that r
 
 In other cases, a client will make an unauthenticated request to a resource that they are not authorized to access.
 In this case, an implementation of `AuthenticationEntryPoint` is used to request credentials from the client.
-The `AuthenticationEntryPoint` implementation might perform a <<servlet-authentication-form,redirect to a log in page>>, respond with an https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate[WWW-Authenticate] header, etc.
+The `AuthenticationEntryPoint` implementation might perform a <<servlet-authentication-form,redirect to a log in page>>, respond with an <<servlet-authentication-basic,WWW-Authenticate>> header, etc.
 
 

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-manager.adoc

@@ -2,9 +2,8 @@
 = AuthenticationManager
 
 {security-api-url}org/springframework/security/authentication/AuthenticationManager.html[`AuthenticationManager`] is the API that defines how Spring Security's Filters perform  <<authentication,authentication>>.
-The `Authentication` that is returned is then set on the <<servlet-authentication-securitycontextholder>>.
-If you are not integrating with <<servlet-filterchainproxy,Spring Security's ``Filters``s>>, you can set the `SecurityContextHolder` directly and are not required to use an `AuthenticationManager`.
+The <<servlet-authentication-authentication,`Authentication`>> that is returned is then set on the <<servlet-authentication-securitycontextholder>> by the controller (i.e. <<servlet-security-filters,Spring Security's ``Filters``s>>) that invoked the `AuthenticationManager`.
+If you are not integrating with __Spring Security's ``Filters``s__ you can set the `SecurityContextHolder` directly and are not required to use an `AuthenticationManager`.
 
 While the implementation of `AuthenticationManager` could be anything, the most common implementation is <<servlet-authentication-providermanager,`ProviderManager`>>.
-// FIXME: link to ProviderManager
 // FIXME: add configuration

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication-provider.adoc

@@ -3,4 +3,4 @@
 
 Multiple {security-api-url}org/springframework/security/authentication/AuthenticationProvider.html[``AuthenticationProvider``s] can be injected into <<servlet-authentication-providermanager,`ProviderManager`>>.
 Each `AuthenticationProvider` performs a specific type of authentication.
-For example, `DaoAuthenticationProvider` supports username/password based authentication while `JwtAuthenticationProvider` supports authenticating a JWT token.
+For example, <<servlet-authentication-daoauthenticationprovider,`DaoAuthenticationProvider`>> supports username/password based authentication while `JwtAuthenticationProvider` supports authenticating a JWT token.

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/authentication.adoc

@@ -3,7 +3,7 @@
 
 The {security-api-url}org/springframework/security/core/Authentication.html[`Authentication`] serves two main purposes within Spring Security:
 
-* An input to `AuthenticationManager` to provide the credentials a user has provided to authenticate.
+* An input to <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> to provide the credentials a user has provided to authenticate.
 When used in this scenario, `isAuthenticated()` returns `false`.
 * Represents the currently authenticated user.
 The current `Authentication` can be obtained from the <<servlet-authentication-securitycontext>>.
@@ -11,7 +11,7 @@ The current `Authentication` can be obtained from the <<servlet-authentication-s
 The `Authentication` contains:
 
 * `principal` - identifies the user.
-When authenticating with a username/password this is often an instance of `UserDetails`.
+When authenticating with a username/password this is often an instance of <<servlet-authentication-userdetails,`UserDetails`>>.
 * `credentials` - Often a password.
 In many cases this will be cleared after the user is authenticated to ensure it is not leaked.
 * `authorities` - the <<servlet-authentication-granted-authority,``GrantedAuthority``s>> are high level permissions the user is granted.

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/granted-authority.adoc

@@ -1,12 +1,14 @@
 [[servlet-authentication-granted-authority]]
 = GrantedAuthority
-Besides the principal, another important method provided by `Authentication` is `getAuthorities()`.
+{security-api-url}org/springframework/security/core/GrantedAuthority.html[``GrantedAuthority``s] are high level permissions the user is granted. A few examples are roles or scopes.
+
+``GrantedAuthority``s can be obtained from the <<servlet-authentication-authentication,`Authentication.getAuthorities()`>> method.
 This method provides a `Collection` of `GrantedAuthority` objects.
 A `GrantedAuthority` is, not surprisingly, an authority that is granted to the principal.
 Such authorities are usually "roles", such as `ROLE_ADMINISTRATOR` or `ROLE_HR_SUPERVISOR`.
 These roles are later on configured for web authorization, method authorization and domain object authorization.
 Other parts of Spring Security are capable of interpreting these authorities, and expect them to be present.
-`GrantedAuthority` objects are usually loaded by the `UserDetailsService`.
+When using username/password based authentication ``GrantedAuthority``s are usually loaded by the <<servlet-authentication-userdetailsservice,`UserDetailsService`>>.
 
 Usually the `GrantedAuthority` objects are application-wide permissions.
 They are not specific to a given domain object.

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc

@@ -34,7 +34,7 @@ Spring Security does not care what type of `Authentication` implementation is se
 Here we use `TestingAuthenticationToken` because it is very simple.
 A more common production scenario is `UsernamePasswordAuthenticationToken(userDetails, password, authorities)`.
 <3> Finally, we set the `SecurityContext` on the `SecurityContextHolder`.
-Spring Security will use this information for <<authorization>>.
+Spring Security will use this information for <<servlet-authorization,authorization>>.
 
 If you wish to obtain information about the authenticated principal, you can do so by accessing the `SecurityContextHolder`.
 

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/cas.adoc

@@ -1,4 +1,4 @@
-[[cas]]
+[[servlet-cas]]
 == CAS Authentication
 
 [[cas-overview]]

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/index.adoc

@@ -8,8 +8,7 @@ This section discusses:
 *Architecture Components*
 
 This section describes the main architectural components of Spring Security's used in Servlet authentication.
-If you need concrete flows that explain how these pieces fit together, look in specific sections.
-// FIXME: add for example see form login if you want to see more concrete flows.
+If you need concrete flows that explain how these pieces fit together, look at the <<servlet-authentication-mechanisms,Authentication Mechanism>> specific sections.
 
 * <<servlet-authentication-securitycontextholder>> - The `SecurityContextHolder` is where Spring Security stores the details of who is <<authentication,authenticated>>.
 * <<servlet-authentication-securitycontext>> - is obtained from the `SecurityContextHolder` and contains the `Authentication` of the currently authenticated user.
@@ -27,7 +26,16 @@ This also gives a good idea of the high level flow of authentication and how pie
 
 // FIXME: brief description
 
-* <<servlet-authentication-unpwd>> - how to authenticate with a username/password
+* <<servlet-authentication-unpwd,Username and Password>> - how to authenticate with a username/password
+* <<oauth2login,OAuth 2.0 Login>> - OAuth 2.0 Log In with OpenID Connect and non-standard OAuth 2.0 Login (i.e. GitHub)
+* <<saml2,SAML 2.0 Login>> - SAML 2.0 Log In
+* <<servlet-cas,Central Authentication Server (CAS)>> - Central Authentication Server (CAS) Support
+* <<servlet-rememberme, Remember Me>> - How to remember a user past session expiration
+* <<servlet-jaas, JAAS Authentication>> - Authenticate with JAAS
+* <<servlet-openid,OpenID>> - OpenID Authentication (not to be confused with OpenID Connect)
+* <<servlet-preauth>> - Authenticate with an external mechanism such as https://www.siteminder.com/[SiteMinder] or Java EE security but still use Spring Security for authorization and protection against common exploits.
+* <<servlet-x509,X509 Authentication>> - X509 Authentication
+
 // FIXME: Add other mechanisms
 
 // We intentionally do not increase leveloffset, this is just for organization vs document structure

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/jaas.adoc

@@ -1,4 +1,4 @@
-[[jaas]]
+[[servlet-jaas]]
 == Java Authentication and Authorization Service (JAAS) Provider
 
 

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/openid.adoc

@@ -1,4 +1,4 @@
-[[ns-openid]]
+[[servlet-openid]]
 == OpenID Support
 The namespace supports https://openid.net/[OpenID] login either instead of, or in addition to normal form-based login, with a simple change:
 

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/preauth.adoc

@@ -1,4 +1,4 @@
-[[preauth]]
+[[servlet-preauth]]
 == Pre-Authentication Scenarios
 There are situations where you want to use Spring Security for authorization, but the user has already been reliably authenticated by some external system prior to accessing the application.
 We refer to these situations as "pre-authenticated" scenarios.
@@ -19,7 +19,7 @@ In some cases, the external mechanism may supply role/authority information for
 === Pre-Authentication Framework Classes
 Because most pre-authentication mechanisms follow the same pattern, Spring Security has a set of classes which provide an internal framework for implementing pre-authenticated authentication providers.
 This removes duplication and allows new implementations to be added in a structured fashion, without having to write everything from scratch.
-You don't need to know about these classes if you want to use something like <<x509,X.509 authentication>>, as it already has a namespace configuration option which is simpler to use and get started with.
+You don't need to know about these classes if you want to use something like <<servlet-x509,X.509 authentication>>, as it already has a namespace configuration option which is simpler to use and get started with.
 If you need to use explicit bean configuration or are planning on writing your own implementation then an understanding of how the provided implementations work will be useful.
 You will find classes under the `org.springframework.security.web.authentication.preauth`.
 We just provide an outline here so you should consult the Javadoc and source where appropriate.
@@ -81,7 +81,7 @@ It always returns a `403`-forbidden response code if called.
 
 
 === Concrete Implementations
-X.509 authentication is covered in its <<x509,own chapter>>.
+X.509 authentication is covered in its <<servlet-x509,own chapter>>.
 Here we'll look at some classes which provide support for other pre-authenticated scenarios.
 
 

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc

@@ -1,5 +1,4 @@
-[[remember-me]]
-[[ns-remember-me]]
+[[servlet-rememberme]]
 == Remember-Me Authentication
 
 

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/storage/index.adoc

@@ -1,25 +0,0 @@
-[[servlet-authentication-unpwd-storage]]
-= User Storage
-
-Spring Security's <<servlet-authentication-userdetailsservice,`UserDetailsService`>> allows for storing user information when authenticating by comparing a username password.
-A configured `UserDetailsService` is used by Spring Security when it is configured to <<servlet-authentication-unpwd-input,accept a username/password>> for authentication.
-
-// FIXME: Once it is retrieved it is validated using DaoAuthenticationProvider
-
-Spring Security provides support for storing user information with the following stores:
-
-* Simple Storage with <<servlet-authentication-inmemory>>
-* Relational Databases with <<servlet-authentication-jdbc>>
-* LDAP Servers with <<servlet-authentication-ldap>>
-* Custom data stores with <<servlet-authentication-userdetailsservice>>
-
-include::in-memory.adoc[leveloffset=+1]
-
-include::jdbc.adoc[leveloffset=+1]
-
-include::ldap.adoc[leveloffset=+1]
-
-include::user-details-service.adoc[leveloffset=+1]
-
-
-// FIXME: UserDetailsManager

docs/manual/src/docs/asciidoc/_includes/servlet/authentication/x509.adoc

@@ -1,4 +1,4 @@
-[[x509]]
+[[servlet-x509]]
 == X.509 Authentication
 
 

docs/manual/src/docs/asciidoc/_includes/servlet/authorization/authorize-requests.adoc

@@ -3,9 +3,9 @@
 :figures: images/servlet/authorization
 :icondir: images/icons
 
-This section builds on <<servlet-architecture,Servlet Architecture and Implementation>> by digging deeper into how <<authorization>> works within Servlet based applications.
+This section builds on <<servlet-architecture,Servlet Architecture and Implementation>> by digging deeper into how <<servlet-authorization,authorization>> works within Servlet based applications.
 
-The {security-api-url}org/springframework/security/web/access/intercept/FilterSecurityInterceptor.html[`FilterSecurityInterceptor`] provides <<authorization>> for ``HttpServletRequest``s.
+The {security-api-url}org/springframework/security/web/access/intercept/FilterSecurityInterceptor.html[`FilterSecurityInterceptor`] provides <<servlet-authorization,authorization>> for ``HttpServletRequest``s.
 It is inserted into the <<servlet-filterchainproxy>> as one of the <<servlet-security-filters>>.
 
 .Authorize HttpServletRequest

docs/manual/src/docs/asciidoc/_includes/servlet/authorization/index.adoc

@@ -1,4 +1,4 @@
-[[authorization]]
+[[servlet-authorization]]
 = Authorization
 The advanced authorization capabilities within Spring Security represent one of the most compelling reasons for its popularity.
 Irrespective of how you choose to authenticate - whether using a Spring Security-provided mechanism and provider, or integrating with a container or other non-Spring Security authentication authority - you will find the authorization services can be used within your application in a consistent and simple way.

docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc

@@ -1,3 +1,4 @@
+[[servlet-exploits]]
 = Protection Against Exploits
 
 include::csrf.adoc[leveloffset=+1]