From af4cc03dec8e7c9963d692588d7ba30ff10d7e1a Mon Sep 17 00:00:00 2001 From: Dmitriy Bogdanov Date: Wed, 15 Sep 2021 13:30:06 +0400 Subject: [PATCH] Fix some typos and mistakes in docs --- .../_includes/about/authentication/password-storage.adoc | 2 +- .../src/docs/asciidoc/_includes/about/exploits/csrf.adoc | 2 +- .../docs/asciidoc/_includes/about/exploits/headers.adoc | 2 +- .../src/docs/asciidoc/_includes/about/exploits/http.adoc | 2 +- .../servlet/architecture/delegating-filter-proxy.adoc | 2 +- .../architecture/exception-translation-filter.adoc | 2 +- .../_includes/servlet/authentication/anonymous.adoc | 2 +- .../architecture/security-context-holder.adoc | 2 +- .../asciidoc/_includes/servlet/authentication/logout.adoc | 8 ++++---- .../_includes/servlet/authentication/rememberme.adoc | 2 +- .../asciidoc/_includes/servlet/authentication/runas.adoc | 2 +- .../servlet/authentication/session-management.adoc | 2 +- .../_includes/servlet/authentication/unpwd/basic.adoc | 2 +- .../_includes/servlet/authentication/unpwd/form.adoc | 8 ++++---- .../_includes/servlet/authentication/unpwd/in-memory.adoc | 2 +- .../_includes/servlet/authorization/architecture.adoc | 2 +- .../_includes/servlet/authorization/expression-based.adoc | 4 ++-- .../_includes/servlet/java-configuration/index.adoc | 2 +- .../asciidoc/_includes/servlet/saml2/saml2-login.adoc | 1 + 19 files changed, 26 insertions(+), 25 deletions(-) diff --git a/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc b/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc index 89c62dee7d..94eda55282 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc @@ -295,7 +295,7 @@ java.lang.IllegalArgumentException: There is no PasswordEncoder mapped for the i at org.springframework.security.crypto.password.DelegatingPasswordEncoder.matches(DelegatingPasswordEncoder.java:196) ---- -The easiest way to resolve the error is to switch to explicitly provide the `PasswordEncoder` that you passwords are encoded with. +The easiest way to resolve the error is to switch to explicitly providing the `PasswordEncoder` that your passwords are encoded with. The easiest way to resolve it is to figure out how your passwords are currently being stored and explicitly provide the correct `PasswordEncoder`. If you are migrating from Spring Security 4.2.x you can revert to the previous behavior by <>. diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc b/docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc index 27ba109df9..026faecde6 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/exploits/csrf.adoc @@ -377,7 +377,7 @@ More information about using multipart forms with Spring can be found within the The first option is to include the actual CSRF token in the body of the request. By placing the CSRF token in the body, the body will be read before authorization is performed. This means that anyone can place temporary files on your server. -However, only authorized users will be able to submit a File that is processed by your application. +However, only authorized users will be able to submit a file that is processed by your application. In general, this is the recommended approach because the temporary file upload should have a negligible impact on most servers. [[csrf-considerations-multipart-url]] diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc b/docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc index ba2abd824b..565272a29c 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/exploits/headers.adoc @@ -384,7 +384,7 @@ This is a nice clean-up action to perform on logout. [NOTE] ==== -Refer to the relevant sections to see how to configure both <> based applications. +Refer to the relevant section to see how to configure <> based applications. ==== Spring Security has mechanisms to make it convenient to add the more common security headers to your application. diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc b/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc index 5e5e52d176..44a4e59692 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc @@ -20,7 +20,7 @@ Spring Security provides support for <> == Proxy Server Configuration When using a proxy server it is important to ensure that you have configured your application properly. -For example, many applications will have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080 +For example, many applications will have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080. Without proper configuration, the application server will not know that the load balancer exists and treat the request as though https://192.168.1:8080 was requested by the client. To fix this you can use https://tools.ietf.org/html/rfc7239[RFC 7239] to specify that a load balancer is being used. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc index a05c740bc2..1ccac8c584 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/delegating-filter-proxy.adoc @@ -41,6 +41,6 @@ fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterCh ---- ==== -Another benefit of `DelegatingFilterProxy` is that it allows delaying looking `Filter` bean instances. +Another benefit of `DelegatingFilterProxy` is that it allows delaying looking `Filter` bean instances up. This is important because the container needs to register the `Filter` instances before the container can startup. However, Spring typically uses a `ContextLoaderListener` to load the Spring Beans which will not be done until after the `Filter` instances need to be registered. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/exception-translation-filter.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/exception-translation-filter.adoc index 67cad58ddf..941c1fb122 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/exception-translation-filter.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/exception-translation-filter.adoc @@ -13,7 +13,7 @@ image::{figures}/exceptiontranslationfilter.png[] * image:{icondir}/number_1.png[] First, the `ExceptionTranslationFilter` invokes `FilterChain.doFilter(request, response)` to invoke the rest of the application. * image:{icondir}/number_2.png[] If the user is not authenticated or it is an `AuthenticationException`, then __Start Authentication__. -** The <> is cleared out +** The <> is cleared out. ** The `HttpServletRequest` is saved in the {security-api-url}org/springframework/security/web/savedrequest/RequestCache.html[`RequestCache`]. When the user successfully authenticates, the `RequestCache` is used to replay the original request. // FIXME: add link to authentication success diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/anonymous.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/anonymous.adoc index 8cb386a153..ec2b8aa259 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/anonymous.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/anonymous.adoc @@ -14,7 +14,7 @@ You could also omit these pages from the filter chain entirely, thus bypassing t This is what we mean by anonymous authentication. Note that there is no real conceptual difference between a user who is "anonymously authenticated" and an unauthenticated user. Spring Security's anonymous authentication just gives you a more convenient way to configure your access-control attributes. -Calls to servlet API calls such as `getCallerPrincipal`, for example, will still return null even though there is actually an anonymous authentication object in the `SecurityContextHolder`. +Calls to servlet API such as `getCallerPrincipal`, for example, will still return null even though there is actually an anonymous authentication object in the `SecurityContextHolder`. There are other situations where anonymous authentication is useful, such as when an auditing interceptor queries the `SecurityContextHolder` to identify which principal was responsible for a given operation. Classes can be authored more robustly if they know the `SecurityContextHolder` always contains an `Authentication` object, and never `null`. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc index fa973793a4..60198d48f6 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/architecture/security-context-holder.adoc @@ -86,4 +86,4 @@ Other applications might want to have threads spawned by the secure thread also This is achieved by using `SecurityContextHolder.MODE_INHERITABLETHREADLOCAL`. You can change the mode from the default `SecurityContextHolder.MODE_THREADLOCAL` in two ways. The first is to set a system property, the second is to call a static method on `SecurityContextHolder`. -Most applications won't need to change from the default, but if you do, take a look at the JavaDoc for `SecurityContextHolder` to learn more. +Most applications won't need to change from the default, but if you do, take a look at the Javadoc for `SecurityContextHolder` to learn more. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/logout.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/logout.adoc index c824ffe0ad..7ebb287ac2 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/logout.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/logout.adoc @@ -55,17 +55,17 @@ override fun configure(http: HttpSecurity) { This is automatically applied when using `WebSecurityConfigurerAdapter`. <2> The URL that triggers log out to occur (default is `/logout`). If CSRF protection is enabled (default), then the request must also be a POST. -For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutUrl-java.lang.String-[JavaDoc]. +For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutUrl-java.lang.String-[Javadoc]. <3> The URL to redirect to after logout has occurred. The default is `/login?logout`. -For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessUrl-java.lang.String-[JavaDoc]. +For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessUrl-java.lang.String-[Javadoc]. <4> Let's you specify a custom `LogoutSuccessHandler`. If this is specified, `logoutSuccessUrl()` is ignored. -For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessHandler-org.springframework.security.web.authentication.logout.LogoutSuccessHandler-[JavaDoc]. +For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#logoutSuccessHandler-org.springframework.security.web.authentication.logout.LogoutSuccessHandler-[Javadoc]. <5> Specify whether to invalidate the `HttpSession` at the time of logout. This is *true* by default. Configures the `SecurityContextLogoutHandler` under the covers. -For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#invalidateHttpSession-boolean-[JavaDoc]. +For more information, please consult the {security-api-url}org/springframework/security/config/annotation/web/configurers/LogoutConfigurer.html#invalidateHttpSession-boolean-[Javadoc]. <6> Adds a `LogoutHandler`. `SecurityContextLogoutHandler` is added as the last `LogoutHandler` by default. <7> Allows specifying the names of cookies to be removed on logout success. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc index bcb1422765..e26ca53fa3 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/rememberme.adoc @@ -34,7 +34,7 @@ Notably, this has a potential security issue in that a captured remember-me toke This is the same issue as with digest authentication. If a principal is aware a token has been captured, they can easily change their password and immediately invalidate all remember-me tokens on issue. If more significant security is needed you should use the approach described in the next section. -Alternatively remember-me services should simply not be used at all. +Alternatively, remember-me services should simply not be used at all. If you are familiar with the topics discussed in the chapter on <>, you can enable remember-me authentication just by adding the `` element: diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/runas.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/runas.adoc index 8eb5de89ec..0b439ad369 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/runas.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/runas.adoc @@ -9,7 +9,7 @@ The `RunAsManager` will indicate the replacement `Authentication` object, if any By temporarily replacing the `Authentication` object during the secure object callback phase, the secured invocation will be able to call other objects which require different authentication and authorization credentials. It will also be able to perform any internal security checks for specific `GrantedAuthority` objects. -Because Spring Security provides a number of helper classes that automatically configure remoting protocols based on the contents of the `SecurityContextHolder`, these run-as replacements are particularly useful when calling remote web services +Because Spring Security provides a number of helper classes that automatically configure remoting protocols based on the contents of the `SecurityContextHolder`, these run-as replacements are particularly useful when calling remote web services. [[runas-config]] === Configuration diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/session-management.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/session-management.adoc index 0579d4efae..9cf5c5f6b7 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/session-management.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/session-management.adoc @@ -200,7 +200,7 @@ It will then invoke the configured `SessionAuthenticationStrategy`. If the user is not currently authenticated, the filter will check whether an invalid session ID has been requested (because of a timeout, for example) and will invoke the configured `InvalidSessionStrategy`, if one is set. The most common behaviour is just to redirect to a fixed URL and this is encapsulated in the standard implementation `SimpleRedirectInvalidSessionStrategy`. -The latter is also used when configuring an invalid session URL through the namespace,<>. +The latter is also used when configuring an invalid session URL through the namespace, <>. === SessionAuthenticationStrategy diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc index aa2ff02f29..411fefcb13 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/basic.adoc @@ -33,7 +33,7 @@ The figure builds off our <> image:{icondir}/number_1.png[] When the user submits their username and password, the `BasicAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of <> by extracting the username and password from the `HttpServletRequest`. image:{icondir}/number_2.png[] Next, the `UsernamePasswordAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated. -The details of what `AuthenticationManager` look like depend on how the <>. +The details of what `AuthenticationManager` looks like depend on how the <>. image:{icondir}/number_3.png[] If authentication fails, then __Failure__ diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc index 27343234e5..f8745f89ab 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/form.adoc @@ -37,7 +37,7 @@ The figure builds off our <> image:{icondir}/number_1.png[] When the user submits their username and password, the `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of <> by extracting the username and password from the `HttpServletRequest`. image:{icondir}/number_2.png[] Next, the `UsernamePasswordAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated. -The details of what `AuthenticationManager` look like depend on how the <>. +The details of what `AuthenticationManager` looks like depend on how the <>. image:{icondir}/number_3.png[] If authentication fails, then __Failure__ @@ -147,7 +147,7 @@ fun configure(http: HttpSecurity) { [[servlet-authentication-form-custom-html]] When the login page is specified in the Spring Security configuration, you are responsible for rendering the page. // FIXME: default login page rendered by Spring Security -Below is a https://www.thymeleaf.org/[Thymeleaf] template that produces an HTML login form that complies with a login page of `/login`.: +Below is a https://www.thymeleaf.org/[Thymeleaf] template that produces an HTML login form that complies with a login page of `/login`: .Log In Form ==== @@ -189,11 +189,11 @@ There are a few key points about the default HTML form: * If the HTTP parameter logout is found, it indicates the user has logged out successfully Many users will not need much more than to customize the log in page. -However, if needed everything above can be customized with additional configuration. +However, if needed, everything above can be customized with additional configuration. [[servlet-authentication-form-custom-controller]] If you are using Spring MVC, you will need a controller that maps `GET /login` to the login template we created. -A minimal sample `LoginController` can be see below: +A minimal sample `LoginController` can be seen below: .LoginController ==== diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc index a364cee0e1..d5b178516b 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authentication/unpwd/in-memory.adoc @@ -1,7 +1,7 @@ [[servlet-authentication-inmemory]] = In-Memory Authentication -Spring Security's `InMemoryUserDetailsManager` implements <> to provide support for username/password based authentication that is retrieved in memory. +Spring Security's `InMemoryUserDetailsManager` implements <> to provide support for username/password based authentication that is stored in memory. `InMemoryUserDetailsManager` provides management of `UserDetails` by implementing the `UserDetailsManager` interface. `UserDetails` based authentication is used by Spring Security when it is configured to <> for authentication. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/architecture.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/architecture.adoc index 15de8dbf70..240727384a 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/architecture.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/architecture.adoc @@ -8,7 +8,7 @@ == Authorities <>, discusses how all `Authentication` implementations store a list of `GrantedAuthority` objects. These represent the authorities that have been granted to the principal. -the `GrantedAuthority` objects are inserted into the `Authentication` object by the `AuthenticationManager` and are later read by `AccessDecisionManager` s when making authorization decisions. +The `GrantedAuthority` objects are inserted into the `Authentication` object by the `AuthenticationManager` and are later read by `AccessDecisionManager` s when making authorization decisions. `GrantedAuthority` is an interface with only one method: diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/expression-based.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/expression-based.adoc index 0fc34842d8..1070783c92 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/expression-based.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/authorization/expression-based.adoc @@ -1,7 +1,7 @@ [[el-access]] == Expression-Based Access Control -Spring Security 3.0 introduced the ability to use Spring EL expressions as an authorization mechanism in addition to the simple use of configuration attributes and access-decision voters which have seen before. +Spring Security 3.0 introduced the ability to use Spring EL expressions as an authorization mechanism in addition to the simple use of configuration attributes and access-decision voters which have been seen before. Expression-based access control is built on the same architecture but allows complicated Boolean logic to be encapsulated in a single expression. @@ -296,7 +296,7 @@ fun deletePermission(contact: Contact?, recipient: Sid?, permission: Permission? ---- ==== -Here we're actually using a method argument as part of the expression to decide whether the current user has the "admin"permission for the given contact. +Here we're actually using a method argument as part of the expression to decide whether the current user has the "admin" permission for the given contact. The built-in `hasPermission()` expression is linked into the Spring Security ACL module through the application context, as we'll <>. You can access any of the method arguments by name as expression variables. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/java-configuration/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/java-configuration/index.adoc index 3ba5432ddc..48205a64a6 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/java-configuration/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/java-configuration/index.adoc @@ -312,7 +312,7 @@ public class Config extends WebSecurityConfigurerAdapter { Spring Security's Java Configuration does not expose every property of every object that it configures. This simplifies the configuration for a majority of users. -Afterall, if every property was exposed, users could use standard bean configuration. +After all, if every property was exposed, users could use standard bean configuration. While there are good reasons to not directly expose every property, users may still need more advanced configuration options. To address this Spring Security introduces the concept of an `ObjectPostProcessor` which can be used to modify or replace many of the Object instances created by the Java Configuration. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/saml2-login.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/saml2-login.adoc index b4483fa5bb..29af4dee8c 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/saml2-login.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/saml2/saml2-login.adoc @@ -1694,6 +1694,7 @@ Also, your application can participate in an AP-initiated logout when the assert === Configuring Logout Endpoints There are three behaviors that can be triggered by different endpoints: + * RP-initiated logout, which allows an authenticated user to `POST` and trigger the logout process by sending the asserting party a `` * AP-initiated logout, which allows an asserting party to send a `` to the application * AP logout response, which allows an asserting party to send a `` in response to the RP-initiated ``