spring-security/src/docbkx/namespace-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="namespace-config" xmlns:xlink="http://www.w3.org/1999/xlink">
  <info>
    <title>Security Namespace Configuration</title>
  </info>
  <section>
    <info>
      <title>Introduction</title>
    </info>
    <para>
      Namespace configuration has been available since version 2.0 of the Spring framework. It allows you to 
      supplement the traditional Spring beans application context syntax with elements from additional XML schema. 
      You can find more information in the Spring
      <link xlink:href="http://static.springframework.org/spring/docs/2.5.x/reference/xsd-config.html">
        Reference Documentation</link>. A namespace element can be used simply to allow a more concise
      way of configuring an individual bean or, more powerfully, to define an alternative
      configuration syntax which more closely matches the problem domain and hides the underlying
      complexity from the user. A simple element may conceal the fact that multiple beans and
      processing steps are being added to the application context. For example, adding the following
      element from the security namespace to an application context will start up an embedded LDAP
      server for testing use within the application:
      <programlisting><![CDATA[ 
  <security:ldap-server />
]]></programlisting>
      This is much simpler than wiring up the equivalent Apache Directory Server beans. The most
      common alterative configuration requirements are supported by attributes on the
      <literal>ldap-server</literal> element and the user is isolated from worrying about which 
      beans they need to be set on and what the bean property names are.
      <footnote>
        <para>You can find out more about the use of the
          <literal>ldap-server</literal>
          element in the chapter on
          <link xlink:href="ldap">LDAP</link>.</para>
      </footnote>. Use of a good XML editor while editing the application context
      file should provide information on the attributes and elements that are
      available. We would recommend that you try out the 
      <link xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite</link>
      as it has special features for working with the Spring portfolio namespaces. 
    </para>
    <para>
      To start using the security namespace in your application context, all you need to do is add
      the schema declaration to your application context file:
<programlisting>
  <![CDATA[
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:security="http://www.springframework.org/schema/security"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
              http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-2.0.xsd">  
    ...
</beans>
  ]]></programlisting>
      In many of the examples you will see (and in the sample) applications, we will often use "security" as the default
      namespace rather than "beans", which means we can omit the prefix on all the security namespace elements,
      making the context easier to read. You may also want to do this if you have your application context divided up
      into separate files and have most of your security configuration in one of them. Your security application context file would then
      start like this
      <programlisting><![CDATA[
<beans:beans xmlns="http://www.springframework.org/schema/security"
   xmlns:beans="http://www.springframework.org/schema/beans">
    ...
</beans:beans>
]]></programlisting>
      We'll assume this syntax is being used from now on in this chapter.
    </para>
    <section>
      <info>
        <title>Design of the Namespace</title>
      </info>
      <para>
        The namespace is designed to capture the most common uses of the framework and provide a simplified and concise
        syntax for enabling them within an application. The design is largely based around the large-scale dependencies
        within the framework, and can be divided up into the following areas:
        <itemizedlist>
          <listitem><para><emphasis>Web/HTTP Security</emphasis> - the most complex part. Sets up the filters and 
            related service beans used to apply the framework authentication mechanisms, to secure URLs, render login and error pages and much more.</para></listitem>
          <listitem><para><emphasis>Business Object (Method) Security</emphasis> - options for securing the service layer.</para></listitem>
          <listitem><para><emphasis>AuthenticationManager</emphasis> - handles authentication requests from other parts of the framework.</para></listitem>
          <listitem><para><emphasis>AccessDecisionManager</emphasis> - provides access decisions for web and method security. A default one will be registered, but you can also
          choose to use a custom one, declared using normal Spring bean syntax.</para></listitem>
          <listitem><para><emphasis>AuthenticationProvider</emphasis>s - mechanisms against which the authentication manager authenticates users.
            The namespace provides supports for several standard options and also a means of adding custom beans declared using a traditional syntax. </para></listitem>
          <listitem><para><emphasis>UserDetailsService</emphasis> - closely related to authentication providers, but often also required by other beans.</para></listitem>
          <!-- todo: diagram and link to other sections which describe the interfaces -->
        </itemizedlist>    
      </para>
      <para>We'll see how these work together in the next section.</para>
      
    </section>
  </section>
  <section>
    <info><title>Example Configurations</title></info>
    <para>
      In this section, we'll look at how you can build up a namespace configuration to use different features of the framework.
    </para>
    
    <section>
    <info><title>A Minimal Configuration</title></info>
    <para>
      Let's assume you want to get up and running as quickly as possible and add authentication support and access control to an existing
      web application, with a few test logins. The first thing you need to do is add the follwing fiter declaration to your <literal>web.xml</literal> 
      file:
<programlisting>
<![CDATA[  
<filter>
  <filter-name>springSecurityFilterChain</filter-name>
  <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
  
<filter-mapping>
  <filter-name>springSecurityFilterChain</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>]]>   
</programlisting>      
      This provides a hook into the Spring Security web infrastructure. You can find more details of how this works in 
      <link xlink:href="#todo">TODO</link>. You're then ready to start editing your application context file.
      Web security services are configured using the <literal>&lt;http&gt;</literal> element.
      All you need to begin with is
<programlisting><![CDATA[
  <http auto-config='true'>
    <intercept-url pattern="/**" access="ROLE_USER" />
  </http>
  ]]>
</programlisting>
      Which says that we want all URLs within our application to be secured, requiring the role <literal>ROLE_USER</literal>
       to access them. To add some users, you can define a set of test data directly in the namespace:
      <programlisting><![CDATA[
  <authentication-provider>
    <user-service>
      <user name="jimi" password="jimispassword" authorities="ROLE_USER, ROLE_ADMIN" />
      <user name="bob" password="bobspassword" authorities="ROLE_USER" />
    </user-service>
  </authentication-provider>
  ]]>
      </programlisting>
      This defines two users, their passwords and their roles within the application (which will be used for access control). The
      <literal>&lt;authentication-provider&gt;</literal> element specifies that the user information will be registered with the authentication
      manager and used to process authentication requests. 
      <sidebar><para>If you are familiar with previous versions of the framework, the <literal>&lt;authentication-provider&gt;</literal>
        element creates a <literal>DaoAuthenticationProvider</literal> bean and the <literal>&lt;user-service&gt;</literal> element creates
      an <classname>InMemoryDaoImpl</classname>. A <literal>ProviderManager</literal> bean is always created by the namespace processing system
       and the <literal>AuthenticationProvider</literal> is automatically registered with it.</para></sidebar>
    </para>
    <para>
      At this point you should be able to start up your application and you will be required to log in to proceed. Try it out, or try
      experimenting with the "tutorial" sample applicaition that comes with the project.
      This configuration actually adds quite a few services to the application automatically (mainly because we have added the <literal>auto-config</literal>
      attribute. For example, form login processing and "remember-me" services are automatically enabled. You might also be wondering where the 
      login form came from when you were prompted to log in. This was also generated automatically, since we didn't explicitly configure a login page URL, but the namespace offers plenty
      of options to allow you to custmize this kind of thing.
    </para>
    </section>
  </section>
</chapter>