spring-security/docs/manual/src/docbook/introduction.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="introduction" xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>Introduction</title>
    <section xml:id="what-is-acegi-security">
        <title>What is Spring Security?</title>
        <para>Spring Security provides comprehensive security services for J2EE-based enterprise
            software applications. There is a particular emphasis on supporting projects built using
            The Spring Framework, which is the leading J2EE solution for enterprise software
            development. If you're not using Spring for developing enterprise applications, we
            warmly encourage you to take a closer look at it. Some familiarity with Spring - and in
            particular dependency injection principles - will help you get up to speed with Spring
            Security more easily.</para>
        <para>People use Spring Security for many reasons, but most are drawn to the project after
            finding the security features of J2EE's Servlet Specification or EJB Specification lack
            the depth required for typical enterprise application scenarios. Whilst mentioning these
            standards, it's important to recognise that they are not portable at a WAR or EAR level.
            Therefore, if you switch server environments, it is typically a lot of work to
            reconfigure your application's security in the new target environment. Using Spring
            Security overcomes these problems, and also brings you dozens of other useful,
            customisable security features.</para>
        <para>As you probably know two major areas of application security are
            <quote>authentication</quote> and <quote>authorization</quote> (or
            <quote>access-control</quote>). These are the two main areas that Spring Security
            targets. <quote>Authentication</quote> is the process of establishing a principal is who
            they claim to be (a <quote>principal</quote> generally means a user, device or some
            other system which can perform an action in your application).
            <quote>Authorization</quote> refers to the process of deciding whether a principal is
            allowed to perform an action within your application. To arrive at the point where an
            authorization decision is needed, the identity of the principal has already been
            established by the authentication process. These concepts are common, and not at all
            specific to Spring Security. </para>
        <para>At an authentication level, Spring Security supports a wide range of authentication
            models. Most of these authentication models are either provided by third parties, or are
            developed by relevant standards bodies such as the Internet Engineering Task Force. In
            addition, Spring Security provides its own set of authentication features. Specifically,
            Spring Security currently supports authentication integration with all of these
            technologies:</para>
        <itemizedlist spacing="compact">
            <listitem>
                <para>HTTP BASIC authentication headers (an IETF RFC-based standard)</para>
            </listitem>
            <listitem>
                <para>HTTP Digest authentication headers (an IETF RFC-based standard)</para>
            </listitem>
            <listitem>
                <para>HTTP X.509 client certificate exchange (an IETF RFC-based standard)</para>
            </listitem>
            <listitem>
                <para>LDAP (a very common approach to cross-platform authentication needs,
                    especially in large environments)</para>
            </listitem>
            <listitem>
                <para>Form-based authentication (for simple user interface needs)</para>
            </listitem>
            <listitem>
                <para>OpenID authentication</para>
            </listitem>
            <listitem>
                <para>Authentication based on pre-established request headers (such as Computer
                    Associates Siteminder)</para>
            </listitem>
            <listitem>
                <para>JA-SIG Central Authentication Service (otherwise known as CAS, which is a
                    popular open source single sign-on system)</para>
            </listitem>
            <listitem>
                <para>Transparent authentication context propagation for Remote Method Invocation
                    (RMI) and HttpInvoker (a Spring remoting protocol)</para>
            </listitem>
            <listitem>
                <para>Automatic "remember-me" authentication (so you can tick a box to avoid
                    re-authentication for a predetermined period of time)</para>
            </listitem>
            <listitem>
                <para>Anonymous authentication (allowing every unauthenticated call to automatically assume a
                    particular security identity)</para>
            </listitem>
            <listitem>
                <para>Run-as authentication (which is useful if one call should proceed with a
                    different security identity)</para>
            </listitem>
            <listitem>
                <para>Java Authentication and Authorization Service (JAAS)</para>
            </listitem>
            <listitem>
                <para>JEE container autentication (so you can still use Container Managed
                    Authentication if desired)</para>
            </listitem>
            <listitem>
                <para>Kerberos</para>
            </listitem>
            <listitem>
                <para>Java Open Source Single Sign On (JOSSO) *</para>
            </listitem>
            <listitem>
                <para>OpenNMS Network Management Platform *</para>
            </listitem>
            <listitem>
                <para>AppFuse *</para>
            </listitem>
            <listitem>
                <para>AndroMDA *</para>
            </listitem>
            <listitem>
                <para>Mule ESB *</para>
            </listitem>
            <listitem>
                <para>Direct Web Request (DWR) *</para>
            </listitem>
            <listitem>
                <para>Grails *</para>
            </listitem>
            <listitem>
                <para>Tapestry *</para>
            </listitem>
            <listitem>
                <para>JTrac *</para>
            </listitem>
            <listitem>
                <para>Jasypt *</para>
            </listitem>
            <listitem>
                <para>Roller *</para>
            </listitem>
            <listitem>
                <para>Elastic Path *</para>
            </listitem>
            <listitem>
                <para>Atlassian Crowd *</para>
            </listitem>
            <listitem>
                <para>Your own authentication systems (see below)</para>
            </listitem>
        </itemizedlist>
        <para>(* Denotes provided by a third party</para>
        <!-- TODO: Reinstate web link to third-party integrations/users -->
        <para>Many independent software vendors (ISVs) adopt Spring Security because of this
            significant choice of flexible authentication models. Doing so allows them to quickly
            integrate their solutions with whatever their end clients need, without undertaking a
            lot of engineering or requiring the client to change their environment. If none of the
            above authentication mechanisms suit your needs, Spring Security is an open platform and
            it is quite simple to write your own authentication mechanism. Many corporate users of
            Spring Security need to integrate with "legacy" systems that don't follow any particular
            security standards, and Spring Security is happy to "play nicely" with such
            systems.</para>
        <para>Irrespective of the authentication mechanism, Spring Security provides a deep set
            of authorization capabilities. There are three main areas of interest 
            - authorizing web requests, authorizing whether methods can be
            invoked, and authorizing access to individual domain object instances. To help you
            understand the differences, consider the authorization capabilities found in the Servlet
            Specification web pattern security, EJB Container Managed Security and file system
            security respectively. Spring Security provides deep capabilities in all of these
            important areas, which we'll explore later in this reference guide.</para>
    </section>
    <section xml:id="history">
        <title>History</title>
        <para>Spring Security began in late 2003 as <quote>The Acegi Security System for
            Spring</quote>. A question was posed on the Spring Developers' mailing list asking
            whether there had been any consideration given to a Spring-based security
            implementation. At the time the Spring community was relatively small (especially
            compared with the size today!), and indeed Spring itself had only existed as a
            SourceForge project from early 2003. The response to the question was that it was a
            worthwhile area, although a lack of time currently prevented its exploration.</para>
        <para>With that in mind, a simple security implementation was built and not released. A few
            weeks later another member of the Spring community inquired about security, and at the
            time this code was offered to them. Several other requests followed, and by January 2004
            around twenty people were using the code. These pioneering users were joined by others
            who suggested a SourceForge project was in order, which was duly established in March
            2004.</para>
        <para>In those early days, the project didn't have any of its own authentication modules.
            Container Managed Security was relied upon for the authentication process, with Acegi
            Security instead focusing on authorization. This was suitable at first, but as more and
            more users requested additional container support, the fundamental limitation of
            container-specific authentication realm interfaces became clear. There was also a
            related issue of adding new JARs to the container's classpath, which was a common source
            of end user confusion and misconfiguration.</para>
        <para>Acegi Security-specific authentication services were subsequently introduced. Around a
            year later, Acegi Security became an official Spring Framework subproject. The 1.0.0
            final release was published in May 2006 - after more than two and a half years of active
            use in numerous production software projects and many hundreds of improvements and
            community contributions.</para>
        <para>Acegi Security became an official Spring Portfolio project towards the end of 2007 and
            was rebranded as <quote>Spring Security</quote>.</para>
        <para>Today Spring Security enjoys a strong and active open source community. There are
            thousands of messages about Spring Security on the support forums. There is an active
            core of developers who work on the code itself and an active community which also
            regularly share patches and support their peers.</para>
    </section>
    <section xml:id="release-numbering">
        <title>Release Numbering</title>
        <para>It is useful to understand how Spring Security release numbers work, as it will help
            you identify the effort (or lack thereof) involved in migrating to future releases of
            the project. Each release uses a standard triplet of integers: MAJOR.MINOR.PATCH. The
            intent is that MAJOR versions are incompatible, large-scale upgrades of the API. MINOR
            versions should largely retain source and binary compatibility with older minor
            versions, thought there may be some design changes and incompatible udates. PATCH level
            should be perfectly compatible, forwards and backwards, with the possible exception of
            changes which are to fix bugs and defects.</para>
        <para>The extent to which you are affected by changes will depend on how tightly integrated
            your code is. If you are doing a lot of customization you are more likely to be affected
            than if you are using a simple namespace configuration.</para>
        <para>You should always test your application thoroughly before rolling out a new
            version.</para>
    </section>
    <section xml:id="get-spring-security">
        <title>Getting Spring Security</title>
        <para>You can get hold of Spring Security in several ways. You can download a packaged
            distribution from the main Spring <link
            xlink:href="http://www.springsource.com/download/community?project=Spring%20Security"
            >download page</link>, download individual jars (and sample WAR files) from the Maven
            Central repository (or a SpringSource Maven repository for snapshot and milestone
            releases) or, alternatively, you can build the project from source yourself. See the
            project web site for more details. </para>
        <section xml:id="modules">
            <title>Project Modules</title>
            <para>In Spring Security 3.0, the codebase has been sub-divided into separate jars which
                more clearly separate different functionaltiy areas and third-party dependencies. If
                you are using Maven to build your project, then these are the modules you will add
                to your <filename>pom.xml</filename>. Even if you're not using Maven, we'd recommend
                that you consult the <filename>pom.xml</filename> files to get an idea of
                third-party dependencies and versions. Alternatively, a good idea is to examine the
                libraries that are included in the sample applications.</para>
            <section xml:id="spring-security-core">
                <title>Core - <literal>spring-security-core.jar</literal></title>
                <para>Contains core authentication and access-contol classes and interfaces,
                    remoting support and basic provisioning APIs. Required by any application which
                    uses Spring Security. Supports standalone applications, remote clients, method
                    (service layer) security and JDBC user provisioning. Contains the top-level packages:<itemizedlist>
                    <listitem>
                        <para><literal>org.springframework.security.core</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>org.springframework.security.access</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>org.springframework.security.authentication</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>org.springframework.security.provisioning</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>org.springframework.security.remoting</literal></para>
                    </listitem>
                    </itemizedlist></para>
            </section>
            <section xml:id="spring-security-web">
                <title>Web - <literal>spring-security-web.jar</literal></title>
                <para>Contains filters and related web-security infrastructure code. Anything with a
                    servlet API dependency. You'll need it if you require Spring Security web
                    authentication services and URL-based access-control. The main package is
                    <literal>org.springframework.security.web</literal>.</para>
            </section>
            <section xml:id="spring-security-config">
                <title>Config - <literal>spring-security-config.jar</literal></title>
                <para>Contains the security namespace parsing code. You need it if you are using the
                    Spring Security XML namespace for configuration. The main package is
                    <literal>org.springframework.security.config</literal>. None of the
                    classes are intended for direct use in an application.</para>
            </section>
            <section xml:id="spring-security-ldap">
                <title>LDAP - <literal>spring-security-ldap.jar</literal></title>
                <para>LDAP authentication and provisioning code. Required if you need to use LDAP
                    authentication or manage LDAP user entries. The top-level package is
                    <literal>org.springframework.security.ldap</literal>.</para>
            </section>
            <section xml:id="spring-security-acl">
                <title>ACL - <literal>spring-security-acl.jar</literal></title>
                <para>Specialized domain object ACL implementation. Used to apply security to
                    specific domain object instances within your application. The top-level package
                    is <literal>org.springframework.security.acls</literal>.</para>
            </section>
            <section xml:id="spring-security-cas">
                <title>CAS - <literal>spring-security-cas-client.jar</literal></title>
                <para>Spring Security's CAS client integration. If you want to use Spring Security
                    web authentication with a CAS single sign-on server. The top-level package is
                    <literal>org.springframework.security.cas</literal>.</para>
            </section>
            <section xml:id="spring-security-openid">
                <title>OpenID - <literal>spring-security-openid.jar</literal></title>
                <para>OpenID web authentication support. Used to authenticate users against an
                    external OpenID server. <literal>org.springframework.security.openid</literal>.
                    Requires OpenID4Java.</para>
            </section>
            <section xml:id="spring-security-crypto">
                <title>Crypto - <literal>spring-security-crypto.jar</literal></title>
                <para>Contains cryptography utility functions which are used by other
                    Spring projects. <literal>org.springframework.security.crypto</literal>.
                </para>
            </section>
        </section>
        <section xml:id="get-source">
            <title>Checking out the Source</title>
            <para> Since Spring Security is an Open Source project, we'd strongly encourage you to
                check out the source code using git. This will give you full access to all the
                sample applications and you can build the most up to date version of the project
                easily. Having the source for a project is also a huge help in debugging. Exception
                stack traces are no longer obscure black-box issues but you can get straight to the
                line that's causing the problem and work out what's happening. The source is the
                ultimate documentation for a project and often the simplest place to find out how
                something actually works. </para>
            <para>To obtain the source for the project, use the following git command:
                <programlisting language="txt">
  git clone git://git.springsource.org/spring-security/spring-security.git
    </programlisting>
            </para>
            <para>This will give you access to the entire project history (including all releases
            and branches) on your local machine.</para>
        </section>
    </section>
</chapter>