Skip to content

Commit

Permalink
Fix Broken Links in Docs
Browse files Browse the repository at this point in the history
Closes gh-9869
  • Loading branch information
marcusdacoregio committed Jun 21, 2021
1 parent 4060f83 commit 95a1ccb
Show file tree
Hide file tree
Showing 19 changed files with 34 additions and 24 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ download-url: the URL to download the Spring Security distribution

== Setting up the sample

This section outlines how to setup a workspace within https://spring.io/tools/sts[Spring Tool Suite (STS)] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide in order to reduce the complexity.
This section outlines how to setup a workspace within https://spring.io/tools[Eclipse IDE with Spring Tools] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide in order to reduce the complexity.

=== Obtaining the sample project

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ download-url: the URL to download the Spring Security distribution

== Setting up the sample

This section outlines how to setup a workspace within https://spring.io/tools/sts[Spring Tool Suite (STS)] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide in order to reduce the complexity.
This section outlines how to setup a workspace within https://spring.io/tools[Eclipse IDE with Spring Tools] so that you can follow along with this guide. The next section outlines generic steps for how to apply Spring Security to your existing application. While you could simply apply the steps to your existing application, we encourage you to follow along with this guide in order to reduce the complexity.

=== Obtaining the sample project

Expand Down
13 changes: 12 additions & 1 deletion docs/manual/spring-security-docs-manual.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,27 @@ asciidoctor {
}

asciidoctorj {
def docsTag = snapshotBuild ? 'current' : project.version
def ghTag = snapshotBuild ? 'main' : project.version
def ghUrl = "https://github.com/spring-projects/spring-security/tree/$ghTag"
def ghOldSamplesUrl = "https://github.com/spring-projects/spring-security/tree/5.4.x/samples"
def ghSamplesUrl = "https://github.com/spring-projects/spring-security-samples/tree/$ghTag"
def securityDocsUrl = "https://docs.spring.io/spring-security/site/docs/$docsTag"
def oldSecurityApiUrl = "https://docs.spring.io/spring-security/site/docs/5.4.x/api/"
def springVersion = "5.3.x"
def securityApiUrl = "$securityDocsUrl/api/"
def securityReferenceUrl = "$securityDocsUrl/reference/html5/"
def springFrameworkApiUrl = "https://docs.spring.io/spring-framework/docs/$springVersion/javadoc-api/"
attributes 'spring-security-version' : project.version,
'spring-boot-version' : springBootVersion,
revnumber : project.version,
'gh-url': ghUrl,
'gh-samples-url': ghSamplesUrl,
'gh-old-samples-url': ghOldSamplesUrl
'gh-old-samples-url': ghOldSamplesUrl,
'old-security-api-url': oldSecurityApiUrl,
'security-api-url': securityApiUrl,
'security-reference-url': securityReferenceUrl,
'spring-framework-api-url': springFrameworkApiUrl
attributeProvider resolvedVersions(project.configurations.testRuntimeClasspath)
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ This means that requests with the HTTP method `GET`, `HEAD`, `OPTIONS`, and `TRA

[[csrf-protection-stp]]
=== Synchronizer Token Pattern
The predominant and most comprehensive way to protect against CSRF attacks is to use the https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#General_Recommendation:_Synchronizer_Token_Pattern[Synchronizer Token Pattern].
The predominant and most comprehensive way to protect against CSRF attacks is to use the https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#synchronizer-token-pattern[Synchronizer Token Pattern].
This solution is to ensure that each HTTP request requires, in addition to our session cookie, a secure random generated value called a CSRF token must be present in the HTTP request.

When an HTTP request is submitted, the server must look up the expected CSRF token and compare it against the actual CSRF token in the HTTP request.
Expand Down Expand Up @@ -348,7 +348,7 @@ This allows the expected CSRF token to outlive the session.
One might ask why the expected CSRF token isn't stored in a cookie by default.
This is because there are known exploits in which headers (for example, to specify the cookies) can be set by another domain.
This is the same reason Ruby on Rails https://weblog.rubyonrails.org/2011/2/8/csrf-protection-bypass-in-ruby-on-rails/[no longer skips CSRF checks when the header X-Requested-With is present].
See http://lists.webappsec.org/pipermail/websecurity_lists.webappsec.org/2011-February/007533.html[this webappsec.org thread] for details on how to perform the exploit.
See https://web.archive.org/web/20210221120355/https://lists.webappsec.org/pipermail/websecurity_lists.webappsec.org/2011-February/007533.html[this webappsec.org thread] for details on how to perform the exploit.
Another disadvantage is that by removing the state (that is, the timeout), you lose the ability to forcibly invalidate the token if it is compromised.

// FIXME: Document timeout with lengthy form expire. We do not want to automatically replay that request because it can lead to exploit
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This portion of the documentation discusses the general topic of Security HTTP R
Refer to the relevant sections for specific information on Security HTTP Response Headers <<servlet-headers,servlet>> and <<webflux-headers,WebFlux>> based applications.
====

There are many https://www.owasp.org/index.php/OWASP_Secure_Headers_Project#tab=Headers[HTTP response headers] that can be used to increase the security of web 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.
This section is dedicated to the various HTTP response headers that Spring Security provides explicit support for.
If necessary, Spring Security can also be configured to provide <<headers-custom,custom headers>>.

Expand Down Expand Up @@ -267,7 +267,7 @@ Content-Security-Policy: script-src https://trustedscripts.example.com; report-u
----
====

https://www.w3.org/TR/CSP2/#violation-reports[Violation reports] are standard JSON structures that can be captured either by the web application's own API or by a publicly hosted CSP violation reporting service, such as, https://report-uri.io/.
https://www.w3.org/TR/CSP2/#violation-reports[Violation reports] are standard JSON structures that can be captured either by the web application's own API or by a publicly hosted CSP violation reporting service, such as, https://report-uri.com/.

The `Content-Security-Policy-Report-Only` header provides the capability for web application authors and administrators to monitor security policies, rather than enforce them.
This header is typically used when experimenting and/or developing security policies for a site.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Without proper configuration, the application server will not know that the load

To fix this you can use https://tools.ietf.org/html/rfc7239[RFC 7239] to specify that a load balancer is being used.
To make the application aware of this, you need to either configure your application server aware of the X-Forwarded headers.
For example Tomcat uses the https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[RemoteIpValve] and Jetty uses https://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[ForwardedRequestCustomizer].
For example Tomcat uses the https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[RemoteIpValve] and Jetty uses https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[ForwardedRequestCustomizer].
Alternatively, Spring users can leverage https://github.com/spring-projects/spring-framework/blob/v4.3.3.RELEASE/spring-web/src/main/java/org/springframework/web/filter/ForwardedHeaderFilter.java[ForwardedHeaderFilter].

Spring Boot users may use the `server.use-forward-headers` property to configure the application.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The topics in this section provide detail on how to consume Spring Security when
=== Spring Boot with Maven

Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies together.
The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/html/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.

Alternatively, you can manually add the starter, as the following example shows:

Expand Down Expand Up @@ -196,7 +196,7 @@ The following topics provide detail on how to consume Spring Security when using
=== Spring Boot with Gradle

Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies together.
The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/html/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.

Alternatively, you can manually add the starter, as the following example shows:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ To get around this, you can disable session fixation protection, but in newer Se
Note that switching between HTTP and HTTPS is not a good idea in general, as any application which uses HTTP at all is vulnerable to man-in-the-middle attacks.
To be truly secure, the user should begin accessing your site in HTTPS and continue using it until they log out.
Even clicking on an HTTPS link from a page accessed over HTTP is potentially risky.
If you need more convincing, check out a tool like https://www.thoughtcrime.org/software/sslstrip/[sslstrip].
If you need more convincing, check out a tool like https://github.com/moxie0/sslstrip/[sslstrip].


==== I'm not switching between HTTP and HTTPS but my session is still getting lost
Expand Down Expand Up @@ -378,7 +378,7 @@ For third-party jars the situation isn't always quite so obvious.
A good starting point is to copy those from one of the pre-built sample applications WEB-INF/lib directories.
For a basic application, you can start with the tutorial sample.
If you want to use LDAP, with an embedded test server, then use the LDAP sample as a starting point.
The reference manual also includes https://static.springsource.org/spring-security/site/docs/3.1.x/reference/springsecurity-single.html#appendix-dependencies[an appendix] listing the first-level dependencies for each Spring Security module with some information on whether they are optional and what they are required for.
The reference manual also includes {security-reference-url}#modules[an appendix] listing the first-level dependencies for each Spring Security module with some information on whether they are optional and what they are required for.

If you are building your project with maven, then adding the appropriate Spring Security modules as dependencies to your pom.xml will automatically pull in the core jars that the framework requires.
Any which are marked as "optional" in the Spring Security POM files will have to be added to your own pom.xml file if you need them.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Without proper configuration, the application server will not know that the load

To fix this you can use https://tools.ietf.org/html/rfc7239[RFC 7239] to specify that a load balancer is being used.
To make the application aware of this, you need to either configure your application server aware of the X-Forwarded headers.
For example Tomcat uses the https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[RemoteIpValve] and Jetty uses https://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[ForwardedRequestCustomizer].
For example Tomcat uses the https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[RemoteIpValve] and Jetty uses https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[ForwardedRequestCustomizer].
Alternatively, Spring 4.3+ users can leverage https://github.com/spring-projects/spring-framework/blob/v4.3.3.RELEASE/spring-web/src/main/java/org/springframework/web/filter/ForwardedHeaderFilter.java[ForwardedHeaderFilter].

Spring Boot users may use the `server.use-forward-headers` property to configure the application.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[[servlet-delegatingfilterproxy]]
= DelegatingFilterProxy

Spring provides a `Filter` implementation named {security-api-url}org/springframework/web/filter/DelegatingFilterProxy.html/[`DelegatingFilterProxy`] that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
Spring provides a `Filter` implementation named {spring-framework-api-url}org/springframework/web/filter/DelegatingFilterProxy.html[`DelegatingFilterProxy`] that allows bridging between the Servlet container's lifecycle and Spring's `ApplicationContext`.
The Servlet container allows registering ``Filter``s using its own standards, but it is not aware of Spring defined Beans.
`DelegatingFilterProxy` can be registered via standard Servlet container mechanisms, but delegate all the work to a Spring Bean that implements `Filter`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ class="org.springframework.security.authentication.jaas.DefaultJaasAuthenticatio

[[jaas-jaasauthenticationprovider]]
=== JaasAuthenticationProvider
The `JaasAuthenticationProvider` assumes the default `Configuration` is an instance of https://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/login/ConfigFile.html[ ConfigFile].
The `JaasAuthenticationProvider` assumes the default `Configuration` is an instance of https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/login/ConfigFile.html[ ConfigFile].
This assumption is made in order to attempt to update the `Configuration`.
The `JaasAuthenticationProvider` then uses the default `Configuration` to create the `LoginContext`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ If you have more than one in your application context, you need to specify which

[[remember-me-persistent-token]]
=== Persistent Token Approach
This approach is based on the article http://jaspan.com/improved_persistent_login_cookie_best_practice[http://jaspan.com/improved_persistent_login_cookie_best_practice] with some minor modifications footnote:[Essentially, the username is not included in the cookie, to prevent exposing a valid login name unecessarily.
This approach is based on the article https://web.archive.org/web/20180819014446/http://jaspan.com/improved_persistent_login_cookie_best_practice[http://jaspan.com/improved_persistent_login_cookie_best_practice] with some minor modifications footnote:[Essentially, the username is not included in the cookie, to prevent exposing a valid login name unecessarily.
There is a discussion on this in the comments section of this article.].
To use the this approach with namespace configuration, you would supply a datasource reference:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,7 @@ For details, refer to the <<servlet-csrf-configure-custom-repository>> 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 <<nsa-access-denied-handler,xml>> and https://github.com/spring-projects/spring-security/blob/3.2.0.RC1/config/src/test/java/org/springframework/security/config/annotation/web/configurers/NamespaceHttpAccessDeniedHandlerTests.java#L64[Java configuration].
For an example of how to customize the `AccessDeniedHandler` refer to the provided links for both <<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


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ fun httpFirewall(): StrictHttpFirewall {
----
====

The `StrictHttpFirewall` provides an allowed list of valid HTTP methods that are allowed to protect against https://www.owasp.org/index.php/Cross_Site_Tracing[Cross Site Tracing (XST)] and https://www.owasp.org/index.php/Test_HTTP_Methods_(OTG-CONFIG-006)[HTTP Verb Tampering].
The `StrictHttpFirewall` provides an allowed list of valid HTTP methods that are allowed to protect against https://owasp.org/www-community/attacks/Cross_Site_Tracing[Cross Site Tracing (XST)] and https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/02-Configuration_and_Deployment_Management_Testing/06-Test_HTTP_Methods[HTTP Verb Tampering].
The default valid methods are "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", and "PUT".
If your application needs to modify the valid methods, you can configure a custom `StrictHttpFirewall` bean.
For example, the following will only allow HTTP "GET" and "POST" methods:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ This means developers need to explicitly protect their applications from externa
==== Spring WebSocket Allowed Origin

Fortunately, since Spring 4.1.5 Spring's WebSocket and SockJS support restricts access to the https://docs.spring.io/spring/docs/current/spring-framework-reference/html/websocket.html#websocket-server-allowed-origins[current domain].
Spring Security adds an additional layer of protection to provide https://en.wikipedia.org/wiki/Defense_in_depth_%2528computing%2529[defence in depth].
Spring Security adds an additional layer of protection to provide https://en.wikipedia.org/wiki/Defense_in_depth_(computing)[defence in depth].

[[websocket-sameorigin-csrf]]
==== Adding CSRF to Stomp Headers
Expand Down
Loading

0 comments on commit 95a1ccb

Please sign in to comment.