<?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>
        <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>
    </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>
