From f561499683cc79a272df5cb3ec614edd0e2961f9 Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Tue, 5 Oct 2021 22:36:03 +0200 Subject: [PATCH] Fix Antora cross-references that lead to other pages. Also using AsciiDoc style listings instead of Markdown style listings, and using explicit section IDs on all cross-references. --- .../pages/reactive/oauth2/access-token.adoc | 2 +- .../reactive/oauth2/resource-server.adoc | 10 ++++--- .../pages/servlet/configuration/java.adoc | 2 ++ .../servlet/oauth2/oauth2-resourceserver.adoc | 10 ++++--- .../ROOT/pages/servlet/saml2/index.adoc | 2 +- .../ROOT/pages/servlet/saml2/saml2-login.adoc | 28 +++++++++---------- .../ROOT/pages/servlet/test/mockmvc.adoc | 4 +-- 7 files changed, 32 insertions(+), 26 deletions(-) diff --git a/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc b/docs/modules/ROOT/pages/reactive/oauth2/access-token.adoc index 27d272c089..4db18e768b 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 xref:reactive/registered-oauth2-authorized-client.adoc#webflux-roac[@RegisteredOAuth2AuthorizedClient] support to obtain and use the access token. +You can now leverage Spring Security's xref:reactive/integrations/webclient.adoc[webclient] 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/resource-server.adoc b/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc index 443b54aff7..68ad9539b9 100644 --- a/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc +++ b/docs/modules/ROOT/pages/reactive/oauth2/resource-server.adoc @@ -504,9 +504,10 @@ fun conversionServiceCustomizer(): BeanFactoryPostProcessor { Specify your key's location: -```yaml +[source,yaml] +---- key.location: hfds://my-key.pub -``` +---- And then autowire the value: @@ -946,10 +947,11 @@ This startup process is quite a bit simpler than for JWTs since no endpoints nee Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header: -```http +[source,http] +---- GET / HTTP/1.1 Authorization: Bearer some-token-value # Resource Server will process this -``` +---- So long as this scheme is indicated, Resource Server will attempt to process the request according to the Bearer Token specification. diff --git a/docs/modules/ROOT/pages/servlet/configuration/java.adoc b/docs/modules/ROOT/pages/servlet/configuration/java.adoc index bf100524cc..985a01c516 100644 --- a/docs/modules/ROOT/pages/servlet/configuration/java.adoc +++ b/docs/modules/ROOT/pages/servlet/configuration/java.adoc @@ -68,6 +68,7 @@ The way in which we use `AbstractSecurityWebApplicationInitializer` differs depe * <> - Use these instructions if you are not using Spring already * <> - Use these instructions if you are already using Spring +[[abstractsecuritywebapplicationinitializer-without-existing-spring]] === AbstractSecurityWebApplicationInitializer without Existing Spring If you are not using Spring or Spring MVC, you will need to pass in the `WebSecurityConfig` into the superclass to ensure the configuration is picked up. @@ -91,6 +92,7 @@ The `SecurityWebApplicationInitializer` will do the following things: * Automatically register the springSecurityFilterChain Filter for every URL in your application * Add a ContextLoaderListener that loads the <>. +[[abstractsecuritywebapplicationinitializer-with-spring-mvc]] === AbstractSecurityWebApplicationInitializer with Spring MVC If we were using Spring elsewhere in our application we probably already had a `WebApplicationInitializer` that is loading our Spring Configuration. diff --git a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc index 14732c21a6..d9b584188c 100644 --- a/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc +++ b/docs/modules/ROOT/pages/servlet/oauth2/oauth2-resourceserver.adoc @@ -681,9 +681,10 @@ fun conversionServiceCustomizer(): BeanFactoryPostProcessor { Specify your key's location: -```yaml +[source,yaml] +---- key.location: hfds://my-key.pub -``` +---- And then autowire the value: @@ -1486,10 +1487,11 @@ This startup process is quite a bit simpler than for JWTs since no endpoints nee Once the application is started up, Resource Server will attempt to process any request containing an `Authorization: Bearer` header: -```http +[source,http] +---- GET / HTTP/1.1 Authorization: Bearer some-token-value # Resource Server will process this -``` +---- So long as this scheme is indicated, Resource Server will attempt to process the request according to the Bearer Token specification. diff --git a/docs/modules/ROOT/pages/servlet/saml2/index.adoc b/docs/modules/ROOT/pages/servlet/saml2/index.adoc index 43a9baf4d1..472ff1887a 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/index.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/index.adoc @@ -16,7 +16,7 @@ https://www.oasis-open.org/committees/download.php/35389/sstc-saml-profiles-erra [[servlet-saml2login-spring-security-history]] Since 2009, support for relying parties has existed as an https://github.com/spring-projects/spring-security-saml/tree/1e013b07a7772defd6a26fcfae187c9bf661ee8f#spring-saml[extension project]. In 2019, the process began to port that into https://github.com/spring-projects/spring-security[Spring Security] proper. -This process is similar to the one started in 2017 for <>. +This process is similar to the one started in 2017 for xref:servlet/oauth2/index.adoc[Spring Security's OAuth 2.0 support]. [NOTE] ==== diff --git a/docs/modules/ROOT/pages/servlet/saml2/saml2-login.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml2-login.adoc index 648ff2e2a4..1259f73bc5 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/saml2-login.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/saml2-login.adoc @@ -13,7 +13,7 @@ https://www.oasis-open.org/committees/download.php/35389/sstc-saml-profiles-erra [[servlet-saml2login-spring-security-history]] Since 2009, support for relying parties has existed as an https://github.com/spring-projects/spring-security-saml/tree/1e013b07a7772defd6a26fcfae187c9bf661ee8f#spring-saml[extension project]. In 2019, the process began to port that into https://github.com/spring-projects/spring-security[Spring Security] proper. -This process is similar to the one started in 2017 for <>. +This process is similar to the one started in 2017 for xref:servlet/oauth2/index.adoc[Spring Security's OAuth 2.0 support]. [NOTE] ==== @@ -21,20 +21,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[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.adoc#servlet-securityfilterchain[`SecurityFilterChain`] and xref:servlet/authentication/architecture.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.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__. +The configured xref:servlet/authentication/architecture.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 <>. @@ -49,23 +49,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.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.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.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`] is cleared out. +* The xref:servlet/authentication/architecture.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.adoc#servlet-authentication-authentication[`Authentication`] is set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[`SecurityContextHolder`]. * The `Saml2WebSsoAuthenticationFilter` invokes `FilterChain#doFilter(request,response)` to continue with the rest of the application logic. [[servlet-saml2login-minimaldependencies]] @@ -167,9 +167,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.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.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. @@ -1306,7 +1306,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/passwords/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 dd712ec6cf..99a41d6e18 100644 --- a/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc +++ b/docs/modules/ROOT/pages/servlet/test/mockmvc.adoc @@ -366,7 +366,7 @@ mvc.get("/") { ==== Running as a User in Spring MVC Test with Annotations -As an alternative to using a `RequestPostProcessor` to create your user, you can use annotations described in <>. +As an alternative to using a `RequestPostProcessor` to create your user, you can use annotations described in xref:servlet/test/method.adoc[Testing Method Security]. For example, the following will run the test with the user with username "user", password "password", and role "ROLE_USER": ==== @@ -1903,7 +1903,7 @@ import static org.springframework.security.test.web.servlet.response.SecurityMoc ==== Exporting the SecurityContext Often times we want to query a repository to see if some `MockMvc` request actually persisted in the database. -In some cases our repository query uses the <> to filter the results based on current user's username or any other property. +In some cases our repository query uses the xref:features/integrations/data.adoc[Spring Data Integration] to filter the results based on current user's username or any other property. Let's see an example: A repository interface: