spring-security/docs/manual/src/docbook/namespace-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ns-config"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <info>
    <title>Security Namespace Configuration</title>
  </info>
  <section>
    <title>Introduction</title>
    <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.springsource.org/spring/docs/3.0.x/spring-framework-reference/htmlsingle/spring-framework-reference.htm"
        > 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 language="xml"><![CDATA[
  <security:ldap-server />
]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server
      beans. The most common alternative 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 create 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 standard Spring namespaces. </para>
    <para> To start using the security namespace in your application context, you first need to make
        sure that the <literal>spring-security-config</literal> jar is on your classpath. Then all you need to do is
      add the schema declaration to your application context file: <programlisting language="xml">
  <![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-3.0.xsd
          http://www.springframework.org/schema/security
          http://www.springframework.org/schema/security/spring-security-3.0.3.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 content 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 language="xml"><![CDATA[
<beans:beans xmlns="http://www.springframework.org/schema/security"
  xmlns:beans="http://www.springframework.org/schema/beans"
  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-3.0.xsd
           http://www.springframework.org/schema/security
           http://www.springframework.org/schema/security/spring-security-3.0.3.xsd">
    ...
</beans:beans>
]]></programlisting> We'll assume this syntax is being used from now on in this chapter. </para>
    <section>
      <title>Design of the Namespace</title>
      <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 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 to configure these in the following sections.</para>
    </section>
  </section>
  <section xml:id="ns-getting-started">
    <title>Getting Started with Security Namespace Configuration</title>
    <para> In this section, we'll look at how you can build up a namespace configuration to use some
      of the main features of the framework. Let's assume you initially 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. Then we'll look at how to change over to authenticating
      against a database or other security repository. In later sections we'll introduce more
      advanced namespace configuration options. </para>
    <section xml:id="ns-web-xml">
      <title><literal>web.xml</literal> Configuration</title>
      <para> The first thing you need to do is add the following filter declaration to your
          <literal>web.xml</literal> file: <programlisting language="xml"><![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. <classname>DelegatingFilterProxy</classname> is a Spring Framework class
        which delegates to a filter implementation which is defined as a Spring bean in your
        application context. In this case, the bean is named
          <quote>springSecurityFilterChain</quote>, which is an internal infrastructure bean created
        by the namespace to handle web security. Note that you should not use this bean name
        yourself. Once you've added this to your <filename>web.xml</filename>, you're ready to start
        editing your application context file. Web security services are configured using the
          <literal>&lt;http&gt;</literal> element. </para>
    </section>
    <section xml:id="ns-minimal">
      <title>A Minimal <literal>&lt;http&gt;</literal> Configuration</title>
      <para> All you need to enable web security to begin with is <programlisting language="xml"><![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. The
          <literal>&lt;http></literal> element is the parent for all web-related namespace
        functionality. The <literal>&lt;intercept-url></literal> element defines a
          <literal>pattern</literal> which is matched against the URLs of incoming requests using an
        ant path style syntax<footnote>
          <para>See the section on <link xlink:href="#request-matching">Request
              Matching</link> in the Web Application Infrastructure chapter for more details
              on how matches are actually performed.</para>
          </footnote>. The <literal>access</literal> attribute defines the access
        requirements for requests matching the given pattern. With the default configuration, this
        is typically a comma-separated list of roles, one of which a user must have to be allowed to
        make the request. The prefix <quote>ROLE_</quote> is a marker which indicates that a simple
        comparison with the user's authorities should be made. In other words, a normal role-based
        check should be used. Access-control in Spring Security is not limited to the use of simple
        roles (hence the use of the prefix to differentiate between different types of security
        attributes). We'll see later how the interpretation can vary<footnote><para>The
            interpretation of the comma-separated values in the <literal>access</literal> attribute
            depends on the implementation of the <link xlink:href="#ns-access-manager"
              >AccessDecisionManager</link> which is used. In Spring Security 3.0, the attribute can
            also be populated with an <link xlink:href="#el-access">EL
          expression</link>.</para></footnote>.</para>
      <note>
        <para>You can use multiple <literal>&lt;intercept-url&gt;</literal> elements to define
          different access requirements for different sets of URLs, but they will be evaluated in
          the order listed and the first match will be used. So you must put the most specific
          matches at the top. You can also add a <literal>method</literal> attribute to limit the
          match to a particular HTTP method (<literal>GET</literal>, <literal>POST</literal>,
            <literal>PUT</literal> etc.). If a request matches multiple patterns, the
          method-specific match will take precedence regardless of ordering.</para>
      </note>
      <para> To add some users, you can define a set of test data directly in the namespace: <programlisting language="xml"><![CDATA[
  <authentication-manager>
    <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>
  </authentication-manager>
  ]]>
        </programlisting></para>
      <sidebar>
        <para>If you are familiar with pre-namespace versions of the framework, you can probably
          already guess roughly what's going on here. The <literal>&lt;http&gt;</literal> element is
          responsible for creating a <classname>FilterChainProxy</classname> and the filter beans
          which it uses. Common problems like incorrect filter ordering are no longer an issue as
          the filter positions are predefined.</para>
        <para>The <literal>&lt;authentication-provider&gt;</literal> element creates a
            <classname>DaoAuthenticationProvider</classname> bean and the
            <literal>&lt;user-service&gt;</literal> element creates an
            <classname>InMemoryDaoImpl</classname>. All <literal>authentication-provider</literal>
          elements must be children of the <literal>&lt;authentication-manager></literal> element,
          which creates a <classname>ProviderManager</classname> and registers the authentication
          providers with it. You can find more detailed information on the beans that are created in
          the <link xlink:href="#appendix-namespace">namespace appendix</link>. It's worth
          cross-checking this if you want to start understanding what the important classes in the
          framework are and how they are used, particularly if you want to customise things
          later.</para>
      </sidebar>
      <para> The configuration above defines two users, their passwords and their roles within the
        application (which will be used for access control). It is also possible to load user
        information from a standard properties file using the <literal>properties</literal>
        attribute on <literal>user-service</literal>. See the section on <link
          xlink:href="#core-services-in-memory-service">in-memory authentication</link> for more
        details on the file format. Using the <literal>&lt;authentication-provider&gt;</literal>
        element means that the user information will be used by the authentication manager to
        process authentication requests. You can have multiple
          <literal>&lt;authentication-provider&gt;</literal> elements to define different
        authentication sources and each will be consulted in turn.</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 <quote>tutorial</quote>
        sample application that comes with the project. The above configuration actually adds quite
        a few services to the application because we have used the <literal>auto-config</literal>
        attribute. For example, form-based login processing is automatically enabled. </para>
      <section xml:id="ns-auto-config">
        <title>What does <literal>auto-config</literal> Include?</title>
        <para> The <literal>auto-config</literal> attribute, as we have used it above, is just a
          shorthand syntax for: <programlisting language="xml"><![CDATA[
  <http>
    <form-login />
    <http-basic />
    <logout />
  </http>
  ]]></programlisting> These other elements are responsible for setting up form-login, basic
          authentication and logout handling services respectively <footnote><para>In versions prior
              to 3.0, this list also included remember-me functionality. This could cause some
              confusing errors with some configurations and was removed in 3.0. In 3.0, the addition
              of an <classname>AnonymousAuthenticationFilter</classname> is part of the default
                <literal>&lt;http></literal> configuration, so the <literal>&lt;anonymous
                /></literal> element is added regardless of whether <literal>auto-config</literal>
              is enabled.</para></footnote> . They each have attributes which can be used to alter
          their behaviour. </para>
      </section>
      <section xml:id="ns-form-and-basic">
        <title>Form and Basic Login Options</title>
        <para> You might be wondering where the login form came from when you were prompted to log
          in, since we made no mention of any HTML files or JSPs. In fact, since we didn't
          explicitly set a URL for the login page, Spring Security generates one automatically,
          based on the features that are enabled and using standard values for the URL which
          processes the submitted login, the default target URL the user will be sent to after
          loggin in and so on. However, the namespace offers plenty of support to allow you to
          customize these options. For example, if you want to supply your own login page, you could
          use: <programlisting language="xml"><![CDATA[
  <http auto-config='true'>
    <intercept-url pattern="/login.jsp*" access="IS_AUTHENTICATED_ANONYMOUSLY"/>
    <intercept-url pattern="/**" access="ROLE_USER" />
    <form-login login-page='/login.jsp'/>
  </http>
  ]]>
        </programlisting> Note that you can still use <literal>auto-config</literal>. The
            <literal>form-login</literal> element just overrides the default settings. Also note
          that we've added an extra <literal>intercept-url</literal> element to say that any
          requests for the login page should be available to anonymous users <footnote><para>See the
              chapter on <link xlink:href="#anonymous">anonymous authentication</link> and also the
                <link xlink:href="#authz-authenticated-voter">AuthenticatedVoter</link> class for
              more details on how the value <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal> is
              processed.</para></footnote>. Otherwise the request would be matched by the pattern
            <literal>/**</literal> and it wouldn't be possible to access the login page itself! This
          is a common configuration error and will result in an infinite loop in the application.
          Spring Security will emit a warning in the log if your login page appears to be secured.
          It is also possible to have all requests matching a particular pattern bypass the security
          filter chain completely: <programlisting language="xml"><![CDATA[
  <http auto-config='true'>
    <intercept-url pattern="/css/**" filters="none"/>
    <intercept-url pattern="/login.jsp*" filters="none"/>
    <intercept-url pattern="/**" access="ROLE_USER" />
    <form-login login-page='/login.jsp'/>
  </http>
  ]]>
          </programlisting>It's important to realise that these requests will be completely
          oblivious to any further Spring Security web-related configuration or additional
          attributes such as <literal>requires-channel</literal>, so you will not be able to access
          information on the current user or call secured methods during the request. Use
            <literal>access='IS_AUTHENTICATED_ANONYMOUSLY'</literal> as an alternative if you still
          want the security filter chain to be applied.
          <note>
              <para>Using <literal>filters="none"</literal> operates by creating an empty filter
                        chain in Spring Security's <classname>FilterChainProxy</classname>, whereas
                        the access attributes are used to configure the
                        <classname>FilterSecurityInterceptor</classname> in the single filter chain
                        which is created by the namespace configuration. The two are applied
                        independently, so if you have an access contraint for a sub-pattern of a
                        pattern which has a <literal>filters="none"</literal> attribute, the access
                        constraint will be ignored, even if it is listed first. It isn't possible to
                        apply a <literal>filters="none"</literal> attribute to the pattern
                        <literal>/**</literal> since this is used by the namespace filter chain. In
                        version 3.1 things are more flexible. You can define multiple filter chains
                        and the <literal>filters</literal> attribute is no longer supported.</para>
          </note>
        </para>
        <para>If you want to use basic authentication instead of form login, then change the
          configuration to <programlisting language="xml"><![CDATA[
  <http auto-config='true'>
    <intercept-url pattern="/**" access="ROLE_USER" />
    <http-basic />
  </http>
  ]]>
        </programlisting> Basic authentication will then take precedence and will be used to
          prompt for a login when a user attempts to access a protected resource. Form login is
          still available in this configuration if you wish to use it, for example through a login
          form embedded in another web page. </para>
        <section xml:id="ns-form-target">
          <title>Setting a Default Post-Login Destination</title>
          <para> If a form login isn't prompted by an attempt to access a protected resource, the
              <literal>default-target-url</literal> option comes into play. This is the URL the user
            will be taken to after logging in, and defaults to "/". You can also configure things so
            that they user <emphasis>always</emphasis> ends up at this page (regardless of whether
            the login was "on-demand" or they explicitly chose to log in) by setting the
              <literal>always-use-default-target</literal> attribute to "true". This is useful if
            your application always requires that the user starts at a "home" page, for example: <programlisting language="xml"><![CDATA[
  <http>
    <intercept-url pattern='/login.htm*' filters='none'/>
    <intercept-url pattern='/**' access='ROLE_USER' />
    <form-login login-page='/login.htm' default-target-url='/home.htm'
            always-use-default-target='true' />
  </http>
  ]]>
            </programlisting></para>
        </section>
      </section>
    </section>
    <section xml:id="ns-auth-providers">
      <title>Using other Authentication Providers</title>
      <para> In practice you will need a more scalable source of user information than a few names
        added to the application context file. Most likely you will want to store your user
        information in something like a database or an LDAP server. LDAP namespace configuration is
        dealt with in the <link xlink:href="#ldap">LDAP chapter</link>, so we won't cover it here.
        If you have a custom implementation of Spring Security's
          <classname>UserDetailsService</classname>, called "myUserDetailsService" in your
        application context, then you can authenticate against this using <programlisting language="xml"><![CDATA[
  <authentication-manager>
    <authentication-provider user-service-ref='myUserDetailsService'/>
  </authentication-manager>
  ]]>
        </programlisting> If you want to use a database, then you can use <programlisting language="xml"><![CDATA[
  <authentication-manager>
    <authentication-provider>
      <jdbc-user-service data-source-ref="securityDataSource"/>
    </authentication-provider>
  </authentication-manager>
  ]]>
        </programlisting> Where <quote>securityDataSource</quote> is the name of a
          <classname>DataSource</classname> bean in the application context, pointing at a database
        containing the standard Spring Security <link xlink:href="#db_schema_users_authorities">user
          data tables</link>. Alternatively, you could configure a Spring Security
          <classname>JdbcDaoImpl</classname> bean and point at that using the
          <literal>user-service-ref</literal> attribute: <programlisting language="xml"><![CDATA[
  <authentication-manager>
    <authentication-provider user-service-ref='myUserDetailsService'/>
  </authentication-manager>

  <beans:bean id="myUserDetailsService"
      class="org.springframework.security.core.userdetails.jdbc.JdbcDaoImpl">
    <beans:property name="dataSource" ref="dataSource"/>
  </beans:bean>
  ]]>
        </programlisting> You can also use standard
          <interfacename>AuthenticationProvider</interfacename> beans as follows <programlisting language="xml"><![CDATA[
  <authentication-manager>
    <authentication-provider ref='myAuthenticationProvider'/>
  </authentication-manager>
  ]]>
        </programlisting> where <literal>myAuthenticationProvider</literal> is the name of a
        bean in your application context which implements
          <interfacename>AuthenticationProvider</interfacename>. You can use multiple
          <literal>authentication-provider</literal> elements, in which case they will be checked
        in the order they are declared when attempting to authenticated a user. See <xref
          linkend="ns-auth-manager"/> for more on information on how the Spring Security
          <interfacename>AuthenticationManager</interfacename> is configured using the namespace. </para>
      <section xml:id="ns-password-encoder">
        <title>Adding a Password Encoder</title>
        <para> Often your password data will be encoded using a hashing algorithm. This is supported
          by the <literal>&lt;password-encoder&gt;</literal> element. With SHA encoded passwords,
          the original authentication provider configuration would look like this: <programlisting language="xml"><![CDATA[
<authentication-manager>
  <authentication-provider>
    <password-encoder hash="sha"/>
    <user-service>
      <user name="jimi" password="d7e6351eaa13189a5a3641bab846c8e8c69ba39f"
            authorities="ROLE_USER, ROLE_ADMIN" />
      <user name="bob" password="4e7421b1b8765d8f9406d87e7cc6aa784c4ab97f"
            authorities="ROLE_USER" />
    </user-service>
  </authentication-provider>
</authentication-manager>
  ]]>
          </programlisting></para>
        <para> When using hashed passwords, it's also a good idea to use a salt value to protect
          against dictionary attacks and Spring Security supports this too. Ideally you would want
          to use a randomly generated salt value for each user, but you can use any property of the
            <classname>UserDetails</classname> object which is loaded by your
            <classname>UserDetailsService</classname>. For example, to use the
            <literal>username</literal> property, you would use <programlisting><![CDATA[
  <password-encoder hash="sha">
    <salt-source user-property="username"/>
  </password-encoder>
    ]]></programlisting> You can use a custom password encoder bean by using the
            <literal>ref</literal> attribute of <literal>password-encoder</literal>. This should
          contain the name of a bean in the application context which is an instance of Spring
          Security's <interfacename>PasswordEncoder</interfacename> interface. </para>
      </section>
    </section>
  </section>
  <section xml:id="ns-web-advanced">
    <title>Advanced Web Features</title>
    <section xml:id="ns-remember-me">
      <title>Remember-Me Authentication</title>
      <para>See the separate <link xlink:href="#remember-me">Remember-Me chapter</link> for
        information on remember-me namespace configuration.</para>
    </section>
    <section xml:id="ns-requires-channel">
      <title>Adding HTTP/HTTPS Channel Security</title>
      <para>If your application supports both HTTP and HTTPS, and you require that particular URLs
        can only be accessed over HTTPS, then this is directly supported using the
          <literal>requires-channel</literal> attribute on <literal>&lt;intercept-url&gt;</literal>: <programlisting language="xml"><![CDATA[
  <http>
    <intercept-url pattern="/secure/**" access="ROLE_USER" requires-channel="https"/>
    <intercept-url pattern="/**" access="ROLE_USER" requires-channel="any"/>
    ...
  </http>]]>
        </programlisting>With this configuration in place, if a user attempts to access
        anything matching the "/secure/**" pattern using HTTP, they will first be redirected to an
        HTTPS URL. The available options are "http", "https" or "any". Using the value "any" means
        that either HTTP or HTTPS can be used. </para>
      <para>If your application uses non-standard ports for HTTP and/or HTTPS, you can specify a
        list of port mappings as follows: <programlisting><![CDATA[
  <http>
    ...
    <port-mappings>
      <port-mapping http="9080" https="9443"/>
    </port-mappings>
  </http>]]>
        </programlisting><!--You can find a more in-depth discussion of channel security
        in <xref xlink:href="#channel-security"/--></para>
    </section>
    <section xml:id="ns-session-mgmt">
      <title>Session Management</title>
      <section>
        <title>Detecting Timeouts</title>
        <para> You can configure Spring Security to detect the submission of an invalid session ID
          and redirect the user to an appropriate URL. This is achieved through the
            <literal>session-management</literal> element: <programlisting language="xml"><![CDATA[
  <http>
    ...
    <session-management invalid-session-url="/sessionTimeout.htm" />
  </http>]]></programlisting></para>
      </section>
      <section xml:id="ns-concurrent-sessions">
        <title>Concurrent Session Control</title>
        <para>If you wish to place constraints on a single user's ability to log in to your
          application, Spring Security supports this out of the box with the following simple
          additions. First you need to add the following listener to your
            <filename>web.xml</filename> file to keep Spring Security updated about session
          lifecycle events: <programlisting language="xml"><![CDATA[
  <listener>
    <listener-class>
      org.springframework.security.web.session.HttpSessionEventPublisher
    </listener-class>
  </listener>
]]></programlisting> Then add the following lines to your application context: <programlisting language="xml"><![CDATA[
  <http>
    ...
    <session-management>
        <concurrency-control max-sessions="1" />
    </session-management>
  </http>]]>
        </programlisting> This will prevent a user from logging in multiple times - a
          second login will cause the first to be invalidated. Often you would prefer to prevent a
          second login, in which case you can use <programlisting language="xml"><![CDATA[
  <http>
    ...
    <session-management>
        <concurrency-control max-sessions="1" error-if-maximum-exceeded="true" />
    </session-management>
  </http>]]>
        </programlisting>The second login will then be rejected. By
            <quote>rejected</quote>, we mean that the user will be sent to the
            <literal>authentication-failure-url</literal> if form-based login is being used. If the
          second authentication takes place through another non-interactive mechanism, such as
            <quote>remember-me</quote>, an <quote>unauthorized</quote> (402) error will be sent to
          the client. If instead you want to use an error page, you can add the attribute
            <literal>session-authentication-error-url</literal> to the
            <literal>session-management</literal> element. </para>
        <para>If you are using a customized authentication filter for form-based login, then you
          have to configure concurrent session control support explicitly. More details can be found
          in the <link xlink:href="#session-mgmt">Session Management chapter</link>. </para>
      </section>
      <section xml:id="ns-session-fixation">
        <title>Session Fixation Attack Protection</title>
        <para>
          <link xlink:href="http://en.wikipedia.org/wiki/Session_fixation">Session fixation</link>
          attacks are a potential risk where it is possible for a malicious attacker to create a
          session by accessing a site, then persuade another user to log in with the same session
          (by sending them a link containing the session identifier as a parameter, for example).
          Spring Security protects against this automatically by creating a new session when a user
          logs in. If you don't require this protection, or it conflicts with some other
          requirement, you can control the behaviour using the
            <literal>session-fixation-protection</literal> attribute on
            <literal>&lt;session-management&gt;</literal>, which has three options
                  <itemizedlist><listitem><para><literal>migrateSession</literal> - creates a new
                session and copies the existing session attributes to the new session. This is the
                default.</para></listitem><listitem><para><literal>none</literal> - Don't do
                anything. The original session will be
                  retained.</para></listitem><listitem><para><literal>newSession</literal> - Create
                a new "clean" session, without copying the existing session
            data.</para></listitem></itemizedlist></para>
      </section>
    </section>
    <section xml:id="ns-openid">
      <title>OpenID Support</title>
      <para>The namespace supports <link xlink:href="http://openid.net/">OpenID</link> login either
        instead of, or in addition to normal form-based login, with a simple change: <programlisting language="xml"><![CDATA[
  <http>
    <intercept-url pattern="/**" access="ROLE_USER" />
    <openid-login />
  </http>
]]></programlisting>You should then register yourself with an OpenID provider (such as
        myopenid.com), and add the user information to your in-memory
          <literal>&lt;user-service&gt;</literal> : <programlisting language="xml"><![CDATA[
  <user name="http://jimi.hendrix.myopenid.com/" authorities="ROLE_USER" />
]]></programlisting> You should be able to login using the <literal>myopenid.com</literal> site to
        authenticate. It is also possible to select a specific
          <interfacename>UserDetailsService</interfacename> bean for use OpenID by setting the
          <literal>user-service-ref</literal> attribute on the <literal>openid-login</literal>
        element. See the previous section on <link xlink:href="#ns-auth-providers">authentication
          providers</link> for more information. Note that we have omitted the password attribute
        from the above user configuration, since this set of user data is only being used to load
        the authorities for the user. A random password will be generate internally, preventing you
        from accidentally using this user data as an authentication source elsewhere in your
        configuration.</para>
      <section>
        <title>Attribute Exchange</title>
        <para>Support for OpenID <link
            xlink:href="http://openid.net/specs/openid-attribute-exchange-1_0.html">attribute
            exchange</link>. As an example, the following configuration would attempt to retrieve
          the email and full name from the OpenID provider, for use by the application:<programlisting language="xml"><![CDATA[
  <openid-login>
    <attribute-exchange>
      <openid-attribute name="email" type="http://axschema.org/contact/email" required="true" />
      <openid-attribute name="name" type="http://axschema.org/namePerson" />
    </attribute-exchange>
  </openid-login>]]></programlisting>The <quote>type</quote> of each OpenID attribute is a URI,
          determined by a particular schema, in this case <link xlink:href="http://axschema.org/"
            >http://axschema.org/</link>. If an attribute must be retrieved for successful
          authentication, the <literal>required</literal> attribute can be set. The exact schema and
          attributes supported will depend on your OpenID provider. The attribute values are
          returned as part of the authentication process and can be accessed afterwards using the
          following
          code:<programlisting language="java">OpenIDAuthenticationToken token = (OpenIDAuthenticationToken)SecurityContextHolder.getContext().getAuthentication();
List&lt;OpenIDAttribute> attributes = token.getAttributes();</programlisting>The
            <classname>OpenIDAttribute</classname> contains the attribute type and the retrieved
          value (or values in the case of multi-valued attributes). We'll see more about how the
            <classname>SecurityContextHolder</classname> class is used when we look at core Spring
          Security components in the <link xlink:href="#core-components">technical overview</link>
          chapter.</para>
      </section>
    </section>
    <section xml:id="ns-custom-filters">
      <title>Adding in Your Own Filters</title>
      <para>If you've used Spring Security before, you'll know that the framework maintains a chain
        of filters in order to apply its services. You may want to add your own filters to the stack
        at particular locations or use a Spring Security filter for which there isn't currently a
        namespace configuration option (CAS, for example). Or you might want to use a customized
        version of a standard namespace filter, such as the
          <literal>UsernamePasswordAuthenticationFilter</literal> which is created by the
          <literal>&lt;form-login&gt;</literal> element, taking advantage of some of the extra
        configuration options which are available by using the bean explicitly. How can you do this
        with namespace configuration, since the filter chain is not directly exposed? </para>
      <para>The order of the filters is always strictly enforced when using the namespace. When the
        application context is being created, the filter beans are sorted by the namespace handling
        code and the standard Spring Security filters each have an alias in the namespace and a
        well-known position.<note><para>In previous versions, the sorting took place after the
            filter instances had been created, during post-processing of the application context. In
            version 3.0+ the sorting is now done at the bean metadata level, before the classes have
            been instantiated. This has implications for how you add your own filters to the stack
            as the entire filter list must be known during the parsing of the
              <literal>&lt;http></literal> element, so the syntax has changed slightly in
            3.0.</para></note>The filters, aliases and namespace elements/attributes which create
        the filters are shown in <xref linkend="filter-stack"/>. The filters are listed in the order
        in which they occur in the filter chain. <table xml:id="filter-stack"><title>Standard Filter
            Aliases and Ordering</title><tgroup cols="3" align="left"><thead><row><entry
                  align="center">Alias</entry><entry align="center">Filter Class</entry><entry
                  align="center">Namespace Element or
                  Attribute</entry></row></thead><tbody><row><entry>
                    CHANNEL_FILTER</entry><entry><literal>ChannelProcessingFilter</literal></entry><entry><literal>http/intercept-url@requires-channel</literal></entry></row><row><entry>
                  CONCURRENT_SESSION_FILTER</entry><entry><literal>ConcurrentSessionFilter</literal>
                </entry><entry><literal>session-management/concurrency-control</literal></entry></row><row><entry>
                  SECURITY_CONTEXT_FILTER</entry><entry><classname>SecurityContextPersistenceFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry>
                  LOGOUT_FILTER
                    </entry><entry><literal>LogoutFilter</literal></entry><entry><literal>http/logout</literal></entry></row><row><entry>
                  X509_FILTER
                    </entry><entry><literal>X509AuthenticationFilter</literal></entry><entry><literal>http/x509</literal></entry></row><row><entry>
                  PRE_AUTH_FILTER
                    </entry><entry><literal>AstractPreAuthenticatedProcessingFilter</literal>
                  Subclasses</entry><entry>N/A</entry></row><row><entry> CAS_FILTER
                    </entry><entry><literal>CasAuthenticationFilter</literal></entry><entry>N/A</entry></row><row><entry>
                  FORM_LOGIN_FILTER
                    </entry><entry><literal>UsernamePasswordAuthenticationFilter</literal></entry><entry><literal>http/form-login</literal></entry></row><row><entry>
                  BASIC_AUTH_FILTER
                  </entry><entry><literal>BasicAuthenticationFilter</literal></entry><entry><literal>http/http-basic</literal></entry></row><row><entry>
                  SERVLET_API_SUPPORT_FILTER</entry><entry><literal>SecurityContextHolderAwareFilter</literal></entry><entry><literal>http/@servlet-api-provision</literal></entry></row><row><entry>
                  REMEMBER_ME_FILTER
                    </entry><entry><classname>RememberMeAuthenticationFilter</classname></entry><entry><literal>http/remember-me</literal></entry></row><row><entry>
                  ANONYMOUS_FILTER
                  </entry><entry><literal>AnonymousAuthenticationFilter</literal></entry><entry><literal>http/anonymous</literal></entry></row><row><entry>
                  SESSION_MANAGEMENT_FILTER</entry><entry><literal>SessionManagementFilter</literal></entry><entry><literal>session-management</literal></entry></row><row><entry>EXCEPTION_TRANSLATION_FILTER
                    </entry><entry><classname>ExceptionTranslationFilter</classname></entry><entry><literal>http</literal></entry></row><row><entry>
                  FILTER_SECURITY_INTERCEPTOR
                    </entry><entry><classname>FilterSecurityInterceptor</classname></entry><entry><literal>http</literal></entry></row><row><entry>
                  SWITCH_USER_FILTER
                  </entry><entry><literal>SwitchUserFilter</literal></entry><entry>N/A</entry></row></tbody></tgroup></table>
        You can add your own filter to the stack, using the <literal>custom-filter</literal> element
        and one of these names to specify the position your filter should appear at: <programlisting language="xml"><![CDATA[
  <http>
     <custom-filter position="FORM_LOGIN_FILTER" ref="myFilter" />
  </http>

  <beans:bean id="myFilter" class="com.mycompany.MySpecialAuthenticationFilter"/>
  ]]>
  </programlisting> You can also use the <literal>after</literal> or <literal>before</literal>
        attributes if you want your filter to be inserted before or after another filter in the
        stack. The names "FIRST" and "LAST" can be used with the <literal>position</literal>
        attribute to indicate that you want your filter to appear before or after the entire stack,
        respectively. </para>
      <tip>
        <title>Avoiding filter position conflicts</title>
        <para> If you are inserting a custom filter which may occupy the same position as one of the
          standard filters created by the namespace then it's important that you don't include the
          namespace versions by mistake. Avoid using the <literal>auto-config</literal> attribute
          and remove any elements which create filters whose functionality you want to replace. </para>
        <para> Note that you can't replace filters which are created by the use of the
            <literal>&lt;http&gt;</literal> element itself -
            <classname>SecurityContextPersistenceFilter</classname>,
            <classname>ExceptionTranslationFilter</classname> or
            <classname>FilterSecurityInterceptor</classname>. </para>
      </tip>
      <para> If you're replacing a namespace filter which requires an authentication entry point
        (i.e. where the authentication process is triggered by an attempt by an unauthenticated user
        to access to a secured resource), you will need to add a custom entry point bean too. </para>
      <section xml:id="ns-entry-point-ref">
        <title>Setting a Custom <interfacename>AuthenticationEntryPoint</interfacename></title>
        <para> If you aren't using form login, OpenID or basic authentication through the namespace,
          you may want to define an authentication filter and entry point using a traditional bean
          syntax and link them into the namespace, as we've just seen. The corresponding
            <interfacename>AuthenticationEntryPoint</interfacename> can be set using the
            <literal>entry-point-ref</literal> attribute on the <literal>&lt;http&gt;</literal>
          element. </para>
        <para> The CAS sample application is a good example of the use of custom beans with the
          namespace, including this syntax. If you aren't familiar with authentication entry points,
          they are discussed in the <link xlink:href="#tech-intro-auth-entry-point">technical
            overview</link> chapter. </para>
      </section>
    </section>
  </section>
  <section xml:id="ns-method-security">
    <title>Method Security</title>
    <para>From version 2.0 onwards Spring Security has improved support substantially for adding
      security to your service layer methods. It provides support for JSR-250 annotation security as
      well as the framework's original <literal>@Secured</literal> annotation. From 3.0 you can also
      make use of new <link xlink:href="#el-access">expression-based annotations</link>. You can
      apply security to a single bean, using the <literal>intercept-methods</literal> element to
      decorate the bean declaration, or you can secure multiple beans across the entire service
      layer using the AspectJ style pointcuts. </para>
    <section xml:id="ns-global-method">
      <title>The <literal>&lt;global-method-security&gt;</literal> Element</title>
      <para> This element is used to enable annotation-based security in your application (by
        setting the appropriate attributes on the element), and also to group together security
        pointcut declarations which will be applied across your entire application context. You
        should only declare one <literal>&lt;global-method-security&gt;</literal> element. The
        following declaration would enable support for Spring Security's
        <literal>@Secured</literal>: <programlisting><![CDATA[
  <global-method-security secured-annotations="enabled" />
  ]]>
</programlisting> Adding an annotation to a method (on an class or interface) would then limit
        the access to that method accordingly. Spring Security's native annotation support defines a
        set of attributes for the method. These will be passed to the
          <interfacename>AccessDecisionManager</interfacename> for it to make the actual decision:
        <programlisting language="java">
  public interface BankService {

    @Secured("IS_AUTHENTICATED_ANONYMOUSLY")
    public Account readAccount(Long id);

    @Secured("IS_AUTHENTICATED_ANONYMOUSLY")
    public Account[] findAccounts();

    @Secured("ROLE_TELLER")
    public Account post(Account account, double amount);
  }
</programlisting>Support
        for JSR-250 annotations can be enabled using <programlisting><![CDATA[
  <global-method-security jsr250-annotations="enabled" />
  ]]>
        </programlisting>These are standards-based and allow simple role-based constraints to be
        applied but do not have the power Spring Security's native annotations.
        To use the new expression-based syntax, you would use
<programlisting><![CDATA[
  <global-method-security pre-post-annotations="enabled" />
  ]]></programlisting>and the equivalent Java code would
        be<programlisting language="java">
   public interface BankService {

     @PreAuthorize("isAnonymous()")
     public Account readAccount(Long id);

     @PreAuthorize("isAnonymous()")
     public Account[] findAccounts();

     @PreAuthorize("hasAuthority('ROLE_TELLER')")
     public Account post(Account account, double amount);
   }
        </programlisting>Expression-based
        annotations are a good choice if you need to define simple rules that go beyond checking the
        role names against the user's list of authorities. You can enable more than one type of
        annotation in the same application, but you should avoid mixing annotations types in the
        same interface or class to avoid confusion.</para>
      <section xml:id="ns-protect-pointcut">
        <title>Adding Security Pointcuts using <literal>protect-pointcut</literal></title>
        <para> The use of <literal>protect-pointcut</literal> is particularly powerful, as it allows
          you to apply security to many beans with only a simple declaration. Consider the following
          example: <programlisting language="xml"><![CDATA[
  <global-method-security>
    <protect-pointcut expression="execution(* com.mycompany.*Service.*(..))"
         access="ROLE_USER"/>
  </global-method-security>
]]>
          </programlisting> This will protect all methods on beans declared in the application
          context whose classes are in the <literal>com.mycompany</literal> package and whose class
          names end in "Service". Only users with the <literal>ROLE_USER</literal> role will be able
          to invoke these methods. As with URL matching, the most specific matches must come first
          in the list of pointcuts, as the first matching expression will be used. </para>
      </section>
    </section>
  </section>
  <section xml:id="ns-access-manager">
    <title>The Default AccessDecisionManager</title>
    <para> This section assumes you have some knowledge of the underlying architecture for
      access-control within Spring Security. If you don't you can skip it and come back to it later,
      as this section is only really relevant for people who need to do some customization in order
      to use more than simple role-based security. </para>
    <para> When you use a namespace configuration, a default instance of
        <interfacename>AccessDecisionManager</interfacename> is automatically registered for you and
      will be used for making access decisions for method invocations and web URL access, based on
      the access attributes you specify in your <literal>intercept-url</literal> and
        <literal>protect-pointcut</literal> declarations (and in annotations if you are using
      annotation secured methods). </para>
    <para> The default strategy is to use an <classname>AffirmativeBased</classname>
      <interfacename>AccessDecisionManager</interfacename> with a <classname>RoleVoter</classname>
      and an <classname>AuthenticatedVoter</classname>. You can find out more about these in the
      chapter on <link xlink:href="authorization">authorization</link>.</para>
    <section xml:id="ns-custom-access-mgr">
      <title>Customizing the AccessDecisionManager</title>
      <para> If you need to use a more complicated access control strategy then it is easy to set an
        alternative for both method and web security. </para>
      <para> For method security, you do this by setting the
          <literal>access-decision-manager-ref</literal> attribute on
          <literal>global-method-security</literal> to the Id of the appropriate
          <interfacename>AccessDecisionManager</interfacename> bean in the application context: <programlisting language="xml"><![CDATA[
  <global-method-security access-decision-manager-ref="myAccessDecisionManagerBean">
    ...
  </global-method-security>
  ]]></programlisting></para>
      <para> The syntax for web security is the same, but on the <literal>http</literal> element: <programlisting language="xml"><![CDATA[
  <http access-decision-manager-ref="myAccessDecisionManagerBean">
    ...
  </http>
  ]]></programlisting></para>
    </section>
  </section>
  <section xml:id="ns-auth-manager">
    <title>The Authentication Manager and the Namespace</title>
    <para> The main interface which provides authentication services in Spring Security is the
        <interfacename>AuthenticationManager</interfacename>. This is usually an instance of Spring
      Security's <classname>ProviderManager</classname> class, which you may already be familiar
      with if you've used the framework before. If not, it will be covered later, in the <link
        xlink:href="#tech-intro-authentication">technical overview chapter</link>. The bean instance
      is registered using the <literal>authentication-manager</literal> namespace element. You can't
      use a custom <classname>AuthenticationManager</classname> if you are using either HTTP or
      method security through the namespace, but this should not be a problem as you have full
      control over the <classname>AuthenticationProvider</classname>s that are used.</para>
    <para> You may want to register additional <classname>AuthenticationProvider</classname> beans
      with the <classname>ProviderManager</classname> and you can do this using the
        <literal>&lt;authentication-provider&gt;</literal> element with the <literal>ref</literal>
      attribute, where the value of the attribute is the name of the provider bean you want to add.
      For example: <programlisting language="xml"><![CDATA[
  <authentication-manager>
    <authentication-provider ref="casAuthenticationProvider"/>
  </authentication-manager>

  <bean id="casAuthenticationProvider"
      class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
    ...
  </bean>
  ]]></programlisting></para>
    <para> Another common requirement is that another bean in the context may require a reference to
      the <interfacename>AuthenticationManager</interfacename>. You can easily register an alias for
      the <interfacename>AuthenticationManager</interfacename> and use this name elsewhere in your
      application context. <programlisting language="xml"><![CDATA[
  <security:authentication-manager alias="authenticationManager">
     ...
  </security:authentication-manager>

  <bean id="customizedFormLoginFilter"
        class="com.somecompany.security.web.CustomFormLoginFilter">
     <property name="authenticationManager" ref="authenticationManager"/>
     ...
  </bean>
  ]]></programlisting></para>
  </section>
</chapter>