Separate Namespace Servlet Docs

Issue gh-10367

Author: jzheaux

config/src/test/java/org/springframework/security/config/doc/XsdDocumentedTests.java

@@ -16,9 +16,10 @@
 
 package org.springframework.security.config.doc;
 
+import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
-import java.nio.file.Paths;
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
@@ -60,7 +61,7 @@ public class XsdDocumentedTests {
 			"nsa-frame-options-from-parameter");
 	// @formatter:on
 
-	String referenceLocation = "../docs/modules/ROOT/pages/servlet/appendix/namespace.adoc";
+	String referenceLocation = "../docs/modules/ROOT/pages/servlet/appendix/namespace";
 
 	String schema31xDocumentLocation = "org/springframework/security/config/spring-security-3.1.xsd";
 
@@ -163,7 +164,7 @@ public void sizeWhenReadingFilesystemThenIsCorrectNumberOfSchemaFiles() throws I
 	public void countReferencesWhenReviewingDocumentationThenEntireSchemaIsIncluded() throws IOException {
 		Map<String, Element> elementsByElementName = this.xml.elementsByElementName(this.schemaDocumentLocation);
 		// @formatter:off
-		List<String> documentIds = Files.lines(Paths.get(this.referenceLocation))
+		List<String> documentIds = namespaceLines()
 				.filter((line) -> line.matches("\\[\\[(nsa-.*)\\]\\]"))
 				.map((line) -> line.substring(2, line.length() - 2))
 				.collect(Collectors.toList());
@@ -189,7 +190,7 @@ public void countLinksWhenReviewingDocumentationThenParentsAndChildrenAreCorrect
 		Map<String, List<String>> docAttrNameToParents = new TreeMap<>();
 		String docAttrName = null;
 		Map<String, List<String>> currentDocAttrNameToElmt = null;
-		List<String> lines = Files.readAllLines(Paths.get(this.referenceLocation));
+		List<String> lines = namespaceLines().collect(Collectors.toList());
 		for (String line : lines) {
 			if (line.matches("^\\[\\[.*\\]\\]$")) {
 				String id = line.substring(2, line.length() - 2);
@@ -212,6 +213,13 @@ else if (id.endsWith("-attributes") || docAttrName != null && !id.startsWith(doc
 					String elmtId = line.replaceAll(expression, "$1");
 					currentDocAttrNameToElmt.computeIfAbsent(docAttrName, (key) -> new ArrayList<>()).add(elmtId);
 				}
+				else {
+					expression = ".*xref:.*#(nsa-.*)\\[.*\\]";
+					if (line.matches(expression)) {
+						String elmtId = line.replaceAll(expression, "$1");
+						currentDocAttrNameToElmt.computeIfAbsent(docAttrName, (key) -> new ArrayList<>()).add(elmtId);
+					}
+				}
 			}
 		}
 		Map<String, Element> elementNameToElement = this.xml.elementsByElementName(this.schemaDocumentLocation);
@@ -295,4 +303,17 @@ public void countWhenReviewingDocumentationThenAllElementsDocumented() throws IO
 		assertThat(notDocAttrIds).isEmpty();
 	}
 
+	private Stream<String> namespaceLines() {
+		return Stream.of(new File(this.referenceLocation).listFiles()).map(File::toPath).flatMap(this::fileLines);
+	}
+
+	private Stream<String> fileLines(Path path) {
+		try {
+			return Files.lines(path);
+		}
+		catch (Exception ex) {
+			throw new RuntimeException(ex);
+		}
+	}
+
 }

docs/modules/ROOT/nav.adoc

@@ -100,7 +100,12 @@
 *** xref:servlet/test/mockmvc/result-handlers.adoc[Security ResultHandlers]
 ** xref:servlet/appendix/index.adoc[Appendix]
 *** xref:servlet/appendix/database-schema.adoc[Database Schemas]
-*** xref:servlet/appendix/namespace.adoc[XML Namespace]
+*** xref:servlet/appendix/namespace/index.adoc[XML Namespace]
+**** xref:servlet/appendix/namespace/authentication-manager.adoc[Authentication Services]
+**** xref:servlet/appendix/namespace/http.adoc[Web Security]
+**** xref:servlet/appendix/namespace/method-security.adoc[Method Security]
+**** xref:servlet/appendix/namespace/ldap.adoc[LDAP Security]
+**** xref:servlet/appendix/namespace/websocket.adoc[WebSocket Security]
 *** xref:servlet/appendix/faq.adoc[FAQ]
 * xref:reactive/index.adoc[Reactive Applications]
 ** xref:reactive/getting-started.adoc[Getting Started]

docs/modules/ROOT/pages/features/integrations/concurrency.adoc

@@ -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 xref:servlet/appendix/namespace.adoc#nsa-global-method-security[<global-method-security>] support to secure one of your services.
+For example, you might have used Spring Security's xref:servlet/appendix/namespace/method-security.adoc#nsa-global-method-security[<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:
 

docs/modules/ROOT/pages/servlet/appendix/index.adoc

@@ -4,5 +4,5 @@ This is an appendix for Servlet based Spring Security.
 It has the following sections:
 
 * xref:servlet/appendix/database-schema.adoc[Database Schemas]
-* xref:servlet/appendix/namespace.adoc[XML Namespace]
+* xref:servlet/appendix/namespace/index.adoc[XML Namespace]
 * xref:servlet/appendix/faq.adoc[FAQ]

docs/modules/ROOT/pages/servlet/appendix/namespace/authentication-manager.adoc

@@ -0,0 +1,292 @@
+[[nsa-authentication]]
+= Authentication Services
+Before Spring Security 3.0, an `AuthenticationManager` was automatically registered internally.
+Now you must register one explicitly using the `<authentication-manager>` element.
+This creates an instance of Spring Security's `ProviderManager` class, which needs to be configured with a list of one or more `AuthenticationProvider` instances.
+These can either be created using syntax elements provided by the namespace, or they can be standard bean definitions, marked for addition to the list using the `authentication-provider` element.
+
+
+[[nsa-authentication-manager]]
+== <authentication-manager>
+Every Spring Security application which uses the namespace must have include this element somewhere.
+It is responsible for registering the `AuthenticationManager` which provides authentication services to the application.
+All elements which create `AuthenticationProvider` instances should be children of this element.
+
+
+[[nsa-authentication-manager-attributes]]
+=== <authentication-manager> Attributes
+
+
+[[nsa-authentication-manager-alias]]
+* **alias**
+This attribute allows you to define an alias name for the internal instance for use in your own configuration.
+
+
+[[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 xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
+
+
+[[nsa-authentication-manager-id]]
+* **id**
+This attribute allows you to define an id for the internal instance for use in your own configuration.
+It is the same as the alias element, but provides a more consistent experience with elements that use the id attribute.
+
+
+[[nsa-authentication-manager-children]]
+=== Child Elements of <authentication-manager>
+
+
+* <<nsa-authentication-provider,authentication-provider>>
+* xref:servlet/appendix/namespace/ldap.adoc#nsa-ldap-authentication-provider[ldap-authentication-provider]
+
+
+
+[[nsa-authentication-provider]]
+== <authentication-provider>
+Unless used with a `ref` attribute, this element is shorthand for configuring a `DaoAuthenticationProvider`.
+`DaoAuthenticationProvider` loads user information from a `UserDetailsService` and compares the username/password combination with the values supplied at login.
+The `UserDetailsService` instance can be defined either by using an available namespace element (`jdbc-user-service` or by using the `user-service-ref` attribute to point to a bean defined elsewhere in the application context).
+
+
+
+[[nsa-authentication-provider-parents]]
+=== Parent Elements of <authentication-provider>
+
+
+* <<nsa-authentication-manager,authentication-manager>>
+
+
+
+[[nsa-authentication-provider-attributes]]
+=== <authentication-provider> Attributes
+
+
+[[nsa-authentication-provider-ref]]
+* **ref**
+Defines a reference to a Spring bean that implements `AuthenticationProvider`.
+
+If you have written your own `AuthenticationProvider` implementation (or want to configure one of Spring Security's own implementations as a traditional bean for some reason, then you can use the following syntax to add it to the internal list of `ProviderManager`:
+
+[source,xml]
+----
+
+<security:authentication-manager>
+  <security:authentication-provider ref="myAuthenticationProvider" />
+</security:authentication-manager>
+<bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider"/>
+
+----
+
+
+
+
+[[nsa-authentication-provider-user-service-ref]]
+* **user-service-ref**
+A reference to a bean that implements UserDetailsService that may be created using the standard bean element or the custom user-service element.
+
+
+[[nsa-authentication-provider-children]]
+=== Child Elements of <authentication-provider>
+
+
+* <<nsa-jdbc-user-service,jdbc-user-service>>
+* xref:servlet/appendix/namespace/ldap.adoc#nsa-ldap-user-service[ldap-user-service]
+* <<nsa-password-encoder,password-encoder>>
+* <<nsa-user-service,user-service>>
+
+
+
+[[nsa-jdbc-user-service]]
+== <jdbc-user-service>
+Causes creation of a JDBC-based UserDetailsService.
+
+
+[[nsa-jdbc-user-service-attributes]]
+=== <jdbc-user-service> Attributes
+
+
+[[nsa-jdbc-user-service-authorities-by-username-query]]
+* **authorities-by-username-query**
+An SQL statement to query for a user's granted authorities given a username.
+
+The default is
+
+[source]
+----
+select username, authority from authorities where username = ?
+----
+
+
+
+
+[[nsa-jdbc-user-service-cache-ref]]
+* **cache-ref**
+Defines a reference to a cache for use with a UserDetailsService.
+
+
+[[nsa-jdbc-user-service-data-source-ref]]
+* **data-source-ref**
+The bean ID of the DataSource which provides the required tables.
+
+
+[[nsa-jdbc-user-service-group-authorities-by-username-query]]
+* **group-authorities-by-username-query**
+An SQL statement to query user's group authorities given a username.
+The default is
+
++
+
+[source]
+----
+select
+g.id, g.group_name, ga.authority
+from
+groups g, group_members gm, group_authorities ga
+where
+gm.username = ? and g.id = ga.group_id and g.id = gm.group_id
+----
+
+
+
+
+[[nsa-jdbc-user-service-id]]
+* **id**
+A bean identifier, used for referring to the bean elsewhere in the context.
+
+
+[[nsa-jdbc-user-service-role-prefix]]
+* **role-prefix**
+A non-empty string prefix that will be added to role strings loaded from persistent storage (default is "ROLE_").
+Use the value "none" for no prefix in cases where the default is non-empty.
+
+
+[[nsa-jdbc-user-service-users-by-username-query]]
+* **users-by-username-query**
+An SQL statement to query a username, password, and enabled status given a username.
+The default is
+
++
+
+[source]
+----
+select username, password, enabled from users where username = ?
+----
+
+
+
+
+[[nsa-password-encoder]]
+== <password-encoder>
+Authentication providers can optionally be configured to use a password encoder as described in the xref:features/authentication/password-storage.adoc#authentication-password-storage[Password Storage].
+This will result in the bean being injected with the appropriate `PasswordEncoder` instance.
+
+
+[[nsa-password-encoder-parents]]
+=== Parent Elements of <password-encoder>
+
+
+* <<nsa-authentication-provider,authentication-provider>>
+* xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-password-compare[password-compare]
+
+
+
+[[nsa-password-encoder-attributes]]
+=== <password-encoder> Attributes
+
+
+[[nsa-password-encoder-hash]]
+* **hash**
+Defines the hashing algorithm used on user passwords.
+We recommend strongly against using MD4, as it is a very weak hashing algorithm.
+
+
+[[nsa-password-encoder-ref]]
+* **ref**
+Defines a reference to a Spring bean that implements `PasswordEncoder`.
+
+
+[[nsa-user-service]]
+== <user-service>
+Creates an in-memory UserDetailsService from a properties file or a list of "user" child elements.
+Usernames are converted to lower-case internally to allow for case-insensitive lookups, so this should not be used if case-sensitivity is required.
+
+
+[[nsa-user-service-attributes]]
+=== <user-service> Attributes
+
+
+[[nsa-user-service-id]]
+* **id**
+A bean identifier, used for referring to the bean elsewhere in the context.
+
+
+[[nsa-user-service-properties]]
+* **properties**
+The location of a Properties file where each line is in the format of
+
++
+
+[source]
+----
+username=password,grantedAuthority[,grantedAuthority][,enabled|disabled]
+----
+
+
+
+
+[[nsa-user-service-children]]
+=== Child Elements of <user-service>
+
+
+* <<nsa-user,user>>
+
+
+
+[[nsa-user]]
+== <user>
+Represents a user in the application.
+
+
+[[nsa-user-parents]]
+=== Parent Elements of <user>
+
+
+* <<nsa-user-service,user-service>>
+
+
+
+[[nsa-user-attributes]]
+=== <user> Attributes
+
+
+[[nsa-user-authorities]]
+* **authorities**
+One of more authorities granted to the user.
+Separate authorities with a comma (but no space).
+For example, "ROLE_USER,ROLE_ADMINISTRATOR"
+
+
+[[nsa-user-disabled]]
+* **disabled**
+Can be set to "true" to mark an account as disabled and unusable.
+
+
+[[nsa-user-locked]]
+* **locked**
+Can be set to "true" to mark an account as locked and unusable.
+
+
+[[nsa-user-name]]
+* **name**
+The username assigned to the user.
+
+
+[[nsa-user-password]]
+* **password**
+The password assigned to the user.
+This may be hashed if the corresponding authentication provider supports hashing (remember to set the "hash" attribute of the "user-service" element).
+This attribute be omitted in the case where the data will not be used for authentication, but only for accessing authorities.
+If omitted, the namespace will generate a random value, preventing its accidental use for authentication.
+Cannot be empty.