<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xml:id="spring-security-reference-guide" xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
    <info>
        <title>Spring Security</title>
        <subtitle>Reference Documentation</subtitle>
        <authorgroup>
            <author>
                <personname>Ben Alex</personname>
            </author>
            <author>
                <personname>Luke Taylor</personname>
            </author>
        </authorgroup>
        <productname>Spring Security</productname>
        <releaseinfo>${version}</releaseinfo>
    </info>
    <toc/>
    <preface xml:id="preface">
        <title>Preface</title>
        <partintro>
            <para>Spring Security provides a comprehensive security solution for J2EE-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.</para>
            <para>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. </para>
            <para>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.</para>
            <para>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. </para>
            <para>Please read <xref linkend="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 <xref linkend="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. </para>
            <para>We hope that you find this reference guide useful, and we welcome your feedback and
                    <link xlink:href="#jira">suggestions</link>. </para>
            <para>Finally, welcome to the Spring Security <link xlink:href="#community"
                >community</link>. </para>
        </partintro>
    </preface>
    <part xml:id="getting-started">
        <title>Getting Started</title>
        <partintro>
            <para>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 3.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. </para>
            <para> 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 <link
                    xlink:href="http://static.springsource.org/spring-security/site/index.html"
                    >project website</link> as it has useful information on building the project,
                plus links to articles, videos and tutorials. </para>
        </partintro>
        <xi:include href="introduction.xml"/>
        <xi:include href="new-3-1.xml"/>
        <xi:include href="namespace-config.xml"/>
        <xi:include href="samples.xml"/>
        <xi:include href="community.xml"/>
    </part>
    <part xml:id="overall-architecture">
        <title>Architecture and Implementation</title>
        <partintro>
            <para>Once you are familiar with setting up and running some namespace-configuration
                based applications, you may wish to develop more of an understanding of how the
                framework actually works behind the namespace facade. Like most software, Spring
                Security has certain central interfaces, classes and conceptual abstractions that
                are commonly used throughout the framework. In this part of the reference guide we
                will look at some of these and see how they work together to support authentication
                and access-control within Spring Security.</para>
        </partintro>
        <xi:include href="technical-overview.xml"/>
        <xi:include href="core-services.xml"/>
    </part>
    <part xml:id="web-app-security">
        <title>Web Application Security</title>
        <partintro>
            <para> Most Spring Security users will be using the framework in applications which make
                user of HTTP and the Servlet API. In this part, we'll take a look at how Spring
                Security provides authentication and access-control features for the web layer of an
                application. We'll look behind the facade of the namespace and see which classes and
                interfaces are actually assembled to provide web-layer security. In some situations
                it is necessary to use traditional bean configuration to provide full control over
                the configuration, so we'll also see how to configure these classes directly without
                the namespace.</para>
        </partintro>
        <xi:include href="security-filter-chain.xml"/>
        <xi:include href="core-filters.xml"/>
        <xi:include href="basic-and-digest-auth.xml"/>
        <xi:include href="remember-me-authentication.xml"/>
        <xi:include href="session-mgmt.xml"/>
        <xi:include href="anon-auth-provider.xml"/>
    </part>

    <part xml:id="authorization">
        <title>Authorization</title>
        <partintro>
            <para>The advanced authorization capabilities within Spring Security represent one of
                the most compelling reasons for its popularity. Irrespective of how you choose to
                authenticate - whether using a Spring Security-provided mechanism and provider, or
                integrating with a container or other non-Spring Security authentication authority -
                you will find the authorization services can be used within your application in a
                consistent and simple way.</para>
            <para>In this part we'll explore the different
                    <classname>AbstractSecurityInterceptor</classname> implementations, which were
                introduced in Part I. We then move on to explore how to fine-tune authorization
                through use of domain access control lists.</para>
        </partintro>
        <xi:include href="authorization-common.xml"/>
        <xi:include href="secured-objects.xml"/>
        <xi:include href="el-access.xml"/>
    </part>
    <part xml:id="advanced-topics">
        <title>Additional Topics</title>
        <!--
      Essentially standalone features which do not have to follow on directly from earlier chapters
    -->
        <partintro>
            <para> In this part we cover features which require a knowledge of previous chapters as
                well as some of the more advanced and less-commonly used features of the
                framework.</para>
        </partintro>
        <xi:include href="domain-acls.xml"/>
        <xi:include href="preauth.xml"/>
        <xi:include href="ldap-auth-provider.xml"/>
        <xi:include href="taglibs.xml"/>
        <xi:include href="jaas-auth-provider.xml"/>
        <xi:include href="cas-auth-provider.xml"/>
        <xi:include href="x509-auth-provider.xml"/>
        <xi:include href="runas-auth-provider.xml"/>
        <xi:include href="crypto.xml"/>
    </part>
    <xi:include href="appendix-db-schema.xml"/>
    <xi:include href="appendix-namespace.xml"/>
    <xi:include href="appendix-dependencies.xml"/>
</book>
