spring-security/src/site/apt/namespaces.apt

                                ----------------------------------------
                                     Security Namespace Configuration
                                ----------------------------------------
                                         ------------------------
                                           (2007-11-7 draft)
                                         ------------------------


Overview


* Summary

    Spring Security will make use of Spring 2.0 namespace-based configuration features to allow much more concise
    configuration. This document outlines the current state of development and the features that have been
    implemented so far and raises points for discussion. The features are still largely experimental and subject to
    change.

    The {{{http://acegisecurity.svn.sourceforge.net/svnroot/acegisecurity/spring-security/trunk/core/src/main/resources/org/springframework/security/config/}schema files}}
    can be found in the core package. For simplicity, a relax NG compact schema (the rnc file) has been used as it is
    easier to work with. This is then coverted into a W3C schema using trang.

* Design

    The initial aim is to provide a relatively small set of namespace configuration options which capture the most
    common uses of framework, especially for inexperienced users who don't require much in the way of customization.
    The focus should be mainly on providing high-level components which logically match the different aspects of
    securing an application. While it is also useful to have namespace options for simplifying the configuration of
    existing framework beans, this is a somewhat orthogonal requirement, with different target users and will be dealt
    with separately. Only the most obvious customizations will be implemented to start with. It should also be possible
    to add new features without affecting the existing design.

    Keeping these aims in mind, the design is largely based around the large-scale dependencies within the framework.
    It can be divided up into the following areas:

    * <<Web/HTTP Security>> - this is by far the largest and most complex area, consisting of

        * Filter chain proxy

        * HttpSessionContextIntegrationFilter - special filter which is of key importance.

        * The filters which are responsible for most of Spring Security's web application features.

        * ExceptionTranslationFilter and FilterSecurityInterceptor - other special filters.

        * Authentication entry point(s).

        * Concurrent session support (optional).

        * Remember-me service (optional).

    The only inward dependency here is that the AuthenticationManager must be made aware of the
    ConcurrentSessionController (if configured). Apart from this, the other areas of the framework are unaware of
    web-related functionality.

    * <<Business Object (Method) Security>> - This is currently implemented using a bean decorator within the
     business object bean, which is a relatively simple syntax.

    * <<AuthenticationManager>> - this is the main dependency of other parts of the framework. The namespace
    configuration creates an instance of ProviderManager as required and registers it under a known name. It assumes
    that this will be used by all the configured beans. This currently happens automatically. It might be worth
    introducing a

---
    <security:authentication-manager id="othername"/>
---

    element just to allow users to explicitly configure an authentication manager which they can use in other beans.
    The additional name could be registered as an alias.

    * <<AccessDecisionManager>> - The security interceptors (both for method and http security) require access to
    an access decision manager. At the moment a default one is created and used by both, but they should additionally
    support the use of an independently configured access manager, based on Id. The standard bean syntax should be
    sufficient for the moment.

    * <<AuthenticationProviders>> - these can be created individually and register themselves with the authentication
    manager. Current namespace options are limited but each provider should be pretty much self-contained and hence
    relatively simple to implement. There may be multiple providers within an application so some means of ordering will
    be required.

    * <<UserDetailsService>> - Closely related to the authentication providers, but often also required by other beans.
    Again the implementations should be relatively straightforward. There may be multiple implementations within the
    application.


* Http Security

   Probably the best starting point here is to look at the {{{http://acegisecurity.svn.sourceforge.net/svnroot/acegisecurity/spring-security/trunk/samples/tutorial/src/main/webapp/WEB-INF/applicationContext-security-ns.xml}namespace configuration file}}
   which is in use in the tutorial sample application:

+--------------------------------------------------------------------------------------------------------------------

<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">

    <security:http>
        <security:intercept-url pattern="/secure/extreme/**" access="ROLE_SUPERVISOR"/>
        <security:intercept-url pattern="/secure/**" access="IS_AUTHENTICATED_REMEMBERED" />
        <security:intercept-url pattern="/**" access="IS_AUTHENTICATED_ANONYMOUSLY" />

        <security:form-login />
        <security:http-basic realm="SpringSecurityTutorialApp"  />
        <security:logout />
        <security:concurrent-session-control maxSessions="1" exceptionIfMaximumExceeded="true"/>

        <security:remember-me tokenRepository="tokenRepo"/>
    </security:http>

    <bean name="tokenRepo" class="org.springframework.security.ui.rememberme.InMemoryTokenRepositoryImpl"/>

    <security:authentication-provider>
        <security:user-service>
            <security:user name="bob" password="bobspassword" authorities="ROLE_SUPERVISOR" />
            <security:user name="bill" password="billspassword" authorities="ROLE_A,ROLE_B" />
        </security:user-service>
    </security:authentication-provider>

</beans>

+--------------------------------------------------------------------------------------------------------------------

** \<security:http /\>

    This element groups the other http-specific elements together and has attributes which allow the
    session creation strategy to be set. It also allows you to specify the type of pattern that will be used for URL
    definitions within the block. This defaults to ``ant'' since this is what users almost always use in practice.

    The {{{./spring-security-core/xref/org/springframework/security/config/HttpSecurityBeanDefinitionParser.html}HttpSecurityBeanDefinitionParser}}
    class is responsible for handling the contents. It creates a FilterChainProxy
    instance, HttpSessionContextIntegrationFilter, FilterSecurityInterceptor and ExceptionTranslationFilter and parses
    the child intercept-url elements (see below). It then delegates to separate parsers to handle the contents of other
    child elements. These encapsulate the functionality of separate web application concerns which are implemented
    by Spring Security and will typically each create a filter and possibly one or more other beans.

    Finally a post processor (HttpSecurityConfigPostProcessor) is registered to handle things which can't be done
    until the application context has been completed. This includes assembling and ordering the filter chain
    and the strategy for selecting which authentication entry point should be used to trigger login. The core
    filters now implement Ordered and a standard ordering has been established for them. Other filters in the
    context must also implement Ordered to be considered, so it may be necessary to provide an element which can be
    used to decorate filter beans to achieve this, if the user can't (or doesn't want to) make their code implement
    Ordered explicitly.


** \<security:intercept-url /\>

    In a traditional, bean-configured setup, there are several beans which require the use of URL patterns -
    FilterChainProxy, FilterSecurityInterceptor and ChannelProcessingFilter. These can now be specified using a
    single construct and the appropriate beans created and assembled by the parser. This allows options to be combined
    in a more logical fashion without duplication. The user picks the important URLs for their application, defines the
    patterns for them and then specifies which filters should be used, what access configuration attributes
    the FilterSecurityInterceptor should enforce and if any channel restrictions apply. Only the access decision part
    has been implemented. The only option for filters is currently "none", which will omit the URL from the security
    filter chain entirely. It's not clear how or if additional filter order customization should be implemented (other
    than by allowing Ids to be set on the various child elements). Channel security should be straightforward.


* Method Security

    An example use of the \<security:intercept-methods /\> decorator is:

+-----------------------------------------------------------------------------------------------------------------------

<bean id="target" class="org.springframework.security.config.TestBusinessBeanImpl">
    <security:intercept-methods>
        <security:protect method="org.springframework.security.config.TestBusinessBean.set*" access="ROLE_ADMIN" />
        <security:protect method="org.springframework.security.config.TestBusinessBean.get*" access="ROLE_ADMIN,ROLE_USER" />
        <security:protect method="org.springframework.security.config.TestBusinessBean.doSomething" access="ROLE_USER" />
    </security:intercept-methods>
</bean>

+-----------------------------------------------------------------------------------------------------------------------

    Spring's AbstractInterceptorDrivenBeanDefinitionDecorator is used to add a MethodSecurityInterceptor to the bean.
    Ideally we would just have the method names here rather than fully-qualified names (any ideas??).


* Authentication Manager and Providers

    At least one authentication provider must be defined for things to work. No providers defined as
    beans will currently be added to the authentication manager, but this could be done with a post
    processor. Alternatively, \<security:authentication-provider /\> could be used round a bean declaration, or
    supplied with a reference to a provider bean.

* Configuration of Specific Beans

    As mentioned above, it is also useful to be able to use namespaces to simplify the configuration of existing beans,
    especially where the existing configuration is complicated. This would typically be done with bean decorators.
    An example of this is the simplification of FilterChainProxy configuration.

** FilterChainProxy Configuration

    The \<security:filter-chain-map /\> decorator sets the configuration map of paths to filter lists for FilterChainProxy. The
    syntax is similar to that described above for the HTTP security features.

+-----------------------------------------------------------------------------------------------------------------------

<bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy">
    <sec:filter-chain-map pathType="ant">
        <sec:filter-chain pattern="/foo/**" filters="mockFilter"/>
        <sec:filter-chain pattern="/some/other/path/**" filters="httpSessionFilter,mockFilter,mockFilter2"/>
        <sec:filter-chain pattern="/do/not/filter" filters="none"/>
        <sec:filter-chain pattern="/**" filters="sif,apf,mockFilter"/>
    </sec:filter-chain-map>
</bean>

+-----------------------------------------------------------------------------------------------------------------------

    This kind of functionality can be added as requested/required without having an impact on other areas, so it is of
    lower priority than the design of "higher-level" namespace components.




* LDAP Configuration Example

    As an example of what is possible in terms of reducing configuration requirements, the \<security:ldap /\>
    element is an excellent example of the use of high-level namespace components. It can be used to set up a complete
    LDAP authentication provider with or without an external server.
    The optional <<<url>>> attribute specifies the URL of an external LDAP server. Without this, it will create
    an embedded Apache Directory server instance and attempt to load any ldif files found on the classpath. Doing this
    with Spring beans would involve potentially hundreds of lines of configuration and is a difficult task for an
    inexperienced user (or indeed any user). Ultimately the user should be able to configure authentication and group
    membership strategy, server details (e.g. port number) and the structure of the directory.

    {{{http://acegisecurity.svn.sourceforge.net/svnroot/acegisecurity/spring-security/trunk/core/src/main/java/org/springframework/security/config/LdapBeanDefinitionParser.java}LdapBeanDefinitionParser}}
    does the parsing work here and there are currently no child elements.