Extract subsections for preface

Issue: gh-2567

Author: rwinch

docs/manual/src/docs/asciidoc/_includes/preface.adoc

@@ -0,0 +1,31 @@
+
+[[community]]
+== Spring Security Community
+
+
+[[jira]]
+=== Issue Tracking
+Spring Security uses JIRA to manage bug reports and enhancement requests.
+If you find a bug, please log a report using JIRA.
+Do not log it on the support forum, mailing list or by emailing the project's developers.
+Such approaches are ad-hoc and we prefer to manage bugs using a more formal process.
+
+If possible, in your issue report please provide a JUnit test that demonstrates any incorrect behaviour.
+Or, better yet, provide a patch that corrects the issue.
+Similarly, enhancements are welcome to be logged in the issue tracker, although we only accept enhancement requests if you include corresponding unit tests.
+This is necessary to ensure project test coverage is adequately maintained.
+
+You can access the issue tracker at https://github.com/spring-projects/spring-security/issues.
+
+
+[[becoming-involved]]
+=== Becoming Involved
+We welcome your involvement in the Spring Security project.
+There are many ways of contributing, including reading the forum and responding to questions from other people, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, or simply making suggestions.
+
+
+[[further-info]]
+=== Further Information
+Questions and comments on Spring Security are welcome.
+You can use the Spring at Stack Overflow web site at http://spring.io/questions[http://spring.io/questions] to discuss Spring Security with other users of the framework.
+Remember to use JIRA for bug reports, as explained above.

docs/manual/src/docs/asciidoc/_includes/preface/community.adoc

@@ -0,0 +1,13 @@
+
+[[getting-started]]
+== Getting Started
+The later parts of this guide provide an in-depth discussion of the framework architecture and implementation classes, which you need to understand if you want to do any serious customization.
+In this part, we'll introduce Spring Security 4.
+0, give a brief overview of the project's history and take a slightly gentler look at how to get started using the framework.
+In particular, we'll look at namespace configuration which provides a much simpler way of securing your application compared to the traditional Spring bean approach where you have to wire up all the implementation classes individually.
+
+We'll also take a look at the sample applications that are available.
+It's worth trying to run these and experimenting with them a bit even before you read the later sections - you can dip back into them as your understanding of the framework increases.
+Please also check out the http://spring.
+io/spring-security[project website] as it has useful information on building the project, plus links to articles, videos and tutorials.
+

docs/manual/src/docs/asciidoc/_includes/preface/getting-started.adoc

@@ -0,0 +1,34 @@
+[[samples]]
+== Samples and Guides (Start Here)
+
+If you are looking to get started with Spring Security, the best place to start is our Sample Applications.
+
+.Sample Applications
+|===
+| Source | Description | Guide
+
+| {gh-samples-url}/javaconfig/helloworld[Hello Spring Security]
+| Demonstrates how to integrate Spring Security with an existing application using Java-based configuration.
+| link:../../guides/html5/helloworld-javaconfig.html[Hello Spring Security Guide]
+
+| {gh-samples-url}/boot/helloworld[Hello Spring Security Boot]
+| Demonstrates how to integrate Spring Security with an existing Spring Boot application.
+| link:../../guides/html5/helloworld-boot.html[Hello Spring Security Boot Guide]
+
+| {gh-samples-url}/xml/helloworld[Hello Spring Security XML]
+| Demonstrates how to integrate Spring Security with an existing application using XML-based configuration.
+| link:../../guides/html5/helloworld-xml.html[Hello Spring Security XML Guide]
+
+| {gh-samples-url}/javaconfig/hellomvc[Hello Spring MVC Security]
+| Demonstrates how to integrate Spring Security with an existing Spring MVC application.
+| link:../../guides/html5/hellomvc-javaconfig.html[Hello Spring MVC Security Guide]
+
+| {gh-samples-url}/javaconfig/form[Custom Login Form]
+| Demonstrates how to create a custom login form.
+| link:../../guides/html5/form-javaconfig.html[Custom Login Form Guide]
+
+| {gh-samples-url}/boot/oauth2login[OAuth 2.0 Login]
+| Demonstrates how to integrate OAuth 2.0 Login with an OAuth 2.0 or OpenID Connect 1.0 Provider.
+| link:{gh-samples-url}/boot/oauth2login/README.adoc[OAuth 2.0 Login Guide]
+
+|===

docs/manual/src/docs/asciidoc/_includes/preface/guides.adoc

@@ -0,0 +1,58 @@
+[[preface]]
+= Preface
+Spring Security provides a comprehensive security solution for Java EE-based enterprise software applications.
+As you will discover as you venture through this reference guide, we have tried to provide you a useful and highly configurable security system.
+
+Security is an ever-moving target, and it's important to pursue a comprehensive, system-wide approach.
+In security circles we encourage you to adopt "layers of security", so that each layer tries to be as secure as possible in its own right, with successive layers providing additional security.
+The "tighter" the security of each layer, the more robust and safe your application will be.
+At the bottom level you'll need to deal with issues such as transport security and system identification, in order to mitigate man-in-the-middle attacks.
+Next you'll generally utilise firewalls, perhaps with VPNs or IP security to ensure only authorised systems can attempt to connect.
+In corporate environments you may deploy a DMZ to separate public-facing servers from backend database and application servers.
+Your operating system will also play a critical part, addressing issues such as running processes as non-privileged users and maximising file system security.
+An operating system will usually also be configured with its own firewall.
+Hopefully somewhere along the way you'll be trying to prevent denial of service and brute force attacks against the system.
+An intrusion detection system will also be especially useful for monitoring and responding to attacks, with such systems able to take protective action such as blocking offending TCP/IP addresses in real-time.
+Moving to the higher layers, your Java Virtual Machine will hopefully be configured to minimize the permissions granted to different Java types, and then your application will add its own problem domain-specific security configuration.
+Spring Security makes this latter area - application security - much easier.
+
+Of course, you will need to properly address all security layers mentioned above, together with managerial factors that encompass every layer.
+A non-exhaustive list of such managerial factors would include security bulletin monitoring, patching, personnel vetting, audits, change control, engineering management systems, data backup, disaster recovery, performance benchmarking, load monitoring, centralised logging, incident response procedures etc.
+
+With Spring Security being focused on helping you with the enterprise application security layer, you will find that there are as many different requirements as there are business problem domains.
+A banking application has different needs from an ecommerce application.
+An ecommerce application has different needs from a corporate sales force automation tool.
+These custom requirements make application security interesting, challenging and rewarding.
+
+Please read <<getting-started>>, in its entirety to begin with.
+This will introduce you to the framework and the namespace-based configuration system with which you can get up and running quite quickly.
+To get more of an understanding of how Spring Security works, and some of the classes you might need to use, you should then read <<overall-architecture>>.
+The remaining parts of this guide are structured in a more traditional reference style, designed to be read on an as-required basis.
+We'd also recommend that you read up as much as possible on application security issues in general.
+Spring Security is not a panacea which will solve all security issues.
+It is important that the application is designed with security in mind from the start.
+Attempting to retrofit it is not a good idea.
+In particular, if you are building a web application, you should be aware of the many potential vulnerabilities such as cross-site scripting, request-forgery and session-hijacking which you should be taking into account from the start.
+The OWASP web site (http://www.
+owasp.
+org/) maintains a top ten list of web application vulnerabilities as well as a lot of useful reference information.
+
+We hope that you find this reference guide useful, and we welcome your feedback and <<jira,suggestions>>.
+
+Finally, welcome to the Spring Security <<community,community>>.
+
+include::getting-started.adoc[]
+
+include::introduction.adoc[]
+
+include::whats-new.adoc[]
+
+include::guides.adoc[]
+
+include::java-configuration.adoc[]
+
+include::namespace.adoc[]
+
+include::samples.adoc[]
+
+include::community.adoc[]