diff --git a/docs/modules/ROOT/pages/overview/community.adoc b/docs/modules/ROOT/pages/overview/community.adoc index 893d17727b..34cd5e504c 100644 --- a/docs/modules/ROOT/pages/overview/community.adoc +++ b/docs/modules/ROOT/pages/overview/community.adoc @@ -11,7 +11,7 @@ If you need help with Spring Security, we are here to help. The following are some of the best ways to get help: * Read through this documentation. -* Try one of our many <>. +* Try one of our many xref:overview/samples.adoc#samples[sample applications]. * Ask a question on https://stackoverflow.com/questions/tagged/spring-security[https://stackoverflow.com] with the `spring-security` tag. * Report bugs and enhancement requests at https://github.com/spring-projects/spring-security/issues diff --git a/docs/modules/ROOT/pages/overview/features/authentication/index.adoc b/docs/modules/ROOT/pages/overview/features/authentication/index.adoc index 2dbe3ae377..991b671e92 100644 --- a/docs/modules/ROOT/pages/overview/features/authentication/index.adoc +++ b/docs/modules/ROOT/pages/overview/features/authentication/index.adoc @@ -10,4 +10,4 @@ Once authentication is performed we know the identity and can perform authorizat Spring Security provides built in support for authenticating users. This section is dedicated to generic authentication support that applies in both Servlet and WebFlux environments. -Refer to the sections on authentication for <> and WebFlux for details on what is supported for each stack. +Refer to the sections on authentication for xref:servlet/authentication/index.adoc#servlet-authentication[Servlet] and WebFlux for details on what is supported for each stack. diff --git a/docs/modules/ROOT/pages/overview/features/exploits/csrf.adoc b/docs/modules/ROOT/pages/overview/features/exploits/csrf.adoc index 026faecde6..8c9517363e 100644 --- a/docs/modules/ROOT/pages/overview/features/exploits/csrf.adoc +++ b/docs/modules/ROOT/pages/overview/features/exploits/csrf.adoc @@ -14,7 +14,7 @@ In the following sections we will explore: [NOTE] ==== This portion of the documentation discusses the general topic of CSRF protection. -Refer to the relevant sections for specific information on CSRF protection for <> and <> based applications. +Refer to the relevant sections for specific information on CSRF protection for xref:servlet/exploits/csrf.adoc#servlet-csrf[servlet] and xref:reactive/exploits/csrf.adoc#webflux-csrf[WebFlux] based applications. ==== [[csrf-explained]] diff --git a/docs/modules/ROOT/pages/overview/features/exploits/headers.adoc b/docs/modules/ROOT/pages/overview/features/exploits/headers.adoc index 565272a29c..be19d3028c 100644 --- a/docs/modules/ROOT/pages/overview/features/exploits/headers.adoc +++ b/docs/modules/ROOT/pages/overview/features/exploits/headers.adoc @@ -4,7 +4,7 @@ [NOTE] ==== This portion of the documentation discusses the general topic of Security HTTP Response Headers. -Refer to the relevant sections for specific information on Security HTTP Response Headers <> and <> based applications. +Refer to the relevant sections for specific information on Security HTTP Response Headers xref:servlet/exploits/headers.adoc#servlet-headers[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers[WebFlux] based applications. ==== There are many https://owasp.org/www-project-secure-headers/#div-headers[HTTP response headers] that can be used to increase the security of web applications. @@ -16,7 +16,7 @@ If necessary, Spring Security can also be configured to provide <> and <> based applications. +Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-default[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-default[webflux] based applications. ==== Spring Security provides a default set of security related HTTP response headers to provide secure defaults. @@ -53,7 +53,7 @@ For additional details on each of these headers, refer to the corresponding sect [NOTE] ==== -Refer to the relevant sections to see how to customize the defaults for both <> and <> based applications. +Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-cache-control[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-cache-control[webflux] based applications. ==== Spring Security's default is to disable caching to protect user's content. @@ -81,7 +81,7 @@ This allows for applications to ensure that static resources like CSS and JavaSc [NOTE] ==== -Refer to the relevant sections to see how to customize the defaults for both <> and <> based applications. +Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-content-type-options[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-content-type-options[webflux] based applications. ==== Historically browsers, including Internet Explorer, would try to guess the content type of a request using https://en.wikipedia.org/wiki/Content_sniffing[content sniffing]. @@ -114,7 +114,7 @@ X-Content-Type-Options: nosniff [NOTE] ==== -Refer to the relevant sections to see how to customize the defaults for both <> and <> based applications. +Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-hsts[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-hsts[webflux] based applications. ==== When you type in your bank's website, do you enter mybank.example.com or do you enter https://mybank.example.com[]? @@ -154,7 +154,7 @@ For more details on HSTS preload please see https://hstspreload.org. [NOTE] ==== -In order to remain passive Spring Security still provides <>, but for the reasons listed above HPKP is no longer recommended by the security team. +In order to remain passive Spring Security still provides xref:servlet/exploits/headers.adoc#servlet-headers-hpkp[support for HPKP in servlet environments], but for the reasons listed above HPKP is no longer recommended by the security team. ==== https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning[HTTP Public Key Pinning (HPKP)] specifies to a web client which public key to use with certain web server to prevent Man in the Middle (MITM) attacks with forged certificates. @@ -170,7 +170,7 @@ Is HTTP Public Key Pinning Dead?] and https://scotthelme.co.uk/im-giving-up-on-h [NOTE] ==== -Refer to the relevant sections to see how to customize the defaults for both <> and <> based applications. +Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-frame-options[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-frame-options[webflux] based applications. ==== Allowing your website to be added to a frame can be a security issue. @@ -200,7 +200,7 @@ X-Frame-Options: DENY [NOTE] ==== -Refer to the relevant sections to see how to customize the defaults for both <> and <> based applications. +Refer to the relevant sections to see how to customize the defaults for both xref:servlet/exploits/headers.adoc#servlet-headers-xss-protection[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-xss-protection[webflux] based applications. ==== Some browsers have built in support for filtering out https://www.owasp.org/index.php/Testing_for_Reflected_Cross_site_scripting_(OWASP-DV-001)[reflected XSS attacks]. @@ -223,7 +223,7 @@ X-XSS-Protection: 1; mode=block [NOTE] ==== -Refer to the relevant sections to see how to configure both <> and <> based applications. +Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-csp[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-csp[webflux] based applications. ==== 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). @@ -299,7 +299,7 @@ https://www.w3.org/TR/CSP2/[W3C Candidate Recommendation] [NOTE] ==== -Refer to the relevant sections to see how to configure both <> and <> based applications. +Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-referrer[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-referrer[webflux] based applications. ==== 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 @@ -322,7 +322,7 @@ The Referrer-Policy response header instructs the browser to let the destination [NOTE] ==== -Refer to the relevant sections to see how to configure both <> and <> based applications. +Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-feature[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-feature[webflux] based applications. ==== 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. @@ -344,7 +344,7 @@ These policies restrict what APIs the site can access or modify the browser's de [NOTE] ==== -Refer to the relevant sections to see how to configure both <> and <> based applications. +Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-permissions[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-permissions[webflux] based applications. ==== https://w3c.github.io/webappsec-permissions-policy/[Permissions 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. @@ -366,7 +366,7 @@ These policies restrict what APIs the site can access or modify the browser's de [NOTE] ==== -Refer to the relevant sections to see how to configure both <> and <> based applications. +Refer to the relevant sections to see how to configure both xref:servlet/exploits/headers.adoc#servlet-headers-clear-site-data[servlet] and xref:reactive/exploits/headers.adoc#webflux-headers-clear-site-data[webflux] based applications. ==== https://www.w3.org/TR/clear-site-data/[Clear Site Data] is a mechanism by which any browser-side data - cookies, local storage, and the like - can be removed when an HTTP response contains this header: @@ -384,7 +384,7 @@ This is a nice clean-up action to perform on logout. [NOTE] ==== -Refer to the relevant section to see how to configure <> based applications. +Refer to the relevant section to see how to configure xref:servlet/exploits/headers.adoc#servlet-headers-custom[servlet] based applications. ==== Spring Security has mechanisms to make it convenient to add the more common security headers to your application. diff --git a/docs/modules/ROOT/pages/overview/features/exploits/http.adoc b/docs/modules/ROOT/pages/overview/features/exploits/http.adoc index 44a4e59692..579745c1aa 100644 --- a/docs/modules/ROOT/pages/overview/features/exploits/http.adoc +++ b/docs/modules/ROOT/pages/overview/features/exploits/http.adoc @@ -9,12 +9,12 @@ However, it does provide a number of features that help with HTTPS usage. [[http-redirect]] == Redirect to HTTPS -When a client uses HTTP, Spring Security can be configured to redirect to HTTPS both <> and <> environments. +When a client uses HTTP, Spring Security can be configured to redirect to HTTPS both xref:servlet/exploits/http.adoc#servlet-http-redirect[Servlet] and xref:reactive/exploits/http.adoc#webflux-http-redirect[WebFlux] environments. [[http-hsts]] == Strict Transport Security -Spring Security provides support for <> and enables it by default. +Spring Security provides support for xref:overview/features/exploits/headers.adoc#headers-hsts[Strict Transport Security] and enables it by default. [[http-proxy-server]] == Proxy Server Configuration diff --git a/docs/modules/ROOT/pages/overview/features/index.adoc b/docs/modules/ROOT/pages/overview/features/index.adoc index 8ae9eb3feb..0edf1f1650 100644 --- a/docs/modules/ROOT/pages/overview/features/index.adoc +++ b/docs/modules/ROOT/pages/overview/features/index.adoc @@ -1,6 +1,6 @@ [[features]] = Features -Spring Security provides comprehensive support for <>, authorization, and protection against <>. +Spring Security provides comprehensive support for xref:overview/features/authentication/index.adoc#authentication[authentication], authorization, and protection against xref:overview/features/exploits/index.adoc#exploits[common exploits]. It also provides integration with other libraries to simplify its usage. diff --git a/docs/modules/ROOT/pages/overview/getting-spring-security.adoc b/docs/modules/ROOT/pages/overview/getting-spring-security.adoc index 51f77fe29f..a9b2eef369 100644 --- a/docs/modules/ROOT/pages/overview/getting-spring-security.adoc +++ b/docs/modules/ROOT/pages/overview/getting-spring-security.adoc @@ -2,7 +2,7 @@ = Getting Spring Security This section discusses all you need to know about getting the Spring Security binaries. -See <> for how to obtain the source code. +See xref:overview/community.adoc#community-source[] for how to obtain the source code. == Release Numbering @@ -72,7 +72,7 @@ You can do so by adding a Maven property, as the following example shows: ---- ==== -If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <>. +If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:overview/modules.adoc#modules[]. [[getting-maven-no-boot]] === Maven Without Spring Boot @@ -118,7 +118,7 @@ A minimal Spring Security Maven set of dependencies typically looks like the fol ---- ==== -If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <>. +If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:overview/modules.adoc#modules[]. Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x. Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems. @@ -236,7 +236,7 @@ ext['spring.version']='{spring-core-version}' ---- ==== -If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <>. +If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:overview/modules.adoc#modules[]. === Gradle Without Spring Boot @@ -274,7 +274,7 @@ dependencies { ---- ==== -If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <>. +If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate xref:overview/modules.adoc#modules[]. Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x. Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems. diff --git a/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc b/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc index c3a92fea4f..d596977b40 100644 --- a/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc +++ b/docs/modules/ROOT/pages/reactive/exploits/csrf.adoc @@ -1,7 +1,7 @@ [[webflux-csrf]] = Cross Site Request Forgery (CSRF) for WebFlux Environments -This section discusses Spring Security's <> support for WebFlux environments. +This section discusses Spring Security's xref:overview/features/exploits/csrf.adoc#csrf[Cross Site Request Forgery (CSRF)] support for WebFlux environments. [[webflux-csrf-using]] == Using Spring Security CSRF Protection @@ -14,7 +14,7 @@ The steps to using Spring Security's CSRF protection are outlined below: [[webflux-csrf-idempotent]] === Use proper HTTP verbs The first step to protecting against CSRF attacks is to ensure your website uses proper HTTP verbs. -This is covered in detail in <>. +This is covered in detail in xref:overview/features/exploits/csrf.adoc#csrf-protection-idempotent[Safe Methods Must be Idempotent]. [[webflux-csrf-configure]] === Configure CSRF Protection @@ -73,7 +73,7 @@ If you do not need the ability to read the cookie with JavaScript directly, it i [[webflux-csrf-configure-disable]] ==== Disable CSRF Protection CSRF protection is enabled by default. -However, it is simple to disable CSRF protection if it <>. +However, it is simple to disable CSRF protection if it xref:overview/features/exploits/csrf.adoc#csrf-when[makes sense for your application]. The Java configuration below will disable CSRF protection. @@ -109,7 +109,7 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain [[webflux-csrf-include]] === Include the CSRF Token -In order for the <> to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request. +In order for the xref:overview/features/exploits/csrf.adoc#csrf-protection-stp[synchronizer token pattern] to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request. This must be included in a part of the request (i.e. form parameter, HTTP header, etc) that is not automatically included in the HTTP request by the browser. Spring Security's https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/server/csrf/CsrfWebFilter.html[CsrfWebFilter] exposes a https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/csrf/CsrfToken.html[Mono] as a `ServerWebExchange` attribute named `org.springframework.security.web.server.csrf.CsrfToken`. @@ -272,19 +272,19 @@ An example of doing this with Thymeleaf is shown below: == CSRF Considerations There are a few special considerations to consider when implementing protection against CSRF attacks. This section discusses those considerations as it pertains to WebFlux environments. -Refer to <> for a more general discussion. +Refer to xref:overview/features/exploits/csrf.adoc#csrf-considerations[] for a more general discussion. [[webflux-considerations-csrf-login]] === Logging In -It is important to <> requests to protect against forging log in attempts. +It is important to xref:overview/features/exploits/csrf.adoc#csrf-considerations-login[require CSRF for log in] requests to protect against forging log in attempts. Spring Security's WebFlux support does this out of the box. [[webflux-considerations-csrf-logout]] === Logging Out -It is important to <> requests to protect against forging log out attempts. +It is important to xref:overview/features/exploits/csrf.adoc#csrf-considerations-logout[require CSRF for log out] requests to protect against forging log out attempts. By default Spring Security's `LogoutWebFilter` only processes HTTP post requests. This ensures that log out requires a CSRF token and that a malicious user cannot forcibly log out your users. @@ -333,7 +333,7 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain By default Spring Security stores the CSRF token in the `WebSession`. This can lead to a situation where the session expires which means there is not an expected CSRF token to validate against. -We've already discussed <> to session timeouts. +We've already discussed xref:overview/features/exploits/csrf.adoc#csrf-considerations-login[general solutions] to session timeouts. This section discusses the specifics of CSRF timeouts as it pertains to the WebFlux support. It is simple to change storage of the expected CSRF token to be in a cookie. @@ -344,7 +344,7 @@ For details, refer to the <> section. // FIXME: We need a WebFlux multipart body vs action story. WebFlux always has multipart enabled. [[webflux-csrf-considerations-multipart]] === Multipart (file upload) -We have <> how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem. +We have xref:overview/features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem. This section discusses how to implement placing the CSRF token in the <> and <> within a WebFlux application. [NOTE] @@ -355,7 +355,7 @@ More information about using multipart forms with Spring can be found within the [[webflux-csrf-considerations-multipart-body]] ==== Place CSRF Token in the Body -We have <> the trade-offs of placing the CSRF token in the body. +We have xref:overview/features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] the trade-offs of placing the CSRF token in the body. In a WebFlux application, this can be configured with the following configuration: @@ -391,7 +391,7 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain [[webflux-csrf-considerations-multipart-url]] ==== Include CSRF Token in URL -We have <> the trade-offs of placing the CSRF token in the URL. +We have xref:overview/features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] the trade-offs of placing the CSRF token in the URL. Since the `CsrfToken` is exposed as an `ServerHttpRequest` <>, we can use that to create an `action` with the CSRF token in it. An example with Thymeleaf is shown below: @@ -407,6 +407,6 @@ An example with Thymeleaf is shown below: [[webflux-csrf-considerations-override-method]] === HiddenHttpMethodFilter -We have <> overriding the HTTP method. +We have xref:overview/features/exploits/csrf.adoc#csrf-considerations-override-method[already discussed] overriding the HTTP method. In a Spring WebFlux application, overriding the HTTP method is done using https://docs.spring.io/spring-framework/docs/5.2.x/javadoc-api/org/springframework/web/filter/reactive/HiddenHttpMethodFilter.html[HiddenHttpMethodFilter]. diff --git a/docs/modules/ROOT/pages/reactive/exploits/headers.adoc b/docs/modules/ROOT/pages/reactive/exploits/headers.adoc index a076a2fedb..ed916c6baf 100644 --- a/docs/modules/ROOT/pages/reactive/exploits/headers.adoc +++ b/docs/modules/ROOT/pages/reactive/exploits/headers.adoc @@ -1,17 +1,17 @@ [[webflux-headers]] = Security HTTP Response Headers -<> can be used to increase the security of web applications. +xref:overview/features/exploits/headers.adoc#headers[Security HTTP Response Headers] can be used to increase the security of web applications. This section is dedicated to WebFlux based support for Security HTTP Response Headers. [[webflux-headers-default]] == Default Security Headers -Spring Security provides a <> to provide secure defaults. +Spring Security provides a xref:overview/features/exploits/headers.adoc#headers-default[default set of Security HTTP Response Headers] to provide secure defaults. While each of these headers are considered best practice, it should be noted that not all clients utilize the headers, so additional testing is encouraged. You can customize specific headers. -For example, assume that you want the defaults except you wish to specify `SAMEORIGIN` for <>. +For example, assume that you want the defaults except you wish to specify `SAMEORIGIN` for xref:servlet/exploits/headers.adoc#servlet-headers-frame-options[X-Frame-Options]. You can easily do this with the following Configuration: @@ -85,7 +85,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-cache-control]] == Cache Control -Spring Security includes <> headers by default. +Spring Security includes xref:overview/features/exploits/headers.adoc#headers-cache-control[Cache Control] headers by default. However, if you actually want to cache specific responses, your application can selectively add them to the https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/server/reactive/ServerHttpResponse.html[ServerHttpResponse] to override the header set by Spring Security. This is useful to ensure things like CSS, JavaScript, and images are properly cached. @@ -131,7 +131,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-content-type-options]] == Content Type Options -Spring Security includes <> headers by default. +Spring Security includes xref:overview/features/exploits/headers.adoc#headers-content-type-options[Content-Type] headers by default. However, you can disable it with: .Content Type Options Disabled @@ -169,7 +169,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-hsts]] == HTTP Strict Transport Security (HSTS) -Spring Security provides the <> header by default. +Spring Security provides the xref:overview/features/exploits/headers.adoc#headers-hsts[Strict Transport Security] header by default. However, you can customize the results explicitly. For example, the following is an example of explicitly providing HSTS: @@ -214,7 +214,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-frame-options]] == X-Frame-Options -By default, Spring Security disables rendering within an iframe using <>. +By default, Spring Security disables rendering within an iframe using xref:overview/features/exploits/headers.adoc#headers-frame-options[X-Frame-Options]. You can customize frame options to use the same origin using the following: @@ -293,7 +293,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-csp]] == Content Security Policy (CSP) -Spring Security does not add <> by default, because a reasonable default is impossible to know without context of the application. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-csp[Content Security Policy] by default, because a reasonable default is impossible to know without context of the application. The web application author must declare the security policy(s) to enforce and/or monitor for the protected resources. For example, given the following security policy: @@ -385,7 +385,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-referrer]] == Referrer Policy -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-referrer[Referrer Policy] headers by default. You can enable the Referrer Policy header using configuration as shown below: .Referrer Policy Configuration @@ -427,7 +427,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-feature]] == Feature Policy -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-feature[Feature Policy] headers by default. The following `Feature-Policy` header: .Feature-Policy Example @@ -475,7 +475,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-permissions]] == Permissions Policy -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-permissions[Permissions Policy] headers by default. The following `Permissions-Policy` header: .Permissions-Policy Example @@ -527,7 +527,7 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { [[webflux-headers-clear-site-data]] == Clear Site Data -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-clear-site-data[Clear-Site-Data] headers by default. The following Clear-Site-Data header: .Clear-Site-Data Example diff --git a/docs/modules/ROOT/pages/reactive/exploits/http.adoc b/docs/modules/ROOT/pages/reactive/exploits/http.adoc index 387a05a719..258d10f74f 100644 --- a/docs/modules/ROOT/pages/reactive/exploits/http.adoc +++ b/docs/modules/ROOT/pages/reactive/exploits/http.adoc @@ -1,7 +1,7 @@ [[webflux-http]] = HTTP -All HTTP based communication should be protected <>. +All HTTP based communication should be protected xref:overview/features/exploits/http.adoc#http[using TLS]. Below you can find details around WebFlux specific features that assist with HTTPS usage. @@ -79,9 +79,9 @@ fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain [[webflux-hsts]] == Strict Transport Security -Spring Security provides support for <> and enables it by default. +Spring Security provides support for xref:servlet/exploits/headers.adoc#servlet-headers-hsts[Strict Transport Security] and enables it by default. [[webflux-http-proxy-server]] == Proxy Server Configuration -Spring Security <>. +Spring Security xref:overview/features/exploits/http.adoc#http-proxy-server[integrates with proxy servers]. diff --git a/docs/modules/ROOT/pages/reactive/index.adoc b/docs/modules/ROOT/pages/reactive/index.adoc index 2e9d23500d..8791a47c32 100644 --- a/docs/modules/ROOT/pages/reactive/index.adoc +++ b/docs/modules/ROOT/pages/reactive/index.adoc @@ -1,4 +1,4 @@ = Reactive Applications -Reactive applications work very differently than <>. +Reactive applications work very differently than xref:servlet/index.adoc#servlet-applications[]. This section discusses how Spring Security works with reactive applications which are typically written using Spring's WebFlux. diff --git a/docs/modules/ROOT/pages/reactive/method.adoc b/docs/modules/ROOT/pages/reactive/method.adoc index 21a183fd34..fbb07d4d7e 100644 --- a/docs/modules/ROOT/pages/reactive/method.adoc +++ b/docs/modules/ROOT/pages/reactive/method.adoc @@ -162,7 +162,7 @@ It is important to note that any of the expressions in standard method security However, at this time we only support return type of `Boolean` or `boolean` of the expression. This means that the expression must not block. -When integrating with <>, the Reactor Context is automatically established by Spring Security according to the authenticated user. +When integrating with xref:reactive/webflux.adoc#jc-webflux[], the Reactor Context is automatically established by Spring Security according to the authenticated user. ==== .Java diff --git a/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc b/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc index ac732704a2..27d272c089 100644 --- a/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc +++ b/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc @@ -49,4 +49,4 @@ fun webFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain { ---- ==== -You can now leverage Spring Security's <> or <> support to obtain and use the access token. +You can now leverage Spring Security's <> or xref:reactive/registered-oauth2-authorized-client.adoc#webflux-roac[@RegisteredOAuth2AuthorizedClient] support to obtain and use the access token. diff --git a/docs/modules/ROOT/pages/reactive/oauth2/login.adoc b/docs/modules/ROOT/pages/reactive/oauth2/login.adoc index ecbe18dc0f..2f80da08b1 100644 --- a/docs/modules/ROOT/pages/reactive/oauth2/login.adoc +++ b/docs/modules/ROOT/pages/reactive/oauth2/login.adoc @@ -39,11 +39,11 @@ The redirect URI is the path in the application that the end-user's user-agent i In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:8080/login/oauth2/code/google`. TIP: The default redirect URI template is `+{baseUrl}/login/oauth2/code/{registrationId}+`. -The *_registrationId_* is a unique identifier for the <>. +The *_registrationId_* is a unique identifier for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration]. For our example, the `registrationId` is `google`. -IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check <> to ensure the application is correctly configured. -Also, see the supported <> for `redirect-uri`. +IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check xref:overview/features/exploits/http.adoc#http-proxy-server[Proxy Server Configuration] to ensure the application is correctly configured. +Also, see the supported xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-auth-code-redirect-uri[ `URI` template variables] for `redirect-uri`. [[webflux-oauth2-login-sample-config]] === Configure `application.yml` @@ -68,7 +68,7 @@ spring: .OAuth Client properties ==== <1> `spring.security.oauth2.client.registration` is the base property prefix for OAuth Client properties. -<2> Following the base property prefix is the ID for the <>, such as google. +<2> Following the base property prefix is the ID for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration], such as google. ==== . Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier. diff --git a/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc b/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc index 8f45337314..443b54aff7 100644 --- a/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc +++ b/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc @@ -896,7 +896,7 @@ fun jwtDecoder(): ReactiveJwtDecoder { [[webflux-oauth2resourceserver-opaque-minimaldependencies]] === Minimal Dependencies for Introspection -As described in <> most of Resource Server support is collected in `spring-security-oauth2-resource-server`. +As described in xref:servlet/oauth2/oauth2-resourceserver.adoc#oauth2resourceserver-jwt-minimaldependencies[Minimal Dependencies for JWT] most of Resource Server support is collected in `spring-security-oauth2-resource-server`. However unless a custom <> is provided, the Resource Server will fallback to ReactiveOpaqueTokenIntrospector. Meaning that both `spring-security-oauth2-resource-server` and `oauth2-oidc-sdk` are necessary in order to have a working minimal Resource Server that supports opaque Bearer Tokens. Please refer to `spring-security-oauth2-resource-server` in order to determin the correct version for `oauth2-oidc-sdk`. diff --git a/docs/modules/ROOT/pages/reactive/registered-oauth2-authorized-client.adoc b/docs/modules/ROOT/pages/reactive/registered-oauth2-authorized-client.adoc index 30beaf7807..b8cc5c6367 100644 --- a/docs/modules/ROOT/pages/reactive/registered-oauth2-authorized-client.adoc +++ b/docs/modules/ROOT/pages/reactive/registered-oauth2-authorized-client.adoc @@ -8,7 +8,7 @@ Spring Security allows resolving an access token using `@RegisteredOAuth2Authori A working example can be found in {gh-samples-url}/reactive/webflux/java/oauth2/webclient[*OAuth 2.0 WebClient WebFlux sample*]. ==== -After configuring Spring Security for <> or as an <>, an `OAuth2AuthorizedClient` can be resolved using the following: +After configuring Spring Security for xref:reactive/oauth2/login.adoc#webflux-oauth2-login[OAuth2 Login] or as an xref:reactive/oauth2/access-token.adoc#webflux-oauth2-client[OAuth2 Client], an `OAuth2AuthorizedClient` can be resolved using the following: ==== .Java diff --git a/docs/modules/ROOT/pages/reactive/test.adoc b/docs/modules/ROOT/pages/reactive/test.adoc index d341dea14a..632e58e18f 100644 --- a/docs/modules/ROOT/pages/reactive/test.adoc +++ b/docs/modules/ROOT/pages/reactive/test.adoc @@ -4,7 +4,7 @@ [[test-erms]] == Testing Reactive Method Security -For example, we can test our example from <> using the same setup and annotations we did in <>. +For example, we can test our example from xref:reactive/method.adoc#jc-erms[] using the same setup and annotations we did in xref:servlet/test/method.adoc#test-method[]. Here is a minimal sample of what we can do: ==== @@ -381,7 +381,7 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read" ---- ==== -Spring Security does the necessary work to make sure that the `OidcUser` instance is available for <>. +Spring Security does the necessary work to make sure that the `OidcUser` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation]. Further, it also links that `OidcUser` to a simple instance of `OAuth2AuthorizedClient` that it deposits into a mock `ServerOAuth2AuthorizedClientRepository`. This can be handy if your tests <>.. @@ -600,7 +600,7 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read" ---- ==== -Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for <>. +Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation]. Further, it also links that `OAuth2User` to a simple instance of `OAuth2AuthorizedClient` that it deposits in a mock `ServerOAuth2AuthorizedClientRepository`. This can be handy if your tests <>. diff --git a/docs/modules/ROOT/pages/reactive/webclient.adoc b/docs/modules/ROOT/pages/reactive/webclient.adoc index 181ac58b2c..270420a4fa 100644 --- a/docs/modules/ROOT/pages/reactive/webclient.adoc +++ b/docs/modules/ROOT/pages/reactive/webclient.adoc @@ -3,7 +3,7 @@ [NOTE] ==== The following documentation is for use within Reactive environments. -For Servlet environments, refer to <> environments. +For Servlet environments, refer to xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-webclient-servlet[ WebClient for Servlet] environments. ==== diff --git a/docs/modules/ROOT/pages/reactive/x509.adoc b/docs/modules/ROOT/pages/reactive/x509.adoc index cb1c4e0a47..880632b060 100644 --- a/docs/modules/ROOT/pages/reactive/x509.adoc +++ b/docs/modules/ROOT/pages/reactive/x509.adoc @@ -1,7 +1,7 @@ [[reactive-x509]] = Reactive X.509 Authentication -Similar to <>, reactive x509 authentication filter allows extracting an authentication token from a certificate provided by a client. +Similar to xref:servlet/authentication/x509.adoc#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: ==== diff --git a/docs/modules/ROOT/pages/servlet/appendix/database-schema.adoc b/docs/modules/ROOT/pages/servlet/appendix/database-schema.adoc index ab840e131f..f6cf413b68 100644 --- a/docs/modules/ROOT/pages/servlet/appendix/database-schema.adoc +++ b/docs/modules/ROOT/pages/servlet/appendix/database-schema.adoc @@ -78,7 +78,7 @@ If you write your own or choose to implement `AuthenticationProvider` without a == Persistent Login (Remember-Me) Schema -This table is used to store data used by the more secure <> remember-me implementation. +This table is used to store data used by the more secure xref:servlet/authentication/rememberme.adoc#remember-me-persistent-token[persistent token] remember-me implementation. If you are using `JdbcTokenRepositoryImpl` either directly or through the namespace, then you will need this table. Remember to adjust this schema to match the database dialect you are using. @@ -96,7 +96,7 @@ create table persistent_logins ( [[dbschema-acl]] == ACL Schema -There are four tables used by the Spring Security <> implementation. +There are four tables used by the Spring Security xref:servlet/authorization/acls.adoc#domain-acls[ACL] implementation. . `acl_sid` stores the security identities recognised by the ACL system. These can be unique principals or authorities which may apply to multiple principals. @@ -367,7 +367,7 @@ END; [[dbschema-oauth2-client]] == OAuth 2.0 Client Schema -The JDBC implementation of <> (`JdbcOAuth2AuthorizedClientService`) requires a table for persisting `OAuth2AuthorizedClient`(s). +The JDBC implementation of xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-authorized-repo-service[ OAuth2AuthorizedClientService] (`JdbcOAuth2AuthorizedClientService`) requires a table for persisting `OAuth2AuthorizedClient`(s). You will need to adjust this schema to match the database dialect you are using. [source,ddl] diff --git a/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc b/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc index a2e029da6b..ec3d417bde 100644 --- a/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc +++ b/docs/modules/ROOT/pages/servlet/appendix/namespace.adoc @@ -1,7 +1,7 @@ [[appendix-namespace]] = The Security Namespace This appendix provides a reference to the elements available in the security namespace and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document). -If you haven't used the namespace before, please read the <> on namespace configuration, as this is intended as a supplement to the information there. +If you haven't used the namespace before, please read the xref:servlet/namespace/index.adoc#ns-config[introductory chapter] on namespace configuration, as this is intended as a supplement to the information there. Using a good quality XML editor while editing a configuration based on the schema is recommended as this will provide contextual information on which elements and attributes are available as well as comments explaining their purpose. The namespace is written in https://relaxng.org/[RELAX NG] Compact format and later converted into an XSD schema. If you are familiar with this format, you may wish to examine the https://raw.githubusercontent.com/spring-projects/spring-security/main/config/src/main/resources/org/springframework/security/config/spring-security-4.1.rnc[schema file] directly. @@ -19,15 +19,15 @@ This may include sensitive information, such as request parameters or headers, a === If you use an `` element within your application, a `FilterChainProxy` bean named "springSecurityFilterChain" is created and the configuration within the element is used to build a filter chain within `FilterChainProxy`. -As of Spring Security 3.1, additional `http` elements can be used to add extra filter chains footnote:[See the pass:specialcharacters,macros[<>] for how to set up the mapping from your `web.xml` ]. +As of Spring Security 3.1, additional `http` elements can be used to add extra filter chains footnote:[See the pass:specialcharacters,macros[xref:servlet/namespace/index.adoc#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 will be added to the stack depending on the attributes and child elements which are present. The positions of the standard filters are fixed (see -<> 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 +xref:servlet/namespace/index.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, of course, still do this if you need full control of the configuration. -All filters which require a reference to the <> will be automatically injected with the internal instance created by the namespace configuration. +All filters which require a reference to the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] will be automatically injected with the internal instance created by the namespace configuration. Each `` namespace block always creates an `SecurityContextPersistenceFilter`, an `ExceptionTranslationFilter` and a `FilterSecurityInterceptor`. These are fixed and cannot be replaced with alternatives. @@ -146,7 +146,7 @@ Defaults to `true`. [[nsa-http-use-expressions]] * **use-expressions** -Enables EL-expressions in the `access` attribute, as described in the chapter on <>. +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. @@ -179,7 +179,7 @@ The default value is true. [[nsa-access-denied-handler]] === This element allows you to set the `errorPage` property for the default `AccessDeniedHandler` used by the `ExceptionTranslationFilter`, using the <> attribute, or to supply your own implementation using the<> attribute. -This is discussed in more detail in the section on the <>. +This is discussed in more detail in the section on the xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[ExceptionTranslationFilter]. [[nsa-access-denied-handler-parents]] @@ -227,7 +227,7 @@ Optional attribute that specifies the bean name of a `CorsConfigurationSource` t === This element allows for configuring additional (security) headers to be send with the response. It enables easy configuration for several headers and also allows for setting custom headers through the <> element. -Additional information, can be found in the <> section of the reference. +Additional information, can be found in the xref:overview/features/exploits/headers.adoc#headers[Security Headers] section of the reference. ** `Cache-Control`, `Pragma`, and `Expires` - Can be set using the <> element. This ensures that the browser does not cache your secured pages. @@ -674,7 +674,7 @@ if unset, defaults to `anonymousUser`. === This element will add 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 only replay "GET" requests upon successful authentication. -Additional information can be found in the <> section of the reference. +Additional information can be found in the xref:overview/features/exploits/csrf.adoc#csrf[Cross Site Request Forgery (CSRF)] section of the reference. [[nsa-csrf-parents]] @@ -710,7 +710,7 @@ Default is any HTTP method except "GET", "TRACE", "HEAD", "OPTIONS". === This element is used to add a filter to the filter chain. It doesn't create any additional beans but is used to select a bean of type `javax.servlet.Filter` which is already defined in the application context and add that at a particular position in the filter chain maintained by Spring Security. -Full details can be found in the <>. +Full details can be found in the xref:servlet/namespace/index.adoc#ns-custom-filters[ namespace chapter]. [[nsa-custom-filter-parents]] @@ -871,7 +871,7 @@ Maps a `ForwardAuthenticationFailureHandler` to `authenticationFailureHandler` p [[nsa-oauth2-login]] === -The <> feature configures authentication support using an OAuth 2.0 and/or OpenID Connect 1.0 Provider. +The xref:servlet/oauth2/oauth2-login.adoc#oauth2login[OAuth 2.0 Login] feature configures authentication support using an OAuth 2.0 and/or OpenID Connect 1.0 Provider. [[nsa-oauth2-login-parents]] @@ -955,7 +955,7 @@ Reference to the `JwtDecoderFactory` used by `OidcAuthorizationCodeAuthenticatio [[nsa-oauth2-client]] === -Configures <> support. +Configures xref:servlet/oauth2/oauth2-client.adoc#oauth2client[OAuth 2.0 Client] support. [[nsa-oauth2-client-parents]] @@ -990,7 +990,7 @@ Reference to the `OAuth2AuthorizedClientService`. [[nsa-authorization-code-grant]] === -Configures <>. +Configures xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-auth-grant-support[OAuth 2.0 Authorization Code Grant]. [[nsa-authorization-code-grant-parents]] @@ -1020,7 +1020,7 @@ Reference to the `OAuth2AccessTokenResponseClient`. [[nsa-client-registrations]] === -A container element for client(s) registered (<>) with an OAuth 2.0 or OpenID Connect 1.0 Provider. +A container element for client(s) registered (xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration]) with an OAuth 2.0 or OpenID Connect 1.0 Provider. [[nsa-client-registrations-children]] @@ -1522,7 +1522,7 @@ Defaults to "username". [[nsa-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 <> section of the namespace configuration chapter. +An example can be found in the xref:servlet/authentication/openid.adoc#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). @@ -1616,7 +1616,7 @@ By default, an instance of `PortMapperImpl` will be added to the configuration f This element can optionally be used to override the default mappings which that class defines. Each child `` element defines a pair of HTTP:HTTPS ports. The default mappings are 80:443 and 8080:8443. -An example of overriding these can be found in <>. +An example of overriding these can be found in xref:servlet/exploits/http.adoc#servlet-http-redirect[]. [[nsa-port-mappings-parents]] @@ -2124,7 +2124,7 @@ This attribute allows you to define an alias name for the internal instance for [[nsa-authentication-manager-erase-credentials]] * **erase-credentials** If set to true, the AuthenticationManager will attempt to clear any credentials data in the returned Authentication object, once the user has been authenticated. -Literally it maps to the `eraseCredentialsAfterAuthentication` property of the <>. +Literally it maps to the `eraseCredentialsAfterAuthentication` property of the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`ProviderManager`]. [[nsa-authentication-manager-id]] @@ -2278,7 +2278,7 @@ select username, password, enabled from users where username = ? [[nsa-password-encoder]] === -Authentication providers can optionally be configured to use a password encoder as described in the <>. +Authentication providers can optionally be configured to use a password encoder as described in the xref:overview/features/authentication/password-storage.adoc#authentication-password-storage[]. This will result in the bean being injected with the appropriate `PasswordEncoder` instance. @@ -2625,7 +2625,7 @@ Defines a reference to a Spring bean Id. === Securing Methods using `` Rather than defining security attributes on an individual method or class basis using the `@Secured` annotation, you can define cross-cutting security constraints across whole sets of methods and interfaces in your service layer using the `` element. -You can find an example in the <>. +You can find an example in the xref:servlet/authorization/method-security.adoc#ns-protect-pointcut[namespace introduction]. [[nsa-protect-pointcut-parents]] @@ -2736,7 +2736,7 @@ A method name [[nsa-ldap]] == LDAP Namespace Options -LDAP is covered in some details in <>. +LDAP is covered in some details in xref:servlet/authentication/unpwd/ldap.adoc#servlet-authentication-ldap[its own chapter]. We will expand on that here with some explanation of how the namespace options map to Spring beans. The LDAP implementation uses Spring LDAP extensively, so some familiarity with that project's API may be useful. @@ -2746,7 +2746,7 @@ The LDAP implementation uses Spring LDAP extensively, so some familiarity with t `` Element This element sets up a Spring LDAP `ContextSource` for use by the other LDAP beans, defining the location of the LDAP server and other information (such as a username and password, if it doesn't allow anonymous access) for connecting to it. It can also be used to create an embedded server for testing. -Details of the syntax for both options are covered in the <>. +Details of the syntax for both options are covered in the xref:servlet/authentication/unpwd/ldap.adoc#servlet-authentication-ldap[LDAP chapter]. The actual `ContextSource` implementation is `DefaultSpringSecurityContextSource` which extends Spring LDAP's `LdapContextSource` class. The `manager-dn` and `manager-password` attributes map to the latter's `userDn` and `password` properties respectively. diff --git a/docs/modules/ROOT/pages/servlet/architecture/index.adoc b/docs/modules/ROOT/pages/servlet/architecture/index.adoc index c107f82fbd..61fcb9f401 100644 --- a/docs/modules/ROOT/pages/servlet/architecture/index.adoc +++ b/docs/modules/ROOT/pages/servlet/architecture/index.adoc @@ -3,7 +3,7 @@ :figures: servlet/architecture This section discusses Spring Security's high level architecture within Servlet based applications. -We build on this high level understanding within <>, <>, <> sections of the reference. +We build on this high level understanding within xref:servlet/authentication/index.adoc#servlet-authentication[], xref:servlet/authorization/index.adoc#servlet-authorization[], xref:servlet/exploits/index.adoc#servlet-exploits[] sections of the reference. // FIXME: Add links to other sections of architecture [[servlet-filters-review]] @@ -128,7 +128,7 @@ For that reason, if you are attempting to troubleshoot Spring Security's Servlet Second, since `FilterChainProxy` is central to Spring Security usage it can perform tasks that are not viewed as optional. // FIXME: Add a link to SecurityContext For example, it clears out the `SecurityContext` to avoid memory leaks. -It also applies Spring Security's <> to protect applications against certain types of attacks. +It also applies Spring Security's xref:servlet/exploits/firewall.adoc#servlet-httpfirewall[`HttpFirewall`] to protect applications against certain types of attacks. In addition, it provides more flexibility in determining when a `SecurityFilterChain` should be invoked. In a Servlet container, ``Filter``s are invoked based upon the URL alone. @@ -179,14 +179,14 @@ Below is a comprehensive list of Spring Security Filter ordering: * CasAuthenticationFilter * OAuth2LoginAuthenticationFilter * Saml2WebSsoAuthenticationFilter -* <> +* xref:servlet/authentication/unpwd/form.adoc#servlet-authentication-usernamepasswordauthenticationfilter[`UsernamePasswordAuthenticationFilter`] * OpenIDAuthenticationFilter * DefaultLoginPageGeneratingFilter * DefaultLogoutPageGeneratingFilter * ConcurrentSessionFilter -* <> +* xref:servlet/authentication/unpwd/digest.adoc#servlet-authentication-digest[`DigestAuthenticationFilter`] * BearerTokenAuthenticationFilter -* <> +* xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[`BasicAuthenticationFilter`] * RequestCacheAwareFilter * SecurityContextHolderAwareRequestFilter * JaasApiIntegrationFilter @@ -195,7 +195,7 @@ Below is a comprehensive list of Spring Security Filter ordering: * OAuth2AuthorizationCodeGrantFilter * SessionManagementFilter * <> -* <> +* xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] * SwitchUserFilter [[servlet-exceptiontranslationfilter]] @@ -211,7 +211,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 xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[] 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 @@ -243,6 +243,6 @@ try { } ---- <1> You will recall from <> that invoking `FilterChain.doFilter(request, response)` is the equivalent of invoking the rest of the application. -This means that if another part of the application, (i.e. <> or method security) throws an `AuthenticationException` or `AccessDeniedException` it will be caught and handled here. +This means that if another part of the application, (i.e. xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] or method security) throws an `AuthenticationException` or `AccessDeniedException` it will be caught and handled here. <2> If the user is not authenticated or it is an `AuthenticationException`, then __Start Authentication__. <3> Otherwise, __Access Denied__ diff --git a/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc b/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc index b98e87e075..d30fd584bf 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/anonymous.adoc @@ -96,7 +96,7 @@ If an `AccessDeniedException` is thrown, and the authentication is of an anonymo This is a necessary distinction, otherwise principals would always be deemed "authenticated" and never be given an opportunity to login via form, basic, digest or some other normal authentication mechanism. You will often see the `ROLE_ANONYMOUS` attribute in the above interceptor configuration replaced with `IS_AUTHENTICATED_ANONYMOUSLY`, which is effectively the same thing when defining access controls. -This is an example of the use of the `AuthenticatedVoter` which we will see in the <>. +This is an example of the use of the `AuthenticatedVoter` which we will see in the xref:servlet/authorization/architecture.adoc#authz-authenticated-voter[authorization chapter]. It uses an `AuthenticationTrustResolver` to process this particular configuration attribute and grant access to anonymous users. The `AuthenticatedVoter` approach is more powerful, since it allows you to differentiate between anonymous, remember-me and fully-authenticated users. If you don't need this functionality though, then you can stick with `ROLE_ANONYMOUS`, which will be processed by Spring Security's standard `RoleVoter`. diff --git a/docs/modules/ROOT/pages/servlet/authentication/architecture/index.adoc b/docs/modules/ROOT/pages/servlet/authentication/architecture/index.adoc index a688d41272..07b8afac58 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/architecture/index.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/architecture/index.adoc @@ -2,14 +2,14 @@ = Servlet Authentication Architecture :figures: servlet/authentication/architecture -This discussion expands on <> to describe 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 at the <> specific sections. +This discussion expands on xref:servlet/architecture/index.adoc#servlet-architecture[] to describe 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 at the xref:servlet/authentication/index.adoc#servlet-authentication-mechanisms[Authentication Mechanism] specific sections. -* <> - The `SecurityContextHolder` is where Spring Security stores the details of who is <>. +* <> - The `SecurityContextHolder` is where Spring Security stores the details of who is xref:overview/features/authentication/index.adoc#authentication[authenticated]. * <> - is obtained from the `SecurityContextHolder` and contains the `Authentication` of the currently authenticated user. * <> - Can be the input to `AuthenticationManager` to provide the credentials a user has provided to authenticate or the current user from the `SecurityContext`. * <> - An authority that is granted to the principal on the `Authentication` (i.e. roles, scopes, etc.) -* <> - the API that defines how Spring Security's Filters perform <>. +* <> - the API that defines how Spring Security's Filters perform xref:overview/features/authentication/index.adoc#authentication[authentication]. * <> - the most common implementation of `AuthenticationManager`. * <> - used by `ProviderManager` to perform a specific type of authentication. * <> - used for requesting credentials from a client (i.e. redirecting to a log in page, sending a `WWW-Authenticate` response, etc.) @@ -26,7 +26,7 @@ It contains the <>. image::{figures}/securitycontextholder.png[] -The `SecurityContextHolder` is where Spring Security stores the details of who is <>. +The `SecurityContextHolder` is where Spring Security stores the details of who is xref:overview/features/authentication/index.adoc#authentication[authenticated]. Spring Security does not care how the `SecurityContextHolder` is populated. If it contains a value, then it is used as the currently authenticated user. @@ -63,7 +63,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 <>. +Spring Security will use this information for xref:servlet/authorization/index.adoc#servlet-authorization[authorization]. If you wish to obtain information about the authenticated principal, you can do so by accessing the `SecurityContextHolder`. @@ -94,7 +94,7 @@ val authorities = authentication.authorities By default the `SecurityContextHolder` uses a `ThreadLocal` to store these details, which means that the `SecurityContext` is always available to methods in the same thread, even if the `SecurityContext` is not explicitly passed around as an argument to those methods. Using a `ThreadLocal` in this way is quite safe if care is taken to clear the thread after the present principal's request is processed. -Spring Security's <> ensures that the `SecurityContext` is always cleared. +Spring Security's xref:servlet/architecture/index.adoc#servlet-filterchainproxy[FilterChainProxy] ensures that the `SecurityContext` is always cleared. Some applications aren't entirely suitable for using a `ThreadLocal`, because of the specific way they work with threads. For example, a Swing client might want all threads in a Java Virtual Machine to use the same security context. @@ -125,7 +125,7 @@ The current `Authentication` can be obtained from the <>. +When authenticating with a username/password this is often an instance of xref:servlet/authentication/unpwd/user-details.adoc#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 <> are high level permissions the user is granted. @@ -141,7 +141,7 @@ A `GrantedAuthority` is, not surprisingly, an authority that is granted to the p 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. -When using username/password based authentication ``GrantedAuthority``s are usually loaded by the <>. +When using username/password based authentication ``GrantedAuthority``s are usually loaded by the xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`]. Usually the `GrantedAuthority` objects are application-wide permissions. They are not specific to a given domain object. @@ -151,8 +151,8 @@ Of course, Spring Security is expressly designed to handle this common requireme [[servlet-authentication-authenticationmanager]] == AuthenticationManager -{security-api-url}org/springframework/security/authentication/AuthenticationManager.html[`AuthenticationManager`] is the API that defines how Spring Security's Filters perform <>. -The <> that is returned is then set on the <> by the controller (i.e. <>) that invoked the `AuthenticationManager`. +{security-api-url}org/springframework/security/authentication/AuthenticationManager.html[`AuthenticationManager`] is the API that defines how Spring Security's Filters perform xref:overview/features/authentication/index.adoc#authentication[authentication]. +The <> that is returned is then set on the <> by the controller (i.e. xref:servlet/architecture/index.adoc#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 <>. @@ -179,7 +179,7 @@ The parent can be any type of `AuthenticationManager`, but it is often an instan image::{figures}/providermanager-parent.png[] In fact, multiple `ProviderManager` instances might share the same parent `AuthenticationManager`. -This is somewhat common in scenarios where there are multiple <> instances that have some authentication in common (the shared parent `AuthenticationManager`), but also different authentication mechanisms (the different `ProviderManager` instances). +This is somewhat common in scenarios where there are multiple xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] instances that have some authentication in common (the shared parent `AuthenticationManager`), but also different authentication mechanisms (the different `ProviderManager` instances). image::{figures}/providermanagers-parent.png[] @@ -199,7 +199,7 @@ See the {security-api-url}org/springframework/security/authentication/ProviderMa Multiple {security-api-url}org/springframework/security/authentication/AuthenticationProvider.html[``AuthenticationProvider``s] can be injected into <>. Each `AuthenticationProvider` performs a specific type of authentication. -For example, <> supports username/password based authentication while `JwtAuthenticationProvider` supports authenticating a JWT token. +For example, xref:servlet/authentication/unpwd/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] supports username/password based authentication while `JwtAuthenticationProvider` supports authenticating a JWT token. [[servlet-authentication-authenticationentrypoint]] == Request Credentials with `AuthenticationEntryPoint` @@ -211,7 +211,7 @@ 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 <>, respond with an <> header, etc. +The `AuthenticationEntryPoint` implementation might perform a xref:servlet/authentication/unpwd/form.adoc#servlet-authentication-form[redirect to a log in page], respond with an xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[WWW-Authenticate] header, etc. @@ -230,7 +230,7 @@ image::{figures}/abstractauthenticationprocessingfilter.png[] image:{icondir}/number_1.png[] When the user submits their credentials, the `AbstractAuthenticationProcessingFilter` creates an <> from the `HttpServletRequest` to be authenticated. The type of `Authentication` created depends on the subclass of `AbstractAuthenticationProcessingFilter`. -For example, <> creates a `UsernamePasswordAuthenticationToken` from a __username__ and __password__ that are submitted in the `HttpServletRequest`. +For example, xref:servlet/authentication/unpwd/form.adoc#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 <> is passed into the <> to be authenticated. diff --git a/docs/modules/ROOT/pages/servlet/authentication/cas.adoc b/docs/modules/ROOT/pages/servlet/authentication/cas.adoc index 5287dd6d92..35f3ad8c23 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/cas.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/cas.adoc @@ -92,7 +92,7 @@ The web application side of CAS is made easy due to Spring Security. It is assumed you already know the basics of using Spring Security, so these are not covered again below. We'll assume a namespace based configuration is being used and add in the CAS beans as required. Each section builds upon the previous section. -A full CAS sample application can be found in the Spring Security <>. +A full CAS sample application can be found in the Spring Security xref:overview/samples.adoc#samples[Samples]. [[cas-st]] @@ -139,7 +139,7 @@ The following beans should be configured to commence the CAS authentication proc ---- For CAS to operate, the `ExceptionTranslationFilter` must have its `authenticationEntryPoint` property set to the `CasAuthenticationEntryPoint` bean. -This can easily be done using <> as is done in the example above. +This can easily be done using xref:servlet/appendix/namespace.adoc#nsa-http-entry-point-ref[entry-point-ref] as is done in the example above. The `CasAuthenticationEntryPoint` must refer to the `ServiceProperties` bean (discussed above), which provides the URL to the enterprise's CAS login server. This is where the user's browser will be redirected. @@ -337,7 +337,7 @@ An example configuration is shown below. [[cas-pt-client-sample]] ==== Calling a Stateless Service Using a Proxy Ticket Now that Spring Security obtains PGTs, you can use them to create proxy tickets which can be used to authenticate to a stateless service. -The CAS <> contains a working example in the `ProxyTicketSampleServlet`. +The CAS xref:overview/samples.adoc#samples[sample application] contains a working example in the `ProxyTicketSampleServlet`. Example code can be found below: ==== diff --git a/docs/modules/ROOT/pages/servlet/authentication/index.adoc b/docs/modules/ROOT/pages/servlet/authentication/index.adoc index 9e976aff2b..3d8053ac1d 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/index.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/index.adoc @@ -1,8 +1,8 @@ [[servlet-authentication]] = Authentication -Spring Security provides comprehensive support for <>. -We start by discussing the overall <>. +Spring Security provides comprehensive support for xref:overview/features/authentication/index.adoc#authentication[]. +We start by discussing the overall xref:servlet/architecture/index.adoc#servlet-architecture[Servlet Authentication Architecture]. As you might expect, this section is more abstract describing the architecture without much discussion on how it applies to concrete flows. If you prefer, you can refer to <> for concrete ways in which users can authenticate. @@ -13,12 +13,12 @@ These sections focus on specific ways you may want to authenticate and point bac // FIXME: brief description -* <> - how to authenticate with a username/password -* <> - OAuth 2.0 Log In with OpenID Connect and non-standard OAuth 2.0 Login (i.e. GitHub) -* <> - SAML 2.0 Log In -* <> - Central Authentication Server (CAS) Support -* <> - how to remember a user past session expiration -* <> - authenticate with JAAS -* <> - OpenID Authentication (not to be confused with OpenID Connect) -* <> - 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. -* <> - X509 Authentication +* xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd[Username and Password] - how to authenticate with a username/password +* xref:servlet/oauth2/oauth2-login.adoc#oauth2login[OAuth 2.0 Login] - OAuth 2.0 Log In with OpenID Connect and non-standard OAuth 2.0 Login (i.e. GitHub) +* xref:servlet/saml2/index.adoc#servlet-saml2[SAML 2.0 Login] - SAML 2.0 Log In +* xref:servlet/authentication/cas.adoc#servlet-cas[Central Authentication Server (CAS)] - Central Authentication Server (CAS) Support +* xref:servlet/authentication/rememberme.adoc#servlet-rememberme[Remember Me] - how to remember a user past session expiration +* xref:servlet/authentication/jaas.adoc#servlet-jaas[JAAS Authentication] - authenticate with JAAS +* xref:servlet/authentication/openid.adoc#servlet-openid[OpenID] - OpenID Authentication (not to be confused with OpenID Connect) +* xref:servlet/authentication/preauth.adoc#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. +* xref:servlet/authentication/x509.adoc#servlet-x509[X509 Authentication] - X509 Authentication diff --git a/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc b/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc index 76671ba579..9e241932be 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/jaas.adoc @@ -166,5 +166,5 @@ This means that the `Subject` can be accessed using: Subject subject = Subject.getSubject(AccessController.getContext()); ---- -This integration can easily be configured using the <> attribute. +This integration can easily be configured using the xref:servlet/appendix/namespace.adoc#nsa-http-jaas-api-provision[jaas-api-provision] attribute. This feature is useful when integrating with legacy or external API's that rely on the JAAS Subject being populated. diff --git a/docs/modules/ROOT/pages/servlet/authentication/logout.adoc b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc index 9ad2110072..c529c9afed 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/logout.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/logout.adoc @@ -74,7 +74,7 @@ This is a shortcut for adding a `CookieClearingLogoutHandler` explicitly. [NOTE] ==== Logouts can of course also be configured using the XML Namespace notation. -Please see the documentation for the <> in the Spring Security XML Namespace section for further details. +Please see the documentation for the xref:servlet/appendix/namespace.adoc#nsa-logout[ logout element] in the Spring Security XML Namespace section for further details. ==== Generally, in order to customize logout functionality, you can add @@ -108,7 +108,7 @@ Various implementations are provided: - {security-api-url}org/springframework/security/web/authentication/logout/SecurityContextLogoutHandler.html[SecurityContextLogoutHandler] - {security-api-url}org/springframework/security/web/authentication/logout/HeaderWriterLogoutHandler.html[HeaderWriterLogoutHandler] -Please see <> for details. +Please see xref:servlet/authentication/rememberme.adoc#remember-me-impls[] for details. Instead of providing `LogoutHandler` implementations directly, the fluent API also provides shortcuts that provide the respective `LogoutHandler` implementations under the covers. E.g. `deleteCookies()` allows specifying the names of one or more cookies to be removed on logout success. @@ -140,9 +140,9 @@ If not configured a status code 200 will be returned by default. == Further Logout-Related References - <> -- <> -- <> -- <> -- <> in section CSRF Caveats -- Section <> (CAS protocol) -- Documentation for the <> in the Spring Security XML Namespace section +- xref:servlet/test/mockmvc.adoc#test-logout[ Testing Logout] +- xref:servlet/integrations/servlet-api.adoc#servletapi-logout[ HttpServletRequest.logout()] +- xref:servlet/authentication/rememberme.adoc#remember-me-impls[] +- xref:servlet/exploits/csrf.adoc#servlet-considerations-csrf-logout[ Logging Out] in section CSRF Caveats +- Section xref:servlet/authentication/cas.adoc#cas-singlelogout[ Single Logout] (CAS protocol) +- Documentation for the xref:servlet/appendix/namespace.adoc#nsa-logout[ logout element] in the Spring Security XML Namespace section diff --git a/docs/modules/ROOT/pages/servlet/authentication/openid.adoc b/docs/modules/ROOT/pages/servlet/authentication/openid.adoc index 9ecc0b8246..9ada981dd5 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/openid.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/openid.adoc @@ -53,7 +53,7 @@ OpenIDAuthenticationToken token = List attributes = token.getAttributes(); ---- -We can obtain the `OpenIDAuthenticationToken` from the <>. +We can obtain the `OpenIDAuthenticationToken` from the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[]. The `OpenIDAttribute` contains the attribute type and the retrieved value (or values in the case of multi-valued attributes). You can supply multiple `attribute-exchange` elements, using an `identifier-matcher` attribute on each. This contains a regular expression which will be matched against the OpenID identifier supplied by the user. diff --git a/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc b/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc index 67da7fc4b9..b6ad3ad06e 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/preauth.adoc @@ -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 <>, 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 xref:servlet/authentication/x509.adoc#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. @@ -86,14 +86,14 @@ The `PreAuthenticatedGrantedAuthoritiesUserDetailsService` class does this. Alternatively, it may delegate to a standard `UserDetailsService` via the `UserDetailsByNameServiceWrapper` implementation. === Http403ForbiddenEntryPoint -The <> is responsible for kick-starting the authentication process for an unauthenticated user (when they try to access a protected resource), but in the pre-authenticated case this doesn't apply. +The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is responsible for kick-starting the authentication process for an unauthenticated user (when they try to access a protected resource), but in the pre-authenticated case this doesn't apply. You would only configure the `ExceptionTranslationFilter` with an instance of this class if you aren't using pre-authentication in combination with other authentication mechanisms. It will be called if the user is rejected by the `AbstractPreAuthenticatedProcessingFilter` resulting in a null authentication. It always returns a `403`-forbidden response code if called. == Concrete Implementations -X.509 authentication is covered in its <>. +X.509 authentication is covered in its xref:servlet/authentication/x509.adoc#servlet-x509[own chapter]. Here we'll look at some classes which provide support for other pre-authenticated scenarios. @@ -139,7 +139,7 @@ A typical configuration using this filter would look like this: ---- -We've assumed here that the <> is being used for configuration. +We've assumed here that the xref:servlet/namespace/index.adoc#ns-config[security namespace] is being used for configuration. It's also assumed that you have added a `UserDetailsService` (called "userDetailsService") to your configuration to load the user's roles. diff --git a/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc b/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc index fd65a3ce62..e954e72ac7 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/rememberme.adoc @@ -36,7 +36,7 @@ If a principal is aware a token has been captured, they can easily change their 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. -If you are familiar with the topics discussed in the chapter on <>, you can enable remember-me authentication just by adding the `` element: +If you are familiar with the topics discussed in the chapter on xref:servlet/namespace/index.adoc#ns-config[namespace configuration], you can enable remember-me authentication just by adding the `` element: [source,xml] ---- diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/basic.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/basic.adoc index b03716b085..098d04672a 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/basic.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/basic.adoc @@ -11,14 +11,14 @@ First, we see the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authentica .Sending WWW-Authenticate Header image::{figures}/basicauthenticationentrypoint.png[] -The figure builds off our <> diagram. +The figure builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram. image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized. -image:{icondir}/number_2.png[] Spring Security's <> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. +image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. -image:{icondir}/number_3.png[] Since the user is not authenticated, <> initiates __Start Authentication__. -The configured <> is an instance of {security-api-url}org/springframework/security/web/authentication/www/BasicAuthenticationEntryPoint.html[`BasicAuthenticationEntryPoint`] which sends a WWW-Authenticate header. +image:{icondir}/number_3.png[] Since the user is not authenticated, xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__. +The configured xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is an instance of {security-api-url}org/springframework/security/web/authentication/www/BasicAuthenticationEntryPoint.html[`BasicAuthenticationEntryPoint`] which sends a WWW-Authenticate header. The `RequestCache` is typically a `NullRequestCache` that does not save the request since the client is capable of replaying the requests it originally requested. When a client receives the WWW-Authenticate header it knows it should retry with a username and password. @@ -28,17 +28,17 @@ Below is the flow for the username and password being processed. .Authenticating Username and Password image::{figures}/basicauthenticationfilter.png[] -The figure builds off our <> diagram. +The figure builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram. -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_1.png[] When the user submits their username and password, the `BasicAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] 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` looks like depend on how the <>. +The details of what `AuthenticationManager` looks like depend on how the xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-storage[user information is stored]. image:{icondir}/number_3.png[] If authentication fails, then __Failure__ -* The <> is cleared out. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[] is cleared out. * `RememberMeServices.loginFail` is invoked. If remember me is not configured, this is a no-op. // FIXME: link to rememberme @@ -46,7 +46,7 @@ If remember me is not configured, this is a no-op. image:{icondir}/number_4.png[] If authentication is successful, then __Success__. -* The <> is set on the <>. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[]. * `RememberMeServices.loginSuccess` is invoked. If remember me is not configured, this is a no-op. // FIXME: link to rememberme diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/dao-authentication-provider.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/dao-authentication-provider.adoc index f7283e58ee..3d716d14c2 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/dao-authentication-provider.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/dao-authentication-provider.adoc @@ -2,21 +2,21 @@ = DaoAuthenticationProvider :figures: servlet/authentication/unpwd -{security-api-url}org/springframework/security/authentication/dao/DaoAuthenticationProvider.html[`DaoAuthenticationProvider`] is an <> implementation that leverages a <> and <> to authenticate a username and password. +{security-api-url}org/springframework/security/authentication/dao/DaoAuthenticationProvider.html[`DaoAuthenticationProvider`] is an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`] and xref:servlet/authentication/unpwd/password-encoder.adoc#servlet-authentication-password-storage[`PasswordEncoder`] to authenticate a username and password. Let's take a look at how `DaoAuthenticationProvider` works within Spring Security. -The figure explains details of how the <> in figures from <> works. +The figure explains details of how the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-input[Reading the Username & Password] works. .`DaoAuthenticationProvider` Usage image::{figures}/daoauthenticationprovider.png[] -image:{icondir}/number_1.png[] The authentication `Filter` from <> passes a `UsernamePasswordAuthenticationToken` to the `AuthenticationManager` which is implemented by <>. +image:{icondir}/number_1.png[] The authentication `Filter` from xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-input[Reading the Username & Password] passes a `UsernamePasswordAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`ProviderManager`]. -image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an <> of type `DaoAuthenticationProvider`. +image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationprovider[] of type `DaoAuthenticationProvider`. image:{icondir}/number_3.png[] `DaoAuthenticationProvider` looks up the `UserDetails` from the `UserDetailsService`. -image:{icondir}/number_4.png[] `DaoAuthenticationProvider` then uses the <> to validate the password on the `UserDetails` returned in the previous step. +image:{icondir}/number_4.png[] `DaoAuthenticationProvider` then uses the xref:servlet/authentication/unpwd/password-encoder.adoc#servlet-authentication-password-storage[`PasswordEncoder`] to validate the password on the `UserDetails` returned in the previous step. -image:{icondir}/number_5.png[] When authentication is successful, the <> that is returned is of type `UsernamePasswordAuthenticationToken` and has a principal that is the `UserDetails` returned by the configured `UserDetailsService`. -Ultimately, the returned `UsernamePasswordAuthenticationToken` will be set on the <> by the authentication `Filter`. +image:{icondir}/number_5.png[] When authentication is successful, the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] that is returned is of type `UsernamePasswordAuthenticationToken` and has a principal that is the `UserDetails` returned by the configured `UserDetailsService`. +Ultimately, the returned `UsernamePasswordAuthenticationToken` will be set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`. diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/digest.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/digest.adoc index 3503f3f21c..51763da932 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/digest.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/digest.adoc @@ -11,14 +11,14 @@ All of these storage formats are considered insecure. Instead, you should store credentials using a one way adaptive password hash (i.e. bCrypt, PBKDF2, SCrypt, etc) which is not supported by Digest Authentication. ==== -Digest Authentication attempts to solve many of the weaknesses of <>, specifically by ensuring credentials are never sent in clear text across the wire. +Digest Authentication attempts to solve many of the weaknesses of xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[Basic authentication], specifically by ensuring credentials are never sent in clear text across the wire. Many https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Digest#Browser_compatibility[browsers support Digest Authentication]. The standard governing HTTP Digest Authentication is defined by https://tools.ietf.org/html/rfc2617[RFC 2617], which updates an earlier version of the Digest Authentication standard prescribed by https://tools.ietf.org/html/rfc2069[RFC 2069]. Most user agents implement RFC 2617. Spring Security's Digest Authentication support is compatible with the "`auth`" quality of protection (`qop`) prescribed by RFC 2617, which also provides backward compatibility with RFC 2069. Digest Authentication was seen as a more attractive option if you need to use unencrypted HTTP (i.e. no TLS/HTTPS) and wish to maximise security of the authentication process. -However, everyone should use <>. +However, everyone should use xref:overview/features/exploits/http.adoc#http[HTTPS]. Central to Digest Authentication is a "nonce". This is a value the server generates. @@ -34,7 +34,7 @@ key: A private key to prevent modification of the nonce token ---- ==== -You will need to ensure you <> insecure plain text <> using `NoOpPasswordEncoder`. +You will need to ensure you xref:overview/features/authentication/password-storage.adoc#authentication-password-storage-configuration[configure] insecure plain text xref:overview/features/authentication/password-storage.adoc#authentication-password-storage[Password Storage] using `NoOpPasswordEncoder`. The following provides an example of configuring Digest Authentication with Java Configuration: .Digest Authentication diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/form.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/form.adoc index f22ebdd992..8ecd652912 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/form.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/form.adoc @@ -12,13 +12,13 @@ First, we see how the user is redirected to the log in form. .Redirecting to the Log In Page image::{figures}/loginurlauthenticationentrypoint.png[] -The figure builds off our <> diagram. +The figure builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram. image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized. -image:{icondir}/number_2.png[] Spring Security's <> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. +image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. -image:{icondir}/number_3.png[] Since the user is not authenticated, <> initiates __Start Authentication__ and sends a redirect to the log in page with the configured <>. +image:{icondir}/number_3.png[] Since the user is not authenticated, xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__ and sends a redirect to the log in page with the configured xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`]. In most cases the `AuthenticationEntryPoint` is an instance of {security-api-url}org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html[`LoginUrlAuthenticationEntryPoint`]. image:{icondir}/number_4.png[] The browser will then request the log in page that it was redirected to. @@ -27,22 +27,22 @@ image:{icondir}/number_5.png[] Something within the application, must <>, so this diagram should look pretty similar. +The `UsernamePasswordAuthenticationFilter` extends xref:servlet/authentication/architecture/index.adoc#servlet-authentication-abstractprocessingfilter[], so this diagram should look pretty similar. .Authenticating Username and Password image::{figures}/usernamepasswordauthenticationfilter.png[] -The figure builds off our <> diagram. +The figure builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram. -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_1.png[] When the user submits their username and password, the `UsernamePasswordAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken` which is a type of xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] 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` looks like depend on how the <>. +The details of what `AuthenticationManager` looks like depend on how the xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-storage[user information is stored]. image:{icondir}/number_3.png[] If authentication fails, then __Failure__ -* The <> is cleared out. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[] is cleared out. * `RememberMeServices.loginFail` is invoked. If remember me is not configured, this is a no-op. // FIXME: link to rememberme @@ -53,13 +53,13 @@ image:{icondir}/number_4.png[] If authentication is successful, then __Success__ * `SessionAuthenticationStrategy` is notified of a new log in. // FIXME: Add link to SessionAuthenticationStrategy -* The <> is set on the <>. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[]. // FIXME: link securitycontextpersistencefilter * `RememberMeServices.loginSuccess` is invoked. If remember me is not configured, this is a no-op. // FIXME: link to rememberme * `ApplicationEventPublisher` publishes an `InteractiveAuthenticationSuccessEvent`. -* The `AuthenticationSuccessHandler` is invoked. Typically this is a `SimpleUrlAuthenticationSuccessHandler` which will redirect to a request saved by <> when we redirect to the log in page. +* The `AuthenticationSuccessHandler` is invoked. Typically this is a `SimpleUrlAuthenticationSuccessHandler` which will redirect to a request saved by xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] when we redirect to the log in page. [[servlet-authentication-form-min]] Spring Security form log in is enabled by default. @@ -183,7 +183,7 @@ Below is a https://www.thymeleaf.org/[Thymeleaf] template that produces an HTML There are a few key points about the default HTML form: * The form should perform a `post` to `/login` -* The form will need to include a <> which is <> by Thymeleaf. +* The form will need to include a xref:servlet/exploits/csrf.adoc#servlet-csrf[CSRF Token] which is xref:servlet/exploits/csrf.adoc#servlet-csrf-include-form-auto[automatically included] by Thymeleaf. * The form should specify the username in a parameter named `username` * The form should specify the password in a parameter named `password` * If the HTTP parameter error is found, it indicates the user failed to provide a valid username / password diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/in-memory.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/in-memory.adoc index d5b178516b..b080006d50 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/in-memory.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/in-memory.adoc @@ -1,11 +1,11 @@ [[servlet-authentication-inmemory]] = In-Memory Authentication -Spring Security's `InMemoryUserDetailsManager` implements <> to provide support for username/password based authentication that is stored in memory. +Spring Security's `InMemoryUserDetailsManager` implements xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[UserDetailsService] 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. +`UserDetails` based authentication is used by Spring Security when it is configured to xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-input[accept a username/password] for authentication. -In this sample we use <> to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`. +In this sample we use xref:overview/features/authentication/password-storage.adoc#authentication-password-storage-boot-cli[Spring Boot CLI] to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`. .InMemoryUserDetailsManager Java Configuration ==== @@ -64,7 +64,7 @@ fun users(): UserDetailsService { The samples above store the passwords in a secure format, but leave a lot to be desired in terms of getting started experience. -In the sample below we leverage <> to ensure that the password stored in memory is protected. +In the sample below we leverage xref:overview/features/authentication/password-storage.adoc#authentication-password-storage-dep-getting-started[User.withDefaultPasswordEncoder] to ensure that the password stored in memory is protected. However, it does not protect against obtaining the password by decompiling the source code. For this reason, `User.withDefaultPasswordEncoder` should only be used for "getting started" and is not intended for production. @@ -114,7 +114,7 @@ fun users(): UserDetailsService { ==== There is no simple way to use `User.withDefaultPasswordEncoder` with XML based configuration. -For demos or just getting started, you can choose to prefix the password with `+{noop}+` to indicate <>. +For demos or just getting started, you can choose to prefix the password with `+{noop}+` to indicate xref:overview/features/authentication/password-storage.adoc#authentication-password-storage-dpe-format[no encoding should be used]. . `+{noop}+` XML Configuration ==== diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/index.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/index.adoc index e59dedf3da..c87a68217a 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/index.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/index.adoc @@ -11,17 +11,17 @@ As such, Spring Security provides comprehensive support for authenticating with Spring Security provides the following built in mechanisms for reading a username and password from the `HttpServletRequest`: -* <> -* <> -* <> +* xref:servlet/authentication/unpwd/form.adoc#servlet-authentication-form[Form Login] +* xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[Basic Authentication] +* xref:servlet/authentication/unpwd/digest.adoc#servlet-authentication-digest[Digest Authentication] [[servlet-authentication-unpwd-storage]] == Storage Mechanisms Each of the supported mechanisms for reading a username and password can leverage any of the supported storage mechanisms: -* Simple Storage with <> -* Relational Databases with <> -* Custom data stores with <> -* LDAP storage with <> +* Simple Storage with xref:servlet/authentication/unpwd/in-memory.adoc#servlet-authentication-inmemory[] +* Relational Databases with xref:servlet/authentication/unpwd/jdbc.adoc#servlet-authentication-jdbc[] +* Custom data stores with xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[] +* LDAP storage with xref:servlet/authentication/unpwd/ldap.adoc#servlet-authentication-ldap[] diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/jdbc.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/jdbc.adoc index 009e551512..75055a6a8f 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/jdbc.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/jdbc.adoc @@ -1,9 +1,9 @@ [[servlet-authentication-jdbc]] = JDBC Authentication -Spring Security's `JdbcDaoImpl` implements <> to provide support for username/password based authentication that is retrieved using JDBC. +Spring Security's `JdbcDaoImpl` implements xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[UserDetailsService] to provide support for username/password based authentication that is retrieved using JDBC. `JdbcUserDetailsManager` extends `JdbcDaoImpl` to provide management of `UserDetails` through the `UserDetailsManager` interface. -`UserDetails` based authentication is used by Spring Security when it is configured to <> for authentication. +`UserDetails` based authentication is used by Spring Security when it is configured to xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-input[accept a username/password] for authentication. In the following sections we will discuss: @@ -147,8 +147,8 @@ In a production environment, you will want to ensure you setup a connection to a [[servlet-authentication-jdbc-bean]] == JdbcUserDetailsManager Bean -In this sample we use <> to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`. -See the <> section for more details about how to store passwords. +In this sample we use xref:overview/features/authentication/password-storage.adoc#authentication-password-storage-boot-cli[Spring Boot CLI] to encode the password of `password` and get the encoded password of `+{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW+`. +See the xref:overview/features/authentication/password-storage.adoc#authentication-password-storage[PasswordEncoder] section for more details about how to store passwords. .JdbcUserDetailsManager ==== diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/ldap.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/ldap.adoc index 57f456deb8..aa3d327c05 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/ldap.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/ldap.adoc @@ -4,7 +4,7 @@ LDAP is often used by organizations as a central repository for user information and as an authentication service. It can also be used to store the role information for application users. -Spring Security's LDAP based authentication is used by Spring Security when it is configured to <> for authentication. +Spring Security's LDAP based authentication is used by Spring Security when it is configured to xref:servlet/authentication/unpwd/index.adoc#servlet-authentication-unpwd-input[accept a username/password] for authentication. However, despite leveraging a username/password for authentication it does not integrate using `UserDetailsService` because in <> the LDAP server does not return the password so the application cannot perform validation of the password. There are many different scenarios for how an LDAP server may be configured so Spring Security's LDAP provider is fully configurable. @@ -258,7 +258,7 @@ fun contextSource(container: UnboundIdContainer): ContextSource { [[servlet-authentication-ldap-authentication]] == Authentication -Spring Security's LDAP support does not use the <> because LDAP bind authentication does not allow clients to read the password or even a hashed version of the password. +Spring Security's LDAP support does not use the xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[] because LDAP bind authentication does not allow clients to read the password or even a hashed version of the password. This means there is no way a password to be read and then authenticated by Spring Security. For this reason, LDAP support is implemented using the `LdapAuthenticator` interface. diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/password-encoder.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/password-encoder.adoc index 73f9e1f2e1..aa443acdf6 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/password-encoder.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/password-encoder.adoc @@ -1,5 +1,5 @@ [[servlet-authentication-password-storage]] = PasswordEncoder -Spring Security's servlet support storing passwords securely by integrating with <>. -Customizing the `PasswordEncoder` implementation used by Spring Security can be done by <>. +Spring Security's servlet support storing passwords securely by integrating with xref:overview/features/authentication/password-storage.adoc#authentication-password-storage[`PasswordEncoder`]. +Customizing the `PasswordEncoder` implementation used by Spring Security can be done by xref:overview/features/authentication/password-storage.adoc#authentication-password-storage-configuration[exposing a `PasswordEncoder` Bean]. diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details-service.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details-service.adoc index 9147cedbd2..92a1d3519f 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details-service.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details-service.adoc @@ -1,8 +1,8 @@ [[servlet-authentication-userdetailsservice]] = UserDetailsService -{security-api-url}org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] is used by <> for retrieving a username, password, and other attributes for authenticating with a username and password. -Spring Security provides <> and <> implementations of `UserDetailsService`. +{security-api-url}org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] is used by xref:servlet/authentication/unpwd/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] for retrieving a username, password, and other attributes for authenticating with a username and password. +Spring Security provides xref:servlet/authentication/unpwd/in-memory.adoc#servlet-authentication-inmemory[in-memory] and xref:servlet/authentication/unpwd/jdbc.adoc#servlet-authentication-jdbc[JDBC] implementations of `UserDetailsService`. You can define custom authentication by exposing a custom `UserDetailsService` as a bean. For example, the following will customize authentication assuming that `CustomUserDetailsService` implements `UserDetailsService`: diff --git a/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details.adoc b/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details.adoc index d56626b37e..1b55e00a0b 100644 --- a/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details.adoc +++ b/docs/modules/ROOT/pages/servlet/authentication/unpwd/user-details.adoc @@ -1,5 +1,5 @@ [[servlet-authentication-userdetails]] = UserDetails -{security-api-url}org/springframework/security/core/userdetails/UserDetails.html[`UserDetails`] is returned by the <>. -The <> validates the `UserDetails` and then returns an <> that has a principal that is the `UserDetails` returned by the configured `UserDetailsService`. +{security-api-url}org/springframework/security/core/userdetails/UserDetails.html[`UserDetails`] is returned by the xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`]. +The xref:servlet/authentication/unpwd/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] validates the `UserDetails` and then returns an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] that has a principal that is the `UserDetails` returned by the configured `UserDetailsService`. diff --git a/docs/modules/ROOT/pages/servlet/authorization/architecture.adoc b/docs/modules/ROOT/pages/servlet/authorization/architecture.adoc index 2be495a653..32363ae6c6 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/architecture.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/architecture.adoc @@ -6,7 +6,7 @@ [[authz-authorities]] == Authorities -<>, discusses how all `Authentication` implementations store a list of `GrantedAuthority` objects. +xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`], 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. diff --git a/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc b/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc index 055ab80c20..60f4d69251 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc @@ -2,22 +2,22 @@ = Authorize HttpServletRequest with FilterSecurityInterceptor :figures: servlet/authorization -This section builds on <> by digging deeper into how <> works within Servlet based applications. +This section builds on xref:servlet/architecture/index.adoc#servlet-architecture[Servlet Architecture and Implementation] by digging deeper into how xref:servlet/authorization/index.adoc#servlet-authorization[authorization] works within Servlet based applications. -The {security-api-url}org/springframework/security/web/access/intercept/FilterSecurityInterceptor.html[`FilterSecurityInterceptor`] provides <> for ``HttpServletRequest``s. -It is inserted into the <> as one of the <>. +The {security-api-url}org/springframework/security/web/access/intercept/FilterSecurityInterceptor.html[`FilterSecurityInterceptor`] provides xref:servlet/authorization/index.adoc#servlet-authorization[authorization] for ``HttpServletRequest``s. +It is inserted into the xref:servlet/architecture/index.adoc#servlet-filterchainproxy[] as one of the xref:servlet/architecture/index.adoc#servlet-security-filters[]. .Authorize HttpServletRequest image::{figures}/filtersecurityinterceptor.png[] -* image:{icondir}/number_1.png[] First, the `FilterSecurityInterceptor` obtains an <> from the <>. +* image:{icondir}/number_1.png[] First, the `FilterSecurityInterceptor` obtains an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[] from the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[]. * image:{icondir}/number_2.png[] Second, `FilterSecurityInterceptor` creates a {security-api-url}org/springframework/security/web/FilterInvocation.html[`FilterInvocation`] from the `HttpServletRequest`, `HttpServletResponse`, and `FilterChain` that are passed into the `FilterSecurityInterceptor`. // FIXME: link to FilterInvocation * image:{icondir}/number_3.png[] Next, it passes the `FilterInvocation` to `SecurityMetadataSource` to get the ``ConfigAttribute``s. * image:{icondir}/number_4.png[] Finally, it passes the `Authentication`, `FilterInvocation`, and ``ConfigAttribute``s to the `AccessDecisionManager`. ** image:{icondir}/number_5.png[] If authorization is denied, an `AccessDeniedException` is thrown. -In this case the <> handles the `AccessDeniedException`. -** image:{icondir}/number_6.png[] If access is granted, `FilterSecurityInterceptor` continues with the <> which allows the application to process normally. +In this case the xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] handles the `AccessDeniedException`. +** image:{icondir}/number_6.png[] If access is granted, `FilterSecurityInterceptor` continues with the xref:servlet/architecture/index.adoc#servlet-filters-review[FilterChain] which allows the application to process normally. // configuration (xml/java) diff --git a/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc index ce49cdd45e..8b194fd275 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc @@ -3,7 +3,7 @@ From version 2.0 onwards Spring Security has improved support substantially for adding security to your service layer methods. It provides support for JSR-250 annotation security as well as the framework's original `@Secured` annotation. -From 3.0 you can also make use of new <>. +From 3.0 you can also make use of new xref:servlet/authorization/expression-based.adoc#el-access[expression-based annotations]. You can apply security to a single bean, using the `intercept-methods` element to decorate the bean declaration, or you can secure multiple beans across the entire service layer using the AspectJ style pointcuts. == EnableMethodSecurity diff --git a/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc b/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc index 5c24678b16..59d2f96e4b 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/secure-objects.adoc @@ -5,7 +5,7 @@ [[aop-alliance]] == AOP Alliance (MethodInvocation) Security Interceptor Prior to Spring Security 2.0, securing ``MethodInvocation``s needed quite a lot of boiler plate configuration. -Now the recommended approach for method security is to use <>. +Now the recommended approach for method security is to use xref:servlet/namespace/index.adoc#ns-method-security[namespace configuration]. This way the method security infrastructure beans are configured automatically for you so you don't really need to know about the implementation classes. We'll just provide a quick overview of the classes that are involved here. diff --git a/docs/modules/ROOT/pages/servlet/exploits/csrf.adoc b/docs/modules/ROOT/pages/servlet/exploits/csrf.adoc index 117de637a2..aaa47d88b7 100644 --- a/docs/modules/ROOT/pages/servlet/exploits/csrf.adoc +++ b/docs/modules/ROOT/pages/servlet/exploits/csrf.adoc @@ -1,7 +1,7 @@ [[servlet-csrf]] = Cross Site Request Forgery (CSRF) for Servlet Environments -This section discusses Spring Security's <> support for servlet environments. +This section discusses Spring Security's xref:overview/features/exploits/csrf.adoc#csrf[Cross Site Request Forgery (CSRF)] support for servlet environments. [[servlet-csrf-using]] == Using Spring Security CSRF Protection @@ -14,7 +14,7 @@ The steps to using Spring Security's CSRF protection are outlined below: [[servlet-csrf-idempotent]] === Use proper HTTP verbs The first step to protecting against CSRF attacks is to ensure your website uses proper HTTP verbs. -This is covered in detail in <>. +This is covered in detail in xref:overview/features/exploits/csrf.adoc#csrf-protection-idempotent[Safe Methods Must be Idempotent]. [[servlet-csrf-configure]] === Configure CSRF Protection @@ -105,7 +105,7 @@ If you do not need the ability to read the cookie with JavaScript directly, it i [[servlet-csrf-configure-disable]] ==== Disable CSRF Protection CSRF protection is enabled by default. -However, it is simple to disable CSRF protection if it <>. +However, it is simple to disable CSRF protection if it xref:overview/features/exploits/csrf.adoc#csrf-when[makes sense for your application]. The XML configuration below will disable CSRF protection. @@ -162,7 +162,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-csrf-include]] === Include the CSRF Token -In order for the <> to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request. +In order for the xref:overview/features/exploits/csrf.adoc#csrf-protection-stp[synchronizer token pattern] to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request. This must be included in a part of the request (i.e. form parameter, HTTP header, etc) that is not automatically included in the HTTP request by the browser. Spring Security's https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/csrf/CsrfFilter.html[CsrfFilter] exposes a https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/csrf/CsrfToken.html[CsrfToken] as an `HttpServletRequest` attribute named `_csrf`. @@ -196,7 +196,7 @@ This means that if you leverage https://docs.spring.io/spring/docs/current/sprin ===== csrfInput Tag If you are using JSPs, then you can use https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-view-jsp-formtaglib[Spring’s form tag library]. -However, if that is not an option, you can also easily include the token with the <> tag. +However, if that is not an option, you can also easily include the token with the xref:servlet/integrations/jsp-taglibs.adoc#taglibs-csrfinput[csrfInput] tag. [[servlet-csrf-include-form-attr]] ===== CsrfToken Request Attribute @@ -274,7 +274,7 @@ $(function () { [[servlet-csrf-include-ajax-meta-tag]] ====== csrfMeta tag -If you are using JSPs a simple way to write the CSRF token to the `meta` tags is by leveraging the <> tag. +If you are using JSPs a simple way to write the CSRF token to the `meta` tags is by leveraging the xref:servlet/integrations/jsp-taglibs.adoc#taglibs-csrfmeta[csrfMeta] tag. [[servlet-csrf-include-ajax-meta-attr]] ====== CsrfToken Request Attribute @@ -301,19 +301,19 @@ An example of doing this with a JSP is shown below: == CSRF Considerations There are a few special considerations to consider when implementing protection against CSRF attacks. This section discusses those considerations as it pertains to servlet environments. -Refer to <> for a more general discussion. +Refer to xref:overview/features/exploits/csrf.adoc#csrf-considerations[] for a more general discussion. [[servlet-considerations-csrf-login]] === Logging In -It is important to <> requests to protect against forging log in attempts. +It is important to xref:overview/features/exploits/csrf.adoc#csrf-considerations-login[require CSRF for log in] requests to protect against forging log in attempts. Spring Security's servlet support does this out of the box. [[servlet-considerations-csrf-logout]] === Logging Out -It is important to <> requests to protect against forging log out attempts. +It is important to xref:overview/features/exploits/csrf.adoc#csrf-considerations-logout[require CSRF for log out] requests to protect against forging log out attempts. If CSRF protection is enabled (default), Spring Security's `LogoutFilter` to only process HTTP POST. This ensures that log out requires a CSRF token and that a malicious user cannot forcibly log out your users. @@ -367,7 +367,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { By default Spring Security stores the CSRF token in the `HttpSession`. This can lead to a situation where the session expires which means there is not an expected CSRF token to validate against. -We've already discussed <> to session timeouts. +We've already discussed xref:overview/features/exploits/csrf.adoc#csrf-considerations-login[general solutions] to session timeouts. This section discusses the specifics of CSRF timeouts as it pertains to the servlet support. It is simple to change storage of the expected CSRF token to be in a cookie. @@ -375,13 +375,13 @@ For details, refer to the <> section. If a token does expire, you might want to customize how it is handled by specifying a custom `AccessDeniedHandler`. The custom `AccessDeniedHandler` can process the `InvalidCsrfTokenException` any way you like. -For an example of how to customize the `AccessDeniedHandler` refer to the provided links for both <> and {gh-url}/config/src/test/java/org/springframework/security/config/annotation/web/configurers/NamespaceHttpServerAccessDeniedHandlerTests.java#L64[Java configuration]. +For an example of how to customize the `AccessDeniedHandler` refer to the provided links for both xref:servlet/appendix/namespace.adoc#nsa-access-denied-handler[xml] and {gh-url}/config/src/test/java/org/springframework/security/config/annotation/web/configurers/NamespaceHttpServerAccessDeniedHandlerTests.java#L64[Java configuration]. // FIXME: We should add a custom AccessDeniedHandler section in the reference and update the links above [[servlet-csrf-considerations-multipart]] === Multipart (file upload) -We have <> how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem. +We have xref:overview/features/exploits/csrf.adoc#csrf-considerations-multipart[already discussed] how protecting multipart requests (file uploads) from CSRF attacks causes a https://en.wikipedia.org/wiki/Chicken_or_the_egg[chicken and the egg] problem. This section discusses how to implement placing the CSRF token in the <> and <> within a servlet application. [NOTE] @@ -392,7 +392,7 @@ More information about using multipart forms with Spring can be found within the [[servlet-csrf-considerations-multipart-body]] ==== Place CSRF Token in the Body -We have <> the tradeoffs of placing the CSRF token in the body. +We have xref:overview/features/exploits/csrf.adoc#csrf-considerations-multipart-body[already discussed] the tradeoffs of placing the CSRF token in the body. In this section we will discuss how to configure Spring Security to read the CSRF from the body. In order to read the CSRF token from the body, the `MultipartFilter` is specified before the Spring Security filter. @@ -473,7 +473,7 @@ An example with a jsp is shown below [[servlet-csrf-considerations-override-method]] === HiddenHttpMethodFilter -We have <> the trade-offs of placing the CSRF token in the body. +We have xref:overview/features/exploits/csrf.adoc#csrf-considerations-multipart-body[already discussed] the trade-offs of placing the CSRF token in the body. In Spring's Servlet support, overriding the HTTP method is done using https://docs.spring.io/spring-framework/docs/5.2.x/javadoc-api/org/springframework/web/filter/reactive/HiddenHttpMethodFilter.html[HiddenHttpMethodFilter]. More information can be found in https://docs.spring.io/spring/docs/5.2.x/spring-framework-reference/web.html#mvc-rest-method-conversion[HTTP Method Conversion] section of the reference documentation. diff --git a/docs/modules/ROOT/pages/servlet/exploits/headers.adoc b/docs/modules/ROOT/pages/servlet/exploits/headers.adoc index e45c5c96c9..734271c6b0 100644 --- a/docs/modules/ROOT/pages/servlet/exploits/headers.adoc +++ b/docs/modules/ROOT/pages/servlet/exploits/headers.adoc @@ -1,13 +1,13 @@ [[servlet-headers]] = Security HTTP Response Headers -<> can be used to increase the security of web applications. +xref:overview/features/exploits/headers.adoc#headers[Security HTTP Response Headers] can be used to increase the security of web applications. This section is dedicated to servlet based support for Security HTTP Response Headers. [[servlet-headers-default]] == Default Security Headers -Spring Security provides a <> to provide secure defaults. +Spring Security provides a xref:overview/features/exploits/headers.adoc#headers-default[default set of Security HTTP Response Headers] to provide secure defaults. While each of these headers are considered best practice, it should be noted that not all clients utilize the headers, so additional testing is encouraged. You can customize specific headers. @@ -71,7 +71,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { If you do not want the defaults to be added and want explicit control over what should be used, you can disable the defaults. An example is provided below: -If you are using Spring Security's Configuration the following will only add <>. +If you are using Spring Security's Configuration the following will only add xref:overview/features/exploits/headers.adoc#headers-cache-control[Cache Control]. .Customize Cache Control Headers ==== @@ -177,7 +177,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-cache-control]] == Cache Control -Spring Security includes <> headers by default. +Spring Security includes xref:overview/features/exploits/headers.adoc#headers-cache-control[Cache Control] headers by default. However, if you actually want to cache specific responses, your application can selectively invoke https://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletResponse.html#setHeader(java.lang.String,java.lang.String)[HttpServletResponse.setHeader(String,String)] to override the header set by Spring Security. This is useful to ensure things like CSS, JavaScript, and images are properly cached. @@ -242,7 +242,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-content-type-options]] == Content Type Options -Spring Security includes <> headers by default. +Spring Security includes xref:overview/features/exploits/headers.adoc#headers-content-type-options[Content-Type] headers by default. However, you can disable it with: .Content Type Options Disabled @@ -300,7 +300,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-hsts]] == HTTP Strict Transport Security (HSTS) -Spring Security provides the <> header by default. +Spring Security provides the xref:overview/features/exploits/headers.adoc#headers-hsts[Strict Transport Security] header by default. However, you can customize the results explicitly. For example, the following is an example of explicitly providing HSTS: @@ -366,7 +366,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-hpkp]] == HTTP Public Key Pinning (HPKP) -For passivity reasons, Spring Security provides servlet support for <> but it is <>. +For passivity reasons, Spring Security provides servlet support for xref:overview/features/exploits/headers.adoc#headers-hpkp[HTTP Public Key Pinning] but it is xref:overview/features/exploits/headers.adoc#headers-hpkp-deprecated[no longer recommended]. You can enable HPKP headers with the following Configuration: @@ -437,7 +437,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-frame-options]] == X-Frame-Options -By default, Spring Security disables rendering within an iframe using <>. +By default, Spring Security disables rendering within an iframe using xref:overview/features/exploits/headers.adoc#headers-frame-options[X-Frame-Options]. You can customize frame options to use the same origin within a Configuration using the following: @@ -560,7 +560,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-csp]] == Content Security Policy (CSP) -Spring Security does not add <> by default, because a reasonable default is impossible to know without context of the application. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-csp[Content Security Policy] by default, because a reasonable default is impossible to know without context of the application. The web application author must declare the security policy(s) to enforce and/or monitor for the protected resources. For example, given the following security policy: @@ -693,7 +693,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-referrer]] == Referrer Policy -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-referrer[Referrer Policy] headers by default. You can enable the Referrer Policy header using the configuration as shown below: .Referrer Policy @@ -753,7 +753,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-feature]] == Feature Policy -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-feature[Feature Policy] headers by default. The following `Feature-Policy` header: .Feature-Policy Example @@ -819,7 +819,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-permissions]] == Permissions Policy -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-permissions[Permissions Policy] headers by default. The following `Permissions-Policy` header: .Permissions-Policy Example @@ -889,7 +889,7 @@ class SecurityConfig : WebSecurityConfigurerAdapter() { [[servlet-headers-clear-site-data]] == Clear Site Data -Spring Security does not add <> headers by default. +Spring Security does not add xref:overview/features/exploits/headers.adoc#headers-clear-site-data[Clear-Site-Data] headers by default. The following Clear-Site-Data header: .Clear-Site-Data Example diff --git a/docs/modules/ROOT/pages/servlet/exploits/http.adoc b/docs/modules/ROOT/pages/servlet/exploits/http.adoc index f9d8c3275b..56e1cd16ab 100644 --- a/docs/modules/ROOT/pages/servlet/exploits/http.adoc +++ b/docs/modules/ROOT/pages/servlet/exploits/http.adoc @@ -1,7 +1,7 @@ [[servlet-http]] = HTTP -All HTTP based communication should be protected <>. +All HTTP based communication should be protected xref:overview/features/exploits/http.adoc#http[using TLS]. Below you can find details around Servlet specific features that assist with HTTPS usage. @@ -69,9 +69,9 @@ The following XML configuration will redirect all HTTP requests to HTTPS [[servlet-hsts]] == Strict Transport Security -Spring Security provides support for <> and enables it by default. +Spring Security provides support for xref:servlet/exploits/headers.adoc#servlet-headers-hsts[Strict Transport Security] and enables it by default. [[servlet-http-proxy-server]] == Proxy Server Configuration -Spring Security <>. +Spring Security xref:overview/features/exploits/http.adoc#http-proxy-server[integrates with proxy servers]. diff --git a/docs/modules/ROOT/pages/servlet/exploits/index.adoc b/docs/modules/ROOT/pages/servlet/exploits/index.adoc index b19171f9a6..e08b8eb72e 100644 --- a/docs/modules/ROOT/pages/servlet/exploits/index.adoc +++ b/docs/modules/ROOT/pages/servlet/exploits/index.adoc @@ -1,7 +1,7 @@ [[servlet-exploits]] = Protection Against Exploits -This section discusses Servlet specific support for <>. +This section discusses Servlet specific support for xref:overview/features/exploits/index.adoc#exploits[Spring Security's protection against common exploits]. * xref:servlet/exploits/csrf.adoc[] * xref:servlet/exploits/headers.adoc[] diff --git a/docs/modules/ROOT/pages/servlet/hello/index.adoc b/docs/modules/ROOT/pages/servlet/hello/index.adoc index 21d8497ad7..756fee3381 100644 --- a/docs/modules/ROOT/pages/servlet/hello/index.adoc +++ b/docs/modules/ROOT/pages/servlet/hello/index.adoc @@ -12,7 +12,7 @@ For your convenience, you can download a minimal Spring Boot + Spring Security a [[servlet-hello-dependencies]] == Updating Dependencies -The only step you need to do is update the dependencies by using <> or <>. +The only step you need to do is update the dependencies by using xref:overview/getting-spring-security.adoc#getting-maven-boot[Maven] or xref:overview/getting-spring-security.adoc#getting-gradle-boot[Gradle]. [[servlet-hello-starting]] == Starting Hello Spring Security Boot diff --git a/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc b/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc index 202b51ab09..ecda96b1f0 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc @@ -5,7 +5,7 @@ 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. Spring Security provides some infrastructure to help make this much easier for users. 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 <> and <>. +In fact, this is what Spring Security builds on to integration with xref:servlet/integrations/servlet-api.adoc#servletapi-start-runnable[] and xref:servlet/integrations/mvc.adoc#mvc-async[]. == DelegatingSecurityContextRunnable @@ -44,7 +44,7 @@ fun run() { While very simple, it makes it seamless to transfer the SecurityContext from one Thread to another. This is important since, in most cases, the SecurityContextHolder acts on a per Thread basis. -For example, you might have used Spring Security's <> support to secure one of your services. +For example, you might have used Spring Security's xref:servlet/appendix/namespace.adoc#nsa-global-method-security[] support to secure one of your services. You can now easily transfer the `SecurityContext` of the current `Thread` to the `Thread` that invokes the secured service. An example of how you might do this can be found below: diff --git a/docs/modules/ROOT/pages/servlet/integrations/data.adoc b/docs/modules/ROOT/pages/servlet/integrations/data.adoc index 9212daeda3..c37f96d302 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/data.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/data.adoc @@ -67,4 +67,4 @@ interface MessageRepository : PagingAndSortingRepository { This checks to see if the `Authentication.getPrincipal().getId()` is equal to the recipient of the `Message`. Note that this example assumes you have customized the principal to be an Object that has an id property. -By exposing the `SecurityEvaluationContextExtension` bean, all of the <> are available within the Query. +By exposing the `SecurityEvaluationContextExtension` bean, all of the xref:servlet/authorization/expression-based.adoc#common-expressions[Common Security Expressions] are available within the Query. diff --git a/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc b/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc index 1f26756b08..e1c407763b 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc @@ -42,6 +42,6 @@ The following Spring Security modules provide Jackson support: - spring-security-core (`CoreJackson2Module`) - spring-security-web (`WebJackson2Module`, `WebServletJackson2Module`, `WebServerJackson2Module`) -- <> (`OAuth2ClientJackson2Module`) +- xref:servlet/oauth2/oauth2-client.adoc#oauth2client[ spring-security-oauth2-client] (`OAuth2ClientJackson2Module`) - spring-security-cas (`CasJackson2Module`) ==== diff --git a/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc b/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc index 28a02e34ac..05bd1ea02c 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/jsp-taglibs.adoc @@ -17,7 +17,7 @@ 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. ]. -The first approach uses a <>, specified in the `access` attribute of the tag. +The first approach uses a xref:servlet/authorization/expression-based.adoc#el-access-web[web-security expression], specified in the `access` attribute of the tag. The expression evaluation will be delegated to the `SecurityExpressionHandler` defined in the application context (you should have web expressions enabled in your `` namespace configuration to make sure this service is available). So, for example, you might have diff --git a/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc index ef2d849355..d6b126a0a7 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc @@ -492,14 +492,14 @@ The `SecurityContext` that is used to process the `Callable` is the `SecurityCon There is no automatic integration with a `DeferredResult` that is returned by controllers. This is because `DeferredResult` is processed by the users and thus there is no way of automatically integrating with it. -However, you can still use <> to provide transparent integration with Spring Security. +However, you can still use xref:servlet/integrations/concurrency.adoc#concurrency[Concurrency Support] to provide transparent integration with Spring Security. [[mvc-csrf]] == Spring MVC and CSRF Integration === Automatic Token Inclusion -Spring Security will automatically <> 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]. +Spring Security will automatically xref:servlet/exploits/csrf.adoc#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: [source,xml] @@ -544,7 +544,7 @@ Will output HTML that is similar to the following: === Resolving the CsrfToken Spring Security provides `CsrfTokenArgumentResolver` which can automatically resolve the current `CsrfToken` for Spring MVC arguments. -By using <> you will automatically have this added to your Spring MVC configuration. +By using xref:servlet/java-configuration/index.adoc#jc-hello-wsca[@EnableWebSecurity] you will automatically have this added to your Spring MVC configuration. If you use XML based configuration, you must add this yourself. Once `CsrfTokenArgumentResolver` is properly configured, you can expose the `CsrfToken` to your static HTML based application. diff --git a/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc b/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc index 6bc74d8af5..741a0629f7 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/servlet-api.adoc @@ -270,4 +270,4 @@ The following section describes the Servlet 3.1 methods that Spring Security int [[servletapi-change-session-id]] === 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 <> attacks in Servlet 3.1 and higher. +The https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServletRequest.html#changeSessionId()[HttpServletRequest.changeSessionId()] is the default method for protecting against xref:servlet/authentication/session-management.adoc#ns-session-fixation[Session Fixation] attacks in Servlet 3.1 and higher. diff --git a/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc b/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc index 2ef0312334..75a94b9ba4 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/websocket.adoc @@ -51,7 +51,7 @@ This will ensure that: <2> The SecurityContextHolder is populated with the user within the simpUser header attribute for any inbound request. <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 <> -Spring Security also provides <> support for securing WebSockets. +Spring Security also provides xref:servlet/appendix/namespace.adoc#nsa-websocket-security[XML Namespace] support for securing WebSockets. A comparable XML based configuration looks like the following: [source,xml] @@ -132,7 +132,7 @@ This will ensure that: <5> Any other message of type MESSAGE or SUBSCRIBE is rejected. Due to 6 we do not need this step, but it illustrates how one can match on specific message types. <6> Any other Message is rejected. This is a good idea to ensure that you do not miss any messages. -Spring Security also provides <> support for securing WebSockets. +Spring Security also provides xref:servlet/appendix/namespace.adoc#nsa-websocket-security[XML Namespace] support for securing WebSockets. A comparable XML based configuration looks like the following: [source,xml] @@ -246,7 +246,7 @@ Spring Security adds an additional layer of protection to provide https://en.wik [[websocket-sameorigin-csrf]] === Adding CSRF to Stomp Headers -By default Spring Security requires the <> in any CONNECT message type. +By default Spring Security requires the xref:overview/features/exploits/csrf.adoc#csrf[CSRF token] in any CONNECT message type. This ensures that only a site that has access to the CSRF token can connect. Since only the *Same Origin* can access the CSRF token, external domains are not allowed to make a connection. @@ -254,7 +254,7 @@ Typically we need to include the CSRF token in an HTTP header or an HTTP paramet However, SockJS does not allow for these options. Instead, we must include the token in the Stomp headers -Applications can <> by accessing the request attribute named _csrf. +Applications can xref:servlet/exploits/csrf.adoc#servlet-csrf-include[obtain a CSRF token] by accessing the request attribute named _csrf. For example, the following will allow accessing the `CsrfToken` in a JSP: [source,javascript] @@ -357,10 +357,10 @@ When using the fallback options we need to relax a few security constraints to a === 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 <> the site from being framed to prevent Clickjacking attacks. +By default Spring Security will xref:overview/features/exploits/headers.adoc#headers-frame-options[deny] the site from being framed to prevent Clickjacking attacks. To allow SockJS frame based transports to work, we need to configure Spring Security to allow the same origin to frame the content. -You can customize X-Frame-Options with the <> element. +You can customize X-Frame-Options with the xref:servlet/appendix/namespace.adoc#nsa-frame-options[frame-options] element. For example, the following will instruct Spring Security to use "X-Frame-Options: SAMEORIGIN" which allows iframes within the same domain: [source,xml] @@ -486,7 +486,7 @@ open class WebSecurityConfig : WebSecurityConfigurerAdapter() { ---- ==== -If we are using XML based configuration, we can use the <>. +If we are using XML based configuration, we can use the xref:servlet/appendix/namespace.adoc#nsa-csrf-request-matcher-ref[csrf@request-matcher-ref]. For example: [source,xml] diff --git a/docs/modules/ROOT/pages/servlet/java-configuration/index.adoc b/docs/modules/ROOT/pages/servlet/java-configuration/index.adoc index e54df9bd7f..54cf54aa74 100644 --- a/docs/modules/ROOT/pages/servlet/java-configuration/index.adoc +++ b/docs/modules/ROOT/pages/servlet/java-configuration/index.adoc @@ -5,7 +5,7 @@ General support for https://docs.spring.io/spring/docs/3.1.x/spring-framework-reference/html/beans.html#beans-java[Java Configuration] was added to Spring Framework in Spring 3.1. Since Spring Security 3.2 there has been Spring Security Java Configuration support which enables users to easily configure Spring Security without the use of any XML. -If you are familiar with the <> then you should find quite a few similarities between it and the Security Java Configuration support. +If you are familiar with the xref:servlet/namespace/index.adoc#ns-config[] then you should find quite a few similarities between it and the Security Java Configuration support. NOTE: Spring Security provides https://github.com/spring-projects/spring-security-samples/tree/main/servlet/java-configuration[lots of sample applications] which demonstrate the use of Spring Security Java Configuration. diff --git a/docs/modules/ROOT/pages/servlet/namespace/index.adoc b/docs/modules/ROOT/pages/servlet/namespace/index.adoc index f0d98efc6c..488c3743c7 100644 --- a/docs/modules/ROOT/pages/servlet/namespace/index.adoc +++ b/docs/modules/ROOT/pages/servlet/namespace/index.adoc @@ -18,7 +18,7 @@ For example, adding the following element from the security namespace to an appl This is much simpler than wiring up the equivalent Apache Directory Server beans. The most common alternative configuration requirements are supported by attributes on the `ldap-server` element and the user is isolated from worrying about which beans they need to create and what the bean property names are. -footnote:[You can find out more about the use of the `ldap-server` element in the chapter on pass:specialcharacters,macros[<>].]. +footnote:[You can find out more about the use of the `ldap-server` element in the chapter on pass:specialcharacters,macros[xref:servlet/authentication/unpwd/ldap.adoc#servlet-authentication-ldap[]].]. Use of a good XML editor while editing the application context file should provide information on the attributes and elements that are available. We would recommend that you try out the https://spring.io/tools[Eclipse IDE with Spring Tools] as it has special features for working with standard Spring namespaces. @@ -126,7 +126,7 @@ All you need to enable web security to begin with is Which says that we want all URLs within our application to be secured, requiring the role `ROLE_USER` to access them, we want to log in to the application using a form with username and password, and that we want a logout URL registered which will allow us to log out of the application. `` element is the parent for all web-related namespace functionality. -The `` element defines a `pattern` which is matched against the URLs of incoming requests using an ant path style syntax footnote:[See the section on pass:specialcharacters,macros[<>] for more details on how matches are actually performed.]. +The `` element defines a `pattern` which is matched against the URLs of incoming requests using an ant path style syntax footnote:[See the section on pass:specialcharacters,macros[xref:servlet/exploits/firewall.adoc#servlet-httpfirewall[`HttpFirewall`]] for more details on how matches are actually performed.]. You can also use regular-expression matching as an alternative (see the namespace appendix for more details). The `access` attribute defines the access requirements for requests matching the given pattern. With the default configuration, this is typically a comma-separated list of roles, one of which a user must have to be allowed to make the request. @@ -134,7 +134,7 @@ The prefix "ROLE_" is a marker which indicates that a simple comparison with the In other words, a normal role-based check should be used. Access-control in Spring Security is not limited to the use of simple roles (hence the use of the prefix to differentiate between different types of security attributes). We'll see later how the interpretation can vary footnote:[The interpretation of the comma-separated values in the `access` attribute depends on the implementation of the <> which is used.]. -In Spring Security 3.0, the attribute can also be populated with an <>. +In Spring Security 3.0, the attribute can also be populated with an xref:servlet/authorization/expression-based.adoc#el-access[EL expression]. [NOTE] @@ -192,13 +192,13 @@ Common problems like incorrect filter ordering are no longer an issue as the fil The `` element creates a `DaoAuthenticationProvider` bean and the `` element creates an `InMemoryDaoImpl`. All `authentication-provider` elements must be children of the `` element, which creates a `ProviderManager` and registers the authentication providers with it. -You can find more detailed information on the beans that are created in the <>. +You can find more detailed information on the beans that are created in the xref:servlet/appendix/namespace.adoc#appendix-namespace[namespace appendix]. It's worth cross-checking this if you want to start understanding what the important classes in the framework are and how they are used, particularly if you want to customise things later. **** The configuration above defines two users, their passwords and their roles within the application (which will be used for access control). It is also possible to load user information from a standard properties file using the `properties` attribute on `user-service`. -See the section on <> for more details on the file format. +See the section on xref:servlet/authentication/unpwd/in-memory.adoc#servlet-authentication-inmemory[in-memory authentication] for more details on the file format. Using the `` element means that the user information will be used by the authentication manager to process authentication requests. You can have multiple `` elements to define different authentication sources and each will be consulted in turn. @@ -353,7 +353,7 @@ Remove any elements which create filters whose functionality you want to replace Note that you can't replace filters which are created by the use of the `` element itself - `SecurityContextPersistenceFilter`, `ExceptionTranslationFilter` or `FilterSecurityInterceptor`. Some other filters are added by default, but you can disable them. -An `AnonymousAuthenticationFilter` is added by default and unless you have <> disabled, a `SessionManagementFilter` will also be added to the filter chain. +An `AnonymousAuthenticationFilter` is added by default and unless you have xref:servlet/authentication/session-management.adoc#ns-session-fixation[session-fixation protection] disabled, a `SessionManagementFilter` will also be added to the filter chain. ==== @@ -365,7 +365,7 @@ If you're replacing a namespace filter which requires an authentication entry po == Method Security From version 2.0 onwards Spring Security has improved support substantially for adding security to your service layer methods. It provides support for JSR-250 annotation security as well as the framework's original `@Secured` annotation. -From 3.0 you can also make use of new <>. +From 3.0 you can also make use of new xref:servlet/authorization/expression-based.adoc#el-access[expression-based annotations]. You can apply security to a single bean, using the `intercept-methods` element to decorate the bean declaration, or you can secure multiple beans across the entire service layer using the AspectJ style pointcuts. [[ns-access-manager]] @@ -376,7 +376,7 @@ If you don't you can skip it and come back to it later, as this section is only When you use a namespace configuration, a default instance of `AccessDecisionManager` is automatically registered for you and will be used for making access decisions for method invocations and web URL access, based on the access attributes you specify in your `intercept-url` and `protect-pointcut` declarations (and in annotations if you are using annotation secured methods). The default strategy is to use an `AffirmativeBased` `AccessDecisionManager` with a `RoleVoter` and an `AuthenticatedVoter`. -You can find out more about these in the chapter on <>. +You can find out more about these in the chapter on xref:servlet/authorization/architecture.adoc#authz-arch[authorization]. [[ns-custom-access-mgr]] diff --git a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc index 31ac01c9f9..affccf9e55 100644 --- a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc +++ b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-client.adoc @@ -74,7 +74,7 @@ class OAuth2ClientSecurityConfig : WebSecurityConfigurerAdapter() { In addition to the `HttpSecurity.oauth2Client()` DSL, XML configuration is also supported. -The following code shows the complete configuration options available in the <>: +The following code shows the complete configuration options available in the xref:servlet/appendix/namespace.adoc#nsa-oauth2-client[ security namespace]: .OAuth2 Client XML Configuration Options ==== @@ -392,7 +392,7 @@ The default implementation of `OAuth2AuthorizedClientService` is `InMemoryOAuth2 Alternatively, the JDBC implementation `JdbcOAuth2AuthorizedClientService` may be configured for persisting `OAuth2AuthorizedClient`(s) in a database. [NOTE] -`JdbcOAuth2AuthorizedClientService` depends on the table definition described in <>. +`JdbcOAuth2AuthorizedClientService` depends on the table definition described in xref:servlet/appendix/database-schema.adoc#dbschema-oauth2-client[ OAuth 2.0 Client Schema]. [[oauth2Client-authorized-manager-provider]] @@ -702,7 +702,7 @@ spring: [NOTE] `+{baseUrl}+` resolves to `+{baseScheme}://{baseHost}{basePort}{basePath}+` -Configuring the `redirect-uri` with `URI` template variables is especially useful when the OAuth 2.0 Client is running behind a <>. +Configuring the `redirect-uri` with `URI` template variables is especially useful when the OAuth 2.0 Client is running behind a xref:overview/features/exploits/http.adoc#http-proxy-server[Proxy Server]. This ensures that the `X-Forwarded-*` headers are used when expanding the `redirect-uri`. ==== Customizing the Authorization Request diff --git a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc index db121281b0..b1f7b736a3 100644 --- a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc +++ b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-login.adoc @@ -40,10 +40,10 @@ The redirect URI is the path in the application that the end-user's user-agent i In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:8080/login/oauth2/code/google`. TIP: The default redirect URI template is `+{baseUrl}/login/oauth2/code/{registrationId}+`. -The *_registrationId_* is a unique identifier for the <>. +The *_registrationId_* is a unique identifier for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration]. -IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check <> to ensure the application is correctly configured. -Also, see the supported <> for `redirect-uri`. +IMPORTANT: If the OAuth Client is running behind a proxy server, it is recommended to check xref:overview/features/exploits/http.adoc#http-proxy-server[Proxy Server Configuration] to ensure the application is correctly configured. +Also, see the supported xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-auth-code-redirect-uri[ `URI` template variables] for `redirect-uri`. [[oauth2login-sample-application-config]] @@ -69,7 +69,7 @@ spring: .OAuth Client properties ==== <1> `spring.security.oauth2.client.registration` is the base property prefix for OAuth Client properties. -<2> Following the base property prefix is the ID for the <>, such as google. +<2> Following the base property prefix is the ID for the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration], such as google. ==== . Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier. @@ -93,7 +93,7 @@ At this point, the OAuth Client retrieves your email address and basic profile i [[oauth2login-boot-property-mappings]] == Spring Boot 2.x Property Mappings -The following table outlines the mapping of the Spring Boot 2.x OAuth Client properties to the <> properties. +The following table outlines the mapping of the Spring Boot 2.x OAuth Client properties to the xref:servlet/oauth2/oauth2-client.adoc#oauth2Client-client-registration[ClientRegistration] properties. |=== |Spring Boot 2.x |ClientRegistration @@ -737,7 +737,7 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() { In addition to the `oauth2Login()` DSL, XML configuration is also supported. -The following code shows the complete configuration options available in the <>: +The following code shows the complete configuration options available in the xref:servlet/appendix/namespace.adoc#nsa-oauth2-login[ security namespace]: .OAuth2 Login XML Configuration Options ==== diff --git a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc index b4565b3300..c9e00338ec 100644 --- a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc +++ b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc @@ -18,19 +18,19 @@ Working samples for both {gh-samples-url}/servlet/spring-boot/java/oauth2/resour ==== Let's take a look at how Bearer Token Authentication works within Spring Security. -First, we see that, like <>, the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authenticate] header is sent back to an unauthenticated client. +First, we see that, like xref:servlet/authentication/unpwd/basic.adoc#servlet-authentication-basic[Basic Authentication], the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authenticate] header is sent back to an unauthenticated client. .Sending WWW-Authenticate Header image::{figures}/bearerauthenticationentrypoint.png[] -The figure above builds off our <> diagram. +The figure above builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram. image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized. -image:{icondir}/number_2.png[] Spring Security's <> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. +image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. -image:{icondir}/number_3.png[] Since the user is not authenticated, <> initiates __Start Authentication__. -The configured <> is an instance of {security-api-url}org/springframework/security/oauth2/server/resource/web/BearerTokenAuthenticationEntryPoint.html[`BearerTokenAuthenticationEntryPoint`] which sends a WWW-Authenticate header. +image:{icondir}/number_3.png[] Since the user is not authenticated, xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__. +The configured xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is an instance of {security-api-url}org/springframework/security/oauth2/server/resource/web/BearerTokenAuthenticationEntryPoint.html[`BearerTokenAuthenticationEntryPoint`] which sends a WWW-Authenticate header. The `RequestCache` is typically a `NullRequestCache` that does not save the request since the client is capable of replaying the requests it originally requested. When a client receives the `WWW-Authenticate: Bearer` header, it knows it should retry with a bearer token. @@ -40,21 +40,21 @@ Below is the flow for the bearer token being processed. .Authenticating Bearer Token image::{figures}/bearertokenauthenticationfilter.png[] -The figure builds off our <> diagram. +The figure builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram. -image:{icondir}/number_1.png[] When the user submits their bearer token, the `BearerTokenAuthenticationFilter` creates a `BearerTokenAuthenticationToken` which is a type of <> by extracting the token from the `HttpServletRequest`. +image:{icondir}/number_1.png[] When the user submits their bearer token, the `BearerTokenAuthenticationFilter` creates a `BearerTokenAuthenticationToken` which is a type of xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] by extracting the token from the `HttpServletRequest`. image:{icondir}/number_2.png[] Next, the `HttpServletRequest` is passed to the `AuthenticationManagerResolver`, which selects the `AuthenticationManager`. The `BearerTokenAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated. The details of what `AuthenticationManager` looks like depends on whether you're configured for <> or <>. image:{icondir}/number_3.png[] If authentication fails, then __Failure__ -* The <> is cleared out. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[] is cleared out. * The `AuthenticationEntryPoint` is invoked to trigger the WWW-Authenticate header to be sent again. image:{icondir}/number_4.png[] If authentication is successful, then __Success__. -* The <> is set on the <>. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[]. * The `BearerTokenAuthenticationFilter` invokes `FilterChain.doFilter(request,response)` to continue with the rest of the application logic. [[oauth2resourceserver-jwt-minimaldependencies]] @@ -142,17 +142,17 @@ From here, consider jumping to: Next, let's see the architectural components that Spring Security uses to support https://tools.ietf.org/html/rfc7519[JWT] Authentication in servlet-based applications, like the one we just saw. -{security-api-url}org/springframework/security/oauth2/server/resource/authentication/JwtAuthenticationProvider.html[`JwtAuthenticationProvider`] is an <> implementation that leverages a <> and <> to authenticate a JWT. +{security-api-url}org/springframework/security/oauth2/server/resource/authentication/JwtAuthenticationProvider.html[`JwtAuthenticationProvider`] is an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a <> and <> to authenticate a JWT. Let's take a look at how `JwtAuthenticationProvider` works within Spring Security. -The figure explains details of how the <> in figures from <> works. +The figure explains details of how the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from <> works. .`JwtAuthenticationProvider` Usage image::{figures}/jwtauthenticationprovider.png[] -image:{icondir}/number_1.png[] The authentication `Filter` from <> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by <>. +image:{icondir}/number_1.png[] The authentication `Filter` from <> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`ProviderManager`]. -image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an <> of type `JwtAuthenticationProvider`. +image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationprovider[] of type `JwtAuthenticationProvider`. [[oauth2resourceserver-jwt-architecture-jwtdecoder]] image:{icondir}/number_3.png[] `JwtAuthenticationProvider` decodes, verifies, and validates the `Jwt` using a <>. @@ -160,8 +160,8 @@ image:{icondir}/number_3.png[] `JwtAuthenticationProvider` decodes, verifies, an [[oauth2resourceserver-jwt-architecture-jwtauthenticationconverter]] image:{icondir}/number_4.png[] `JwtAuthenticationProvider` then uses the <> to convert the `Jwt` into a `Collection` of granted authorities. -image:{icondir}/number_5.png[] When authentication is successful, the <> that is returned is of type `JwtAuthenticationToken` and has a principal that is the `Jwt` returned by the configured `JwtDecoder`. -Ultimately, the returned `JwtAuthenticationToken` will be set on the <> by the authentication `Filter`. +image:{icondir}/number_5.png[] When authentication is successful, the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] that is returned is of type `JwtAuthenticationToken` and has a principal that is the `Jwt` returned by the configured `JwtDecoder`. +Ultimately, the returned `JwtAuthenticationToken` will be set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`. [[oauth2resourceserver-jwt-jwkseturi]] == Specifying the Authorization Server JWK Set Uri Directly @@ -1513,22 +1513,22 @@ From here, you may want to jump to: Next, let's see the architectural components that Spring Security uses to support https://tools.ietf.org/html/rfc7662[opaque token] Authentication in servlet-based applications, like the one we just saw. -{security-api-url}org/springframework/security/oauth2/server/resource/authentication/OpaqueTokenAuthenticationProvider.html[`OpaqueTokenAuthenticationProvider`] is an <> implementation that leverages a <> to authenticate an opaque token. +{security-api-url}org/springframework/security/oauth2/server/resource/authentication/OpaqueTokenAuthenticationProvider.html[`OpaqueTokenAuthenticationProvider`] is an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationprovider[`AuthenticationProvider`] implementation that leverages a <> to authenticate an opaque token. Let's take a look at how `OpaqueTokenAuthenticationProvider` works within Spring Security. -The figure explains details of how the <> in figures from <> works. +The figure explains details of how the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationmanager[`AuthenticationManager`] in figures from <> works. .`OpaqueTokenAuthenticationProvider` Usage image::{figures}/opaquetokenauthenticationprovider.png[] -image:{icondir}/number_1.png[] The authentication `Filter` from <> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by <>. +image:{icondir}/number_1.png[] The authentication `Filter` from <> passes a `BearerTokenAuthenticationToken` to the `AuthenticationManager` which is implemented by xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`ProviderManager`]. -image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an <> of type `OpaqueTokenAuthenticationProvider`. +image:{icondir}/number_2.png[] The `ProviderManager` is configured to use an xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationprovider[] of type `OpaqueTokenAuthenticationProvider`. [[oauth2resourceserver-opaque-architecture-introspector]] image:{icondir}/number_3.png[] `OpaqueTokenAuthenticationProvider` introspects the opaque token and adds granted authorities using an <>. -When authentication is successful, the <> that is returned is of type `BearerTokenAuthentication` and has a principal that is the `OAuth2AuthenticatedPrincipal` returned by the configured <>. -Ultimately, the returned `BearerTokenAuthentication` will be set on the <> by the authentication `Filter`. +When authentication is successful, the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[`Authentication`] that is returned is of type `BearerTokenAuthentication` and has a principal that is the `OAuth2AuthenticatedPrincipal` returned by the configured <>. +Ultimately, the returned `BearerTokenAuthentication` will be set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] by the authentication `Filter`. [[oauth2resourceserver-opaque-attributes]] == Looking Up Attributes Post-Authentication @@ -3007,7 +3007,7 @@ fun rest(): RestTemplate { [NOTE] Unlike the {security-api-url}org/springframework/security/oauth2/client/OAuth2AuthorizedClientManager.html[OAuth 2.0 Authorized Client Manager], this filter interceptor makes no attempt to renew the token, should it be expired. -To obtain this level of support, please create an interceptor using the <>. +To obtain this level of support, please create an interceptor using the xref:servlet/oauth2/oauth2-client.adoc#oauth2client[OAuth 2.0 Authorized Client Manager]. [[oauth2resourceserver-bearertoken-failure]] == Bearer Token Failure @@ -3023,7 +3023,7 @@ HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error_code="invalid_token", error_description="Unsupported algorithm of none", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1" ---- -Additionally, it is published as an `AuthenticationFailureBadCredentialsEvent`, which you can <> like so: +Additionally, it is published as an `AuthenticationFailureBadCredentialsEvent`, which you can xref:servlet/authentication/events.adoc#servlet-events[listen for in your application] like so: ==== .Java diff --git a/docs/modules/ROOT/pages/servlet/saml2/index.adoc b/docs/modules/ROOT/pages/servlet/saml2/index.adoc index ec19543759..50cf0a5182 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/index.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/index.adoc @@ -24,20 +24,20 @@ A working sample for {gh-samples-url}/servlet/spring-boot/java/saml2-login[SAML ==== Let's take a look at how SAML 2.0 Relying Party Authentication works within Spring Security. -First, we see that, like <>, Spring Security takes the user to a third-party for performing authentication. +First, we see that, like xref:servlet/oauth2/oauth2-login.adoc#oauth2login[ OAuth 2.0 Login], Spring Security takes the user to a third-party for performing authentication. It does this through a series of redirects. .Redirecting to Asserting Party Authentication image::{figures}/saml2webssoauthenticationrequestfilter.png[] -The figure above builds off our <> and <> diagrams: +The figure above builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] and xref:servlet/authentication/architecture/index.adoc#servlet-authentication-abstractprocessingfilter[ `AbstractAuthenticationProcessingFilter`] diagrams: image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized. -image:{icondir}/number_2.png[] Spring Security's <> indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. +image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-requests.adoc#servlet-authorization-filtersecurityinterceptor[`FilterSecurityInterceptor`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`. -image:{icondir}/number_3.png[] Since the user lacks authorization, the <> initiates __Start Authentication__. -The configured <> is an instance of {security-api-url}org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html[`LoginUrlAuthenticationEntryPoint`] which redirects to <` generating endpoint>>, `Saml2WebSsoAuthenticationRequestFilter`. +image:{icondir}/number_3.png[] Since the user lacks authorization, the xref:servlet/architecture/index.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__. +The configured xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is an instance of {security-api-url}org/springframework/security/web/authentication/LoginUrlAuthenticationEntryPoint.html[`LoginUrlAuthenticationEntryPoint`] which redirects to <` generating endpoint>>, `Saml2WebSsoAuthenticationRequestFilter`. Or, if you've <>, it will first redirect to a picker page. image:{icondir}/number_4.png[] Next, the `Saml2WebSsoAuthenticationRequestFilter` creates, signs, serializes, and encodes a `` using its configured <>. @@ -52,23 +52,23 @@ image:{icondir}/number_6.png[] The browser then POSTs the `` to .Authenticating a `` image::{figures}/saml2webssoauthenticationfilter.png[] -The figure builds off our <> diagram. +The figure builds off our xref:servlet/architecture/index.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram. image:{icondir}/number_1.png[] When the browser submits a `` to the application, it <>. This filter calls its configured `AuthenticationConverter` to create a `Saml2AuthenticationToken` by extracting the response from the `HttpServletRequest`. This converter additionally resolves the <> and supplies it to `Saml2AuthenticationToken`. -image:{icondir}/number_2.png[] Next, the filter passes the token to its configured <>. +image:{icondir}/number_2.png[] Next, the filter passes the token to its configured xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`AuthenticationManager`]. By default, it will use the <>. image:{icondir}/number_3.png[] If authentication fails, then __Failure__ -* The <> is cleared out. -* The <> is invoked to restart the authentication process. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[ `SecurityContextHolder`] is cleared out. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is invoked to restart the authentication process. image:{icondir}/number_4.png[] If authentication is successful, then __Success__. -* The <> is set on the <>. +* The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-authentication[ `Authentication`] is set on the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-securitycontextholder[ `SecurityContextHolder`]. * The `Saml2WebSsoAuthenticationFilter` invokes `FilterChain#doFilter(request,response)` to continue with the rest of the application logic. [[servlet-saml2login-minimaldependencies]] @@ -169,9 +169,9 @@ image:{figures}/opensamlauthenticationprovider.png[] This figure builds off of the <>. -image:{icondir}/number_1.png[] The `Saml2WebSsoAuthenticationFilter` formulates the `Saml2AuthenticationToken` and invokes the <>. +image:{icondir}/number_1.png[] The `Saml2WebSsoAuthenticationFilter` formulates the `Saml2AuthenticationToken` and invokes the xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`AuthenticationManager`]. -image:{icondir}/number_2.png[] The <> invokes the OpenSAML authentication provider. +image:{icondir}/number_2.png[] The xref:servlet/authentication/architecture/index.adoc#servlet-authentication-providermanager[`AuthenticationManager`] invokes the OpenSAML authentication provider. image:{icondir}/number_3.png[] The authentication provider deserializes the response into an OpenSAML `Response` and checks its signature. If the signature is invalid, authentication fails. @@ -1267,7 +1267,7 @@ open class SecurityConfig : WebSecurityConfigurerAdapter() { ---- ==== <1> First, call the default converter, which extracts attributes and authorities from the response -<2> Second, call the <> using the relevant information +<2> Second, call the xref:servlet/authentication/unpwd/user-details-service.adoc#servlet-authentication-userdetailsservice[ `UserDetailsService`] using the relevant information <3> Third, return a custom authentication that includes the user details [NOTE] diff --git a/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc b/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc index 5a58d3118d..dd712ec6cf 100644 --- a/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc +++ b/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc @@ -480,7 +480,7 @@ fun foo(user: Principal): String { ---- ==== -There's nothing OAuth2-specific about it, so you will likely be able to simply <> and be fine. +There's nothing OAuth2-specific about it, so you will likely be able to simply xref:servlet/test/method.adoc#test-method-withmockuser[use `@WithMockUser`] and be fine. But, in cases where your controllers are bound to some aspect of Spring Security's OAuth 2.0 support, like the following: @@ -583,7 +583,7 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read" ---- ==== -Spring Security does the necessary work to make sure that the `OidcUser` instance is available for <>. +Spring Security does the necessary work to make sure that the `OidcUser` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation]. Further, it also links that `OidcUser` to a simple instance of `OAuth2AuthorizedClient` that it deposits into an mock `OAuth2AuthorizedClientRepository`. This can be handy if your tests <>.. @@ -806,7 +806,7 @@ assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read" ---- ==== -Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for <>. +Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for xref:servlet/integrations/mvc.adoc#mvc-authentication-principal[the `@AuthenticationPrincipal` annotation]. Further, it also links that `OAuth2User` to a simple instance of `OAuth2AuthorizedClient` that it deposits in a mock `OAuth2AuthorizedClientRepository`. This can be handy if your tests <>.