From 2909d460600f397cfd250f26835e87e6a4994f0f Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 10 Feb 2020 10:47:21 -0600 Subject: [PATCH] Fix Asciidoctor Warnings Closes gh-7973 --- .../authentication/password-storage.adoc | 20 ++++++----- .../about/getting-spring-security.adoc | 2 +- .../asciidoc/_includes/about/samples.adoc | 1 + .../_includes/reactive/exploits/csrf.adoc | 2 +- .../_includes/reactive/exploits/http.adoc | 2 +- .../_includes/reactive/oauth2/login.adoc | 8 ++--- .../reactive/oauth2/resource-server.adoc | 5 +-- .../_includes/servlet/appendix/namespace.adoc | 26 +++++++------- .../servlet/architecture/core-services.adoc | 4 +-- .../_includes/servlet/architecture/index.adoc | 4 +++ .../authentication-provider.adoc | 2 +- .../_includes/servlet/authentication/cas.adoc | 6 ++-- .../authentication/session-management.adoc | 3 +- .../unpwd/storage/in-memory.adoc | 14 ++++---- .../authentication/unpwd/storage/jdbc.adoc | 8 ++--- .../authentication/unpwd/storage/ldap.adoc | 24 ++++++------- .../authorization/expression-based.adoc | 6 ++-- .../_includes/servlet/exploits/http.adoc | 2 +- .../_includes/servlet/namespace/index.adoc | 8 ++--- .../servlet/oauth2/oauth2-client.adoc | 12 +++---- .../servlet/oauth2/oauth2-login.adoc | 12 +++---- .../servlet/oauth2/oauth2-resourceserver.adoc | 1 + .../_includes/servlet/saml2/saml2-login.adoc | 35 +++++++++---------- 23 files changed, 107 insertions(+), 100 deletions(-) diff --git a/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc b/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc index e72d3536f0..6fe994c7fd 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/authentication/password-storage.adoc @@ -51,7 +51,7 @@ The short term credential can be validated quickly without any loss in security. == DelegatingPasswordEncoder Prior to Spring Security 5.0 the default `PasswordEncoder` was `NoOpPasswordEncoder` which required plain text passwords. -Based upon the <> section you might expect that the default `PasswordEncoder` is now something like `BCryptPasswordEncoder`. +Based upon the <> section you might expect that the default `PasswordEncoder` is now something like `BCryptPasswordEncoder`. However, this ignores three real world problems: - There are many applications using old password encodings that cannot easily migrate @@ -101,7 +101,7 @@ The general format for a password is: .DelegatingPasswordEncoder Storage Format ==== -[source,text] +[source,text,attrs="-attributes"] ---- {id}encodedPassword ---- @@ -115,7 +115,7 @@ All of the original passwords are "password". .DelegatingPasswordEncoder Encoded Passwords Example ==== -[source,text] +[source,text,attrs="-attributes"] ---- {bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG // <1> {noop}password // <2> @@ -148,12 +148,12 @@ For example, BCrypt passwords often start with `$2a$`. === Password Encoding The `idForEncode` passed into the constructor determines which `PasswordEncoder` will be used for encoding passwords. -In the `DelegatingPasswordEncoder` we constructed above, that means that the result of encoding `password` would be delegated to `BCryptPasswordEncoder` and be prefixed with `{bcrypt}`. +In the `DelegatingPasswordEncoder` we constructed above, that means that the result of encoding `password` would be delegated to `BCryptPasswordEncoder` and be prefixed with `+{bcrypt}+`. The end result would look like: .DelegatingPasswordEncoder Encode Example ==== -[source,text] +[source,text,attrs="-attributes"] ---- {bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG ---- @@ -162,7 +162,7 @@ The end result would look like: [[authentication-password-storage-dpe-matching]] === Password Matching -Matching is done based upon the `{id}` and the mapping of the `id` to the `PasswordEncoder` provided in the constructor. +Matching is done based upon the `+{id}+` and the mapping of the `id` to the `PasswordEncoder` provided in the constructor. Our example in <> provides a working example of how this is done. By default, the result of invoking `matches(CharSequence, String)` with a password and an `id` that is not mapped (including a null id) will result in an `IllegalArgumentException`. This behavior can be customized using `DelegatingPasswordEncoder.setDefaultPasswordEncoderForMatches(PasswordEncoder)`. @@ -180,7 +180,7 @@ There are convenience mechanisms to make this easier, but this is still not inte .withDefaultPasswordEncoder Example ==== -[source,java] +[source,java,attrs="-attributes"] ---- User user = User.withDefaultPasswordEncoder() .username("user") @@ -225,7 +225,7 @@ For example, the following will encode the password of `password` for use with < .Spring Boot CLI encodepassword Example ==== -[source] +[source,attrs="-attributes"] ---- spring encodepassword password {bcrypt}$2a$10$X5wFBtLrL/kHcmrOGGTrGufsBX8CJ0WpQpF3pgeuxBB/H73BK1DW6 @@ -235,7 +235,7 @@ spring encodepassword password [[authentication-password-storage-dpe-troubleshoot]] === Troubleshooting -The following error occurs when one of the passwords that are stored has no id as described in <>. +The following error occurs when one of the passwords that are stored has no id as described in <>. ---- java.lang.IllegalArgumentException: There is no PasswordEncoder mapped for the id "null" @@ -257,6 +257,8 @@ $2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG to + +[source,attrs="-attributes"] ---- {bcrypt}$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG ---- diff --git a/docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc b/docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc index 63839b9b5a..c2b64f113a 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc @@ -276,7 +276,7 @@ dependencies { If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <>. -Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x. {JB} +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. The easiest way to resolve this is to use the `spring-framework-bom` within your `` section of your `pom.xml`. You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows: diff --git a/docs/manual/src/docs/asciidoc/_includes/about/samples.adoc b/docs/manual/src/docs/asciidoc/_includes/about/samples.adoc index 47f72cebc8..af712c01b7 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/samples.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/samples.adoc @@ -1,3 +1,4 @@ +[[samples]] = Samples Spring Security includes many {gh-samples-url}[samples] applications. diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/csrf.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/csrf.adoc index 3f4ce26546..3cfc1d2619 100644 --- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/csrf.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/csrf.adoc @@ -83,7 +83,7 @@ In order for the <> to protect a 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`. -This means that any view technology can access the `Mono` to expose the expected token as either a <> or <>. +This means that any view technology can access the `Mono` to expose the expected token as either a <> or <>. [[webflux-csrf-include-subscribe]] If your view technology does not provide a simple way to subscribe to the `Mono`, a common pattern is to use Spring's `@ControllerAdvice` to expose the `CsrfToken` directly. diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc index 20c36393bc..851142d660 100644 --- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc @@ -54,4 +54,4 @@ Spring Security provides support for <>. +Spring Security <>. diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc index 4c4d5483a3..fbc1be05c8 100644 --- a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc @@ -38,11 +38,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 <>. +TIP: The default redirect URI template is `+{baseUrl}/login/oauth2/code/{registrationId}+`. +The *_registrationId_* is a unique identifier for the <>. 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. +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`. [[webflux-oauth2-login-sample-config]] @@ -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 <>, 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/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc index 576007453a..5e45a74427 100644 --- a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/resource-server.adoc @@ -117,7 +117,7 @@ We still specify the `issuer-uri` so that Resource Server still validates the `i [NOTE] This property can also be supplied directly on the <>. -[[webflux-oauth2resourceserver-sansboot]] +[[webflux-oauth2resourceserver-jwt-sansboot]] === Overriding or Replacing Boot Auto Configuration There are two `@Bean` s that Spring Boot generates on Resource Server's behalf. @@ -559,6 +559,7 @@ This can be handy when revocation is a requirement. When using https://spring.io/projects/spring-boot[Spring Boot], configuring an application as a resource server that uses introspection consists of two basic steps. First, include the needed dependencies and second, indicate the introspection endpoint details. +[[webflux-oauth2resourceserver-opaque-introspectionuri]] ==== Specifying the Authorization Server To specify where the introspection endpoint is, simply do: @@ -1005,7 +1006,7 @@ ReactiveOpaqueTokenIntrospector introspector() { } ---- -[[oauth2resourceserver-multitenancy]] +[[webflux-oauth2resourceserver-multitenancy]] == Multi-tenancy A resource server is considered multi-tenant when there are multiple strategies for verifying a bearer token, keyed by some tenant identifier. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc index e1e01974a6..9b1052e389 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc @@ -1248,7 +1248,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 the <>. +An example of overriding these can be found in <>. [[nsa-port-mappings-parents]] @@ -1751,7 +1751,7 @@ All elements which create `AuthenticationProvider` instances should be children [[nsa-authentication-manager-alias]] * **alias** This attribute allows you to define an alias name for the internal instance for use in your own configuration. -Its use is described in the<>. +Its use is described in the <>. [[nsa-authentication-manager-erase-credentials]] @@ -1912,7 +1912,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 <>. This will result in the bean being injected with the appropriate `PasswordEncoder` instance. @@ -2338,7 +2338,7 @@ A method name [[nsa-ldap]] === LDAP Namespace Options -LDAP is covered in some details in <>. +LDAP is covered in some details in <>. 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. @@ -2348,7 +2348,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 <>. 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. @@ -2443,7 +2443,7 @@ Defaults to "" (searching from the root). * **group-search-filter** Group search filter. Maps to the ``DefaultLdapAuthoritiesPopulator``'s `groupSearchFilter` property. -Defaults to (uniqueMember={0}). +Defaults to `+(uniqueMember={0})+`. The substituted parameter is the DN of the user. @@ -2476,8 +2476,8 @@ If set, the framework will attempt to load standard attributes for the defined c * **user-dn-pattern** If your users are at a fixed location in the directory (i.e. you can work out the DN directly from the username without doing a directory search), you can use this attribute to map directly to the DN. It maps directly to the `userDnPatterns` property of `AbstractLdapAuthenticator`. -The value is a specific pattern used to build the user's DN, for example "uid={0},ou=people". -The key "{0}" must be present and will be substituted with the username. +The value is a specific pattern used to build the user's DN, for example `+uid={0},ou=people+`. +The key `+{0}+` must be present and will be substituted with the username. [[nsa-ldap-authentication-provider-user-search-base]] @@ -2490,20 +2490,20 @@ Only used with a 'user-search-filter'. If you need to perform a search to locate the user in the directory, then you can set these attributes to control the search. The `BindAuthenticator` will be configured with a `FilterBasedLdapUserSearch` and the attribute values map directly to the first two arguments of that bean's constructor. -If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `user-search-filter="(uid={0})"` and `user-search-base=""` will be used. +If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` will be used. [[nsa-ldap-authentication-provider-user-search-filter]] * **user-search-filter** The LDAP filter used to search for users (optional). -For example "(uid={0})". +For example `+(uid={0})+`. The substituted parameter is the user's login name. + If you need to perform a search to locate the user in the directory, then you can set these attributes to control the search. The `BindAuthenticator` will be configured with a `FilterBasedLdapUserSearch` and the attribute values map directly to the first two arguments of that bean's constructor. -If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `user-search-filter="(uid={0})"` and `user-search-base=""` will be used. +If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` will be used. [[nsa-ldap-authentication-provider-children]] @@ -2582,7 +2582,7 @@ Defaults to "" (searching from the root). [[nsa-ldap-user-service-group-search-filter]] * **group-search-filter** Group search filter. -Defaults to (uniqueMember={0}). +Defaults to `+(uniqueMember={0})+`. The substituted parameter is the DN of the user. @@ -2625,5 +2625,5 @@ Only used with a 'user-search-filter'. [[nsa-ldap-user-service-user-search-filter]] * **user-search-filter** The LDAP filter used to search for users (optional). -For example "(uid={0})". +For example `+(uid={0})+`. The substituted parameter is the user's login name. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/core-services.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/core-services.adoc index d6528721da..dc9bb50078 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/core-services.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/architecture/core-services.adoc @@ -79,7 +79,7 @@ Configuring the provider is quite simple: The `PasswordEncoder` is optional. A `PasswordEncoder` provides encoding and matching of encoded passwords presented in the `UserDetails` object that is returned from the configured `UserDetailsService`. -This will be discussed in more detail <>. +This is discussed in more detail in <>. === UserDetailsService Implementations @@ -105,7 +105,7 @@ Is easy to use create a custom `UserDetailsService` implementation that extracts This is particularly true if you're building a prototype application or just starting integrating Spring Security, when you don't really want to spend time configuring databases or writing `UserDetailsService` implementations. For this sort of situation, a simple option is to use the `user-service` element from the security <>: -[source,xml] +[source,xml,attrs="-attributes"] ----