11. Authorization

As we’ve also seen in the Technical Overview chapter, Spring Security provides interceptors which control access to secure objects such as method invocations or web requests.
A pre-invocation decision on whether the invocation is allowed to proceed is made by the AccessDecisionManager.

int vote(Authentication authentication, Object object, Collection<ConfigAttribute> attrs);

boolean supports(ConfigAttribute attribute);

boolean supports(Class clazz);

Whilst the AccessDecisionManager is called by the AbstractSecurityInterceptor before proceeding with the secure object invocation, some applications need a way of modifying the object actually returned by the secure object invocation.
Whilst you could easily implement your own AOP concern to achieve this, Spring Security provides a convenient hook that has several concrete implementations that integrate with its ACL capabilities.

Figure 11.2, “After Invocation Implementation” illustrates Spring Security’s AfterInvocationManager and its concrete implementations.

Like many other parts of Spring Security, AfterInvocationManager has a single concrete implementation, AfterInvocationProviderManager, which polls a list of AfterInvocationProvider s.
Each AfterInvocationProvider is allowed to modify the return object or throw an AccessDeniedException.
Indeed multiple providers can modify the object, as the result of the previous provider is passed to the next in the list.

Please be aware that if you’re using AfterInvocationManager, you will still need configuration attributes that allow the MethodSecurityInterceptor‘s AccessDecisionManager to allow an operation.
If you’re using the typical Spring Security included AccessDecisionManager implementations, having no configuration attributes defined for a particular secure method invocation will cause each AccessDecisionVoter to abstain from voting.
In turn, if the AccessDecisionManager property “allowIfAllAbstainDecisions” is false, an AccessDeniedException will be thrown.
You may avoid this potential issue by either (i) setting “allowIfAllAbstainDecisions” to true (although this is generally not recommended) or (ii) simply ensure that there is at least one configuration attribute that an AccessDecisionVoter will vote to grant access for.
This latter (recommended) approach is usually achieved through a ROLE_USER or ROLE_AUTHENTICATED configuration attribute.

It is a common requirement that a particular role in an application should automatically “include” other roles.
For example, in an application which has the concept of an “admin” and a “user” role, you may want an admin to be able to do everything a normal user can.
To achieve this, you can either make sure that all admin users are also assigned the “user” role.
Alternatively, you can modify every access constraint which requires the “user” role to also include the “admin” role.
This can get quite complicated if you have a lot of different roles in your application.

The use of a role-hierarchy allows you to configure which roles (or authorities) should include others.
An extended version of Spring Security’s RoleVoter, RoleHierarchyVoter, is configured with a RoleHierarchy, from which it obtains all the “reachable authorities” which the user is assigned.
A typical configuration might look like this:

<beanid="roleVoter"class="org.springframework.security.access.vote.RoleHierarchyVoter"><constructor-argref="roleHierarchy" /></bean><beanid="roleHierarchy"class="org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl"><propertyname="hierarchy"><value>
            ROLE_ADMIN > ROLE_STAFF
            ROLE_STAFF > ROLE_USER
            ROLE_USER > ROLE_GUEST
        </value></property></bean>

Here we have four roles in a hierarchy ROLE_ADMIN ⇒ ROLE_STAFF ⇒ ROLE_USER ⇒ ROLE_GUEST.
A user who is authenticated with ROLE_ADMIN, will behave as if they have all four roles when security constraints are evaluated against an AccessDecisionManager configured with the above RoleHierarchyVoter.
The > symbol can be thought of as meaning “includes”.

Role hierarchies offer a convenient means of simplifying the access-control configuration data for your application and/or reducing the number of authorities which you need to assign to a user.
For more complex requirements you may wish to define a logical mapping between the specific access-rights your application requires and the roles that are assigned to users, translating between the two when loading the user information.

The AspectJ security interceptor is very similar to the AOP Alliance security interceptor discussed in the previous section.
Indeed we will only discuss the differences in this section.

The AspectJ interceptor is named AspectJSecurityInterceptor.
Unlike the AOP Alliance security interceptor, which relies on the Spring application context to weave in the security interceptor via proxying, the AspectJSecurityInterceptor is weaved in via the AspectJ compiler.
It would not be uncommon to use both types of security interceptors in the same application, with AspectJSecurityInterceptor being used for domain object instance security and the AOP Alliance MethodSecurityInterceptor being used for services layer security.

Let’s first consider how the AspectJSecurityInterceptor is configured in the Spring application context:

<beanid="bankManagerSecurity"class=
    "org.springframework.security.access.intercept.aspectj.AspectJMethodSecurityInterceptor"><propertyname="authenticationManager"ref="authenticationManager"/><propertyname="accessDecisionManager"ref="accessDecisionManager"/><propertyname="afterInvocationManager"ref="afterInvocationManager"/><propertyname="securityMetadataSource"><sec:method-security-metadata-source><sec:protectmethod="com.mycompany.BankManager.delete*"access="ROLE_SUPERVISOR"/><sec:protectmethod="com.mycompany.BankManager.getBalance"access="ROLE_TELLER,ROLE_SUPERVISOR"/></sec:method-security-metadata-source></property></bean>

As you can see, aside from the class name, the AspectJSecurityInterceptor is exactly the same as the AOP Alliance security interceptor.
Indeed the two interceptors can share the same securityMetadataSource, as the SecurityMetadataSource works with java.lang.reflect.Method s rather than an AOP library-specific class.
Of course, your access decisions have access to the relevant AOP library-specific invocation (ie MethodInvocation or JoinPoint) and as such can consider a range of addition criteria when making access decisions (such as method arguments).

Next you’ll need to define an AspectJ aspect.
For example:

package org.springframework.security.samples.aspectj;

import org.springframework.security.access.intercept.aspectj.AspectJSecurityInterceptor;
import org.springframework.security.access.intercept.aspectj.AspectJCallback;
import org.springframework.beans.factory.InitializingBean;

public aspect DomainObjectInstanceSecurityAspect implements InitializingBean {

    private AspectJSecurityInterceptor securityInterceptor;

    pointcut domainObjectInstanceExecution(): target(PersistableEntity)
        && execution(public * *(..)) && !within(DomainObjectInstanceSecurityAspect);

    Object around(): domainObjectInstanceExecution() {
        if (this.securityInterceptor == null) {
            return proceed();
        }

        AspectJCallback callback = new AspectJCallback() {
            public Object proceedWithObject() {
                return proceed();
            }
        };

        returnthis.securityInterceptor.invoke(thisJoinPoint, callback);
    }

    public AspectJSecurityInterceptor getSecurityInterceptor() {
        return securityInterceptor;
    }

    publicvoid setSecurityInterceptor(AspectJSecurityInterceptor securityInterceptor) {
        this.securityInterceptor = securityInterceptor;
    }

    publicvoid afterPropertiesSet() throws Exception {
        if (this.securityInterceptor == null)
            thrownew IllegalArgumentException("securityInterceptor required");
        }
    }
}

In the above example, the security interceptor will be applied to every instance of PersistableEntity, which is an abstract class not shown (you can use any other class or pointcut expression you like).
For those curious, AspectJCallback is needed because the proceed(); statement has special meaning only within an around() body.
The AspectJSecurityInterceptor calls this anonymous AspectJCallback class when it wants the target object to continue.

You will need to configure Spring to load the aspect and wire it with the AspectJSecurityInterceptor.
A bean declaration which achieves this is shown below:

<beanid="domainObjectInstanceSecurityAspect"class="security.samples.aspectj.DomainObjectInstanceSecurityAspect"factory-method="aspectOf"><propertyname="securityInterceptor"ref="bankManagerSecurity"/></bean>

That’s it!
Now you can create your beans from anywhere within your application, using whatever means you think fit (eg new Person();) and they will have the security interceptor applied.

Spring Security uses Spring EL for expression support and you should look at how that works if you are interested in understanding the topic in more depth.
Expressions are evaluated with a “root object” as part of the evaluation context.
Spring Security uses specific classes for web and method security as the root object, in order to provide built-in expressions and access to values such as the current principal.

To use expressions to secure individual URLs, you would first need to set the use-expressions attribute in the <http> element to true.
Spring Security will then expect the access attributes of the <intercept-url> elements to contain Spring EL expressions.
The expressions should evaluate to a Boolean, defining whether access should be allowed or not.
For example:

<http><intercept-urlpattern="/admin*"access="hasRole('admin') and hasIpAddress('192.168.1.0/24')"/>
    ...
</http>

Here we have defined that the “admin” area of an application (defined by the URL pattern) should only be available to users who have the granted authority “admin” and whose IP address matches a local subnet.
We’ve already seen the built-in hasRole expression in the previous section.
The expression hasIpAddress is an additional built-in expression which is specific to web security.
It is defined by the WebSecurityExpressionRoot class, an instance of which is used as the expression root object when evaluation web-access expressions.
This object also directly exposed the HttpServletRequest object under the name request so you can invoke the request directly in an expression.
If expressions are being used, a WebExpressionVoter will be added to the AccessDecisionManager which is used by the namespace.
So if you aren’t using the namespace and want to use expressions, you will have to add one of these to your configuration.

Method security is a bit more complicated than a simple allow or deny rule.
Spring Security 3.0 introduced some new annotations in order to allow comprehensive support for the use of expressions.

<global-method-securitypre-post-annotations="enabled"/>

@PreAuthorize("hasRole('USER')")publicvoid create(Contact contact);

@PreAuthorize("hasPermission(#contact, 'admin')")publicvoid deletePermission(Contact contact, Sid recipient, Permission permission);

@PreAuthorize("#contact.name == authentication.name")publicvoid doSomething(Contact contact);

boolean hasPermission(Authentication authentication, Object targetDomainObject,
                            Object permission);

boolean hasPermission(Authentication authentication, Serializable targetId,
                            String targetType, Object permission);

<security:global-method-securitypre-post-annotations="enabled"><security:expression-handlerref="expressionHandler"/></security:global-method-security><beanid="expressionHandler"class=
"org.springframework.security.access.expression.method.DefaultMethodSecurityExpressionHandler"><propertyname="permissionEvaluator"ref="myPermissionEvaluator"/></bean>

Complex applications often will find the need to define access permissions not simply at a web request or method invocation level.
Instead, security decisions need to comprise both who (Authentication), where (MethodInvocation) and what (SomeDomainObject).
In other words, authorization decisions also need to consider the actual domain object instance subject of a method invocation.

Imagine you’re designing an application for a pet clinic.
There will be two main groups of users of your Spring-based application: staff of the pet clinic, as well as the pet clinic’s customers.
The staff will have access to all of the data, whilst your customers will only be able to see their own customer records.
To make it a little more interesting, your customers can allow other users to see their customer records, such as their “puppy preschool” mentor or president of their local “Pony Club”.
Using Spring Security as the foundation, you have several approaches that can be used:

Each one of these approaches is perfectly legitimate.
However, the first couples your authorization checking to your business code.
The main problems with this include the enhanced difficulty of unit testing and the fact it would be more difficult to reuse the Customer authorization logic elsewhere.
Obtaining the GrantedAuthority[] s from the Authentication object is also fine, but will not scale to large numbers of Customer s.
If a user might be able to access 5,000 Customer s (unlikely in this case, but imagine if it were a popular vet for a large Pony Club!) the amount of memory consumed and time required to construct the Authentication object would be undesirable.
The final method, opening the Customer directly from external code, is probably the best of the three.
It achieves separation of concerns, and doesn’t misuse memory or CPU cycles, but it is still inefficient in that both the AccessDecisionVoter and the eventual business method itself will perform a call to the DAO responsible for retrieving the Customer object.
Two accesses per method invocation is clearly undesirable.
In addition, with every approach listed you’ll need to write your own access control list (ACL) persistence and business logic from scratch.

Fortunately, there is another alternative, which we’ll talk about below.

Spring Security’s ACL services are shipped in the spring-security-acl-xxx.jar.
You will need to add this JAR to your classpath to use Spring Security’s domain object instance security capabilities.

Spring Security’s domain object instance security capabilities centre on the concept of an access control list (ACL).
Every domain object instance in your system has its own ACL, and the ACL records details of who can and can’t work with that domain object.
With this in mind, Spring Security delivers three main ACL-related capabilities to your application:

As indicated by the first bullet point, one of the main capabilities of the Spring Security ACL module is providing a high-performance way of retrieving ACLs.
This ACL repository capability is extremely important, because every domain object instance in your system might have several access control entries, and each ACL might inherit from other ACLs in a tree-like structure (this is supported out-of-the-box by Spring Security, and is very commonly used).
Spring Security’s ACL capability has been carefully designed to provide high performance retrieval of ACLs, together with pluggable caching, deadlock-minimizing database updates, independence from ORM frameworks (we use JDBC directly), proper encapsulation, and transparent database updating.

Given databases are central to the operation of the ACL module, let’s explore the four main tables used by default in the implementation.
The tables are presented below in order of size in a typical Spring Security ACL deployment, with the table with the most rows listed last:

As mentioned in the last paragraph, the ACL system uses integer bit masking.
Don’t worry, you need not be aware of the finer points of bit shifting to use the ACL system, but suffice to say that we have 32 bits we can switch on or off.
Each of these bits represents a permission, and by default the permissions are read (bit 0), write (bit 1), create (bit 2), delete (bit 3) and administer (bit 4).
It’s easy to implement your own Permission instance if you wish to use other permissions, and the remainder of the ACL framework will operate without knowledge of your extensions.

It is important to understand that the number of domain objects in your system has absolutely no bearing on the fact we’ve chosen to use integer bit masking.
Whilst you have 32 bits available for permissions, you could have billions of domain object instances (which will mean billions of rows in ACL_OBJECT_IDENTITY and quite probably ACL_ENTRY).
We make this point because we’ve found sometimes people mistakenly believe they need a bit for each potential domain object, which is not the case.

Now that we’ve provided a basic overview of what the ACL system does, and what it looks like at a table structure, let’s explore the key interfaces.
The key interfaces are:

Please note that our out-of-the-box AclService and related database classes all use ANSI SQL.
This should therefore work with all major databases.
At the time of writing, the system had been successfully tested using Hypersonic SQL, PostgreSQL, Microsoft SQL Server and Oracle.

Two samples ship with Spring Security that demonstrate the ACL module.
The first is the Contacts Sample, and the other is the Document Management System (DMS) Sample.
We suggest taking a look over these for examples.

To get starting using Spring Security’s ACL capability, you will need to store your ACL information somewhere.
This necessitates the instantiation of a DataSource using Spring.
The DataSource is then injected into a JdbcMutableAclService and BasicLookupStrategy instance.
The latter provides high-performance ACL retrieval capabilities, and the former provides mutator capabilities.
Refer to one of the samples that ship with Spring Security for an example configuration.
You’ll also need to populate the database with the four ACL-specific tables listed in the last section (refer to the ACL samples for the appropriate SQL statements).

Once you’ve created the required schema and instantiated JdbcMutableAclService, you’ll next need to ensure your domain model supports interoperability with the Spring Security ACL package.
Hopefully ObjectIdentityImpl will prove sufficient, as it provides a large number of ways in which it can be used.
Most people will have domain objects that contain a public Serializable getId() method.
If the return type is long, or compatible with long (eg an int), you will find you need not give further consideration to ObjectIdentity issues.
Many parts of the ACL module rely on long identifiers.
If you’re not using long (or an int, byte etc), there is a very good chance you’ll need to reimplement a number of classes.
We do not intend to support non-long identifiers in Spring Security’s ACL module, as longs are already compatible with all database sequences, the most common identifier data type, and are of sufficient length to accommodate all common usage scenarios.

The following fragment of code shows how to create an Acl, or modify an existing Acl:

ObjectIdentity oi = new ObjectIdentityImpl(Foo.class, new Long(44));
Sid sid = new PrincipalSid("Samantha");
Permission p = BasePermission.ADMINISTRATION;


MutableAcl acl = null;
try {
acl = (MutableAcl) aclService.readAclById(oi);
} catch (NotFoundException nfe) {
acl = aclService.createAcl(oi);
}


acl.insertAce(acl.getEntries().length, p, sid, true);
aclService.updateAcl(acl);

In the example above, we’re retrieving the ACL associated with the “Foo” domain object with identifier number 44.
We’re then adding an ACE so that a principal named “Samantha” can “administer” the object.
The code fragment is relatively self-explanatory, except the insertAce method.
The first argument to the insertAce method is determining at what position in the Acl the new entry will be inserted.
In the example above, we’re just putting the new ACE at the end of the existing ACEs.
The final argument is a Boolean indicating whether the ACE is granting or denying.
Most of the time it will be granting (true), but if it is denying (false), the permissions are effectively being blocked.

Spring Security does not provide any special integration to automatically create, update or delete ACLs as part of your DAO or repository operations.
Instead, you will need to write code like shown above for your individual domain objects.
It’s worth considering using AOP on your services layer to automatically integrate the ACL information with your services layer operations.
We’ve found this quite an effective approach in the past.

Once you’ve used the above techniques to store some ACL information in the database, the next step is to actually use the ACL information as part of authorization decision logic.
You have a number of choices here.
You could write your own AccessDecisionVoter or AfterInvocationProvider that respectively fires before or after a method invocation.
Such classes would use AclService to retrieve the relevant ACL and then call Acl.isGranted(Permission[] permission, Sid[] sids, boolean administrativeMode) to decide whether permission is granted or denied.
Alternately, you could use our AclEntryVoter, AclEntryAfterInvocationProvider or AclEntryAfterInvocationCollectionFilteringProvider classes.
All of these classes provide a declarative-based approach to evaluating ACL information at runtime, freeing you from needing to write any code.
Please refer to the sample applications to learn how to use these classes.