When trouble-shooting security issues it's often useful to confirm who the user is and what, if any, additional information is associated with that user. Previously this was possible (to a limited extent) by starting a client in debug mode and viewing the page source, which would contain information about the user in a comment at the bottom of the page. But as of Weave 2.6.5 there's also a link that will return all the available information about the user in a single response, that link is If the user is not logged in the page should indicate that the user is an anonymous user but will still provide some additional details, such as their IP address. If the user is logged in it will show their username and roles along with the other details. This can be particularly useful to verify that the roles that are associated with a user are the same as the role names that are being used in an ACL, or that the IP address being returned for a user is actually the users IP address and not something else, for example the IP address of a reverse proxy. |
The front line for security in Weave is Acegi security (now Spring Security). Acegi security system is a formidable, easy-to-use alternative to writing custom security code for Java enterprise applications. Weave utilises the plugin nature of the Acegi to provide a highly customisable authentication mechanism while minimising the amount of security-specific code.
Starting with Weave version 2.5, a newer version of Acegi security, known as Spring Security is supported (at the time of this writing, Spring Security version 3.2). For more information on Spring security configuration, refer Spring Security. |
Authentication and authorisation are multi-stage processes. Firstly the user must be identified. By default they are an "anonymous" user, but this can be changed by users going to the login page (either directly themselves or being forced to by Weave) or by enabling Windows integrated authentication (which uses their Windows login username). Third-party authentication systems can be configured for this purpose via an Acegi security plugin.
Secondly, we need to determine what Roles the user has, again this can be done a number of ways, one of which is going to Active Directory (AD) and determining what AD Groups the user is a member of. In fact, any user attribute that's associated with a user in AD can be used to determine their role but group membership is the most common.
Thus, determining a user's identity and their roles occur outside of Weave and is handled by Acegi security.
Specifics of Windows authentication are covered here
Once a user is authenticated and their roles are known, Weave Access Control Lists (ACLs) come in to play. ACLs provide a way of attaching an access decision to an object.
E.g. a) for object A: users with ROLE_X will be denied access but users with ROLE_Y will be allowed
b) for object B: anonymous users and users with ROLE_X will be denied access but everyone else will be allowed access
As well as roles, a user's userid can also be used in an ACL when a specific users need to be targeted, either to remove access or grant it.
Refer to the section on Access Control List for more information.
The following sections describe details about how Acegi security works internally.
Acegi security system uses security filters to provide authentication and authorisation services to enterprise applications.
The framework offers several types of filters that you can configure according to your application requirements.
You can configure security filters for the following tasks:
As this list suggests, Acegi filters allow you to do almost anything you might require to secure enterprise applications.
This section introduces Acegi's components; next, you will learn how the framework uses inversion of control (IOC) and XML configuration files to combine components and express their dependencies.
Acegi consists of four main types of component: filters, managers, providers, and handlers.
Filters - These mostly high-level components provide common security services like authentication processing, session handling, and logout. Filters are only a high-level abstraction of security-related functionality: managers and providers are used to actually implement authentication processing and logout services.
Managers - Managers manage lower-level security services offered by different providers.
Providers - A variety of providers are available to communicate with different types of data storage services, such as directory services, relational databases, or simple in-memory objects. This means you can store your user base and access control policies in any of these data storage services and Acegi's managers will select appropriate providers at run time.
Handlers - Tasks are sometimes broken up into multiple steps with each step performed by a specific handler. For example, Acegi's logout filter uses two handlers to sign out an HTTP client. One handler invalidates a user's HTTP session and another handler destroys the user's cookie. Having multiple handlers provides flexibility when configuring Acegi to work according to your application requirements. You can select the handlers of your choice to execute the steps required to secure your application.
Acegi's components are dependent on each other to secure enterprise applications.
For example, an authentication processing filter requires an authentication manager to select an appropriate authentication provider. This means you must be able to express and manage the dependency of Acegi's components.
An IOC implementation is commonly used to manage the dependencies of Java components. IOC offers two important features:
Acegi uses the popular open-source IOC implementation that comes with the Spring framework (see Resources) to manage its components. Spring uses an XML configuration file to express the dependency of components, similar to the following:
<beans> <bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy"> <property name="filterInvocationDefinitionSource"> <value> value here </value> </property> </bean> <bean id="authenticationProcessingFilter" class="org.acegisecurity.ui.webapp.AuthenticationProcessingFitler"> <property name="authenticationManager" ref="authManager"/> <!-- Other properties --> </bean> <bean id="authManager" class="org.acegisecurity.providers.ProviderManager"> <property name="providers"> <!-- List of providers here --> </property> </bean> <!-- Other bean tags --> </beans> |
As you can see, the Spring XML configuration file used by Acegi contains a single <beans> tag that wraps a number of other <bean> tags. All Acegi components (that is, filters, managers, providers, etc.) are actually JavaBeans. Each <bean> tag in the XML configuration file represents a Spring security component.
The first thing you will note is that each <bean> tag has a class attribute that identifies the class that the component uses. The <bean> tag also has an id attribute that identifies the instance (Java object) acting as a Acegi component.
For instance, the first <bean> tag of the above example identifies a component instance named filterChainProxy which is an instance of a class named org.acegisecurity.util.FilterChainProxy.
The dependency of a bean is expressed using child tags of the <bean> tag. For example, notice the <property> child tag of the first <bean> tag. The <property> child tag defines values or other beans on which the <bean> tag depends.
So in the example, the <property> child tag of the first <bean> tag has a name attribute and a <value> child tag, which respectively define the name and value of the property on which the bean depends. Likewise, the second and third <bean> tags of the example define that a filter bean depends on a manager bean. The second <bean> tag represents the filter bean and the third <bean> tag represents the manager bean.
The <bean> tag for the filter contains a <property> child tag with two attributes, name and ref.
The name attribute defines a property of the filter bean and the ref attribute refers to the instance (name) of the manager bean.
The next section shows you how to configure Acegi filters in an XML configuration file.
As previously mentioned, Acegi uses security filters to provide authentication and authorisation services to enterprise applications. You can use and configure various types of filters according to your application requirements. The following sections introduce the five most important Acegi filters.
Acegi's Session Integration Filter (SIF) is normally the first filter you will configure.
SIF creates a security context object, which is a placeholder for security-related information.
Other Acegi filters save security information in the security context and also use the information available in the security context.
SIF creates the security context and calls other filters in the filter chain.
Other filters then retrieve the security context and make changes to it.
For example, the Authentication Processing Filter (which is discussed next) stores user information such as username, password, and e-mail address in the security context.
When all the filters have finished processing, SIF checks the security context for updates.
If any filter has made changes to the security context, SIF saves the changes into a server-side session object. If no changes are found in the security context, SIF discards it.
SIF is configured in the XML configuration file as follows:
<bean id="httpSessionContextIntegrationFilter" class="org.acegisecurity.context.HttpSessionContextIntegrationFilter"/> |
Acegi uses the Authentication Processing Filter (APF) for authentication.
APF uses an authentication (or login) form, in which a user enters a username and password and triggers authentication.
APF performs all back-end authentication processing tasks such as extracting the username and password from the client request, reading the user's parameters from the back-end user base, and using the information to authenticate the user.
When you configure APF, you must provide the following parameters:
APF fetches the username, password and other information from the user's request object. It then passes this information to the authentication manager. The authentication manager uses an appropriate provider to read detailed user information (such as username, password, e-mail address and the user's access rights or privileges) from the back-end user base, authenticates the user, and stores the information in an Authentication object.
Finally, APF saves the Authentication object in the security context created earlier by SIF.
The Authentication object stored in the security context will be used later to make authorization decisions.
Configure APF as shown in the following example:
<bean id="authenticationProcessingFilter" class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilter"> <property name="authenticationManager" ref="authenticationManager" /> <property name="filterProcessesUrl" value="/j_acegi_security_check" /> <property name="defaultTargetUrl" value="/protected/protected1.jsp" /> <property name="authenticationFailureUrl" value="/login.jsp?login_error=1" /> </bean> |
You can see from this code that APF depends on the four parameters discussed in "The Big Four".
Each parameter is configured as a <property> tag in the example.
Acegi uses a Logout Processing Filer (LPF) to manage logout processing. LPF operates when a logout request comes from a client. It identifies the logout request from the URL invoked by the client.
LPF is configured as shown in the following example:
<bean id="logoutFilter" class="org.acegisecurity.ui.logout.LogoutFilter"> <constructor-arg value="/logoutSuccess.jsp"/> <constructor-arg> <list> <bean class="org.acegisecurity.ui.logout.SecurityContextLogoutHandler"/> </list> </constructor-arg> </bean> |
You can see that LPF takes two parameters in its constructor: the logout success URL (/logoutSuccess.jsp) and a list of handlers. The logout success URL is used to redirect the client after the logout process is complete. Handlers perform the actual logout process; I have configured only one handler because it is enough to invalidate the HTTP session.
The Exception Translation Filter (ETF) handles exceptional cases in the authentication and authorization procedure, such as when authorization fails. In these exceptional cases, ETF decides what to do.
For example, if a non-authenticated user attempts to access a protected resource, ETF serves the login page inviting the user to authenticate.
Similarly, in case of authorization failure, you can configure ETF to serve an Access Denied page.
ETF is configured as shown in the followign example:
<bean id="exceptionTranslationFilter" class="org.acegisecurity.ui.ExceptionTranslationFilter"> <property name="authenticationEntryPoint"> <bean class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint"> <property name="loginFormUrl" value="/login.jsp" /> </bean> </property> <property name="accessDeniedHandler"> <bean class="org.acegisecurity.ui.AccessDeniedHandlerImpl"> <property name="errorPage" value="/accessDenied.jsp" /> </bean> </property> </bean> |
As you can see from the above example, ETF takes two parameters named authenticationEntryPoint and accessDeniedHandler. The authenticationEntryPoint property specifies the login page and the accessDeniedHandler specifies the Access Denied page.
Acegi's interceptor filters are used to make authorization decisions. You need to configure interceptor filters to act after APF has performed a successful authentication. Interceptors use your application's access control policy to make authorisation decisions.
Later we will show you how to design access control policies, how to host them on a directory service, and how to configure Acegi to read your access control policy. For the moment however, we will stick to showing you how to configure a simple access control policy using Acegi.
You can divide configuring a simple access control policy into two steps:
Step # Writing a simple access control policy
Start by looking at the next example, which shows how to define a user and the user's role:
alice=123,ROLE_HEAD_OF_ENGINEERING |
The access control policy shown above defines a user named alice, whose password is 123 and whose role is ROLE_HEAD_OF_ENGINEERING.
Step 2. Configuring Acegi's interceptor filter
Interceptor filters use three components to make authorisation decisions, which I have configured in the next example:
<bean id="filterInvocationInterceptor" class="org.acegisecurity.intercept.web.FilterSecurityInterceptor"> <property name="authenticationManager" ref="authenticationManager" /> <property name="accessDecisionManager" ref="accessDecisionManager" /> <property name="objectDefinitionSource"> <value> CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON PATTERN_TYPE_APACHE_ANT /protected/**=ROLE_HEAD_OF_ENGINEERING /**=IS_AUTHENTICATED_ANONYMOUSLY </value> </property> <!-- More properties of the interceptor filter --> </bean> |
As the example shows, the three components you need to configure are the authenticationManager, accessDecisionManager and objectDefinitionSource:
Recall from the previous example that you defined ROLE_HEAD_OF_ENGINEERING for the user named alice. This means alice will be able to access the /protected/* URL.
As you have learned already, Acegi's components are dependent on each other to secure your applications. Later you will see how to configure Acegi to apply security filters in a specific order, thus creating a chain of filters. For this purpose, Acegi maintains a filter chain object which wraps all the filters you have configured to secure your application.
The following steps describe the life cycle of the filter chain:
To help you further understand Acegi filters we will give you a closer look at the operation of two of them: the Session Integration Filter and the Authentication Processing Filter.
How SIF creates a security context:
How APF authenticates a users:
You have learned quite a bit about Acegi so far, so we will now have a look at what you can do with what you have learned so far.
Securing Weave requires protecting certain resources, and if a user attempts to access any of the protected resources they will be presented with a login page. When the user signs in using the login page, the application automatically redirects to the requested protected resource.
The user can go directly to the login page, in which case the application presents the login page where the user can sign in. After signing in, the application redirects the user to a start page which is the default resource presented whenever the user signs in without requesting a particular resource.
For Weave the XML file that contains the beans used to configure Acegi is called security.xml and is stored in the same directory as the main config.xml file.
The following shows a simple security.xml file that secures Weave with information contained directly within the security.xml file itself
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"> <beans> <bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy"> <property name="filterInvocationDefinitionSource"> <!-- we use a different filter chain for requests sent to /server/request because they're JSON based requests and we want to send back a JSON formatted response if something goes wrong, so the only difference between the two filter chains is the exception translation filter --> <value> CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON PATTERN_TYPE_APACHE_ANT /server/request/**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityContextHolderAwareRequestFilter,rememberMeProcessingFilter,anonymousProcessingFilter,jsonExceptionTranslationFilter,filterInvocationInterceptor /**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityContextHolderAwareRequestFilter,rememberMeProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor </value> </property> </bean> <bean id="httpSessionContextIntegrationFilter" class="org.acegisecurity.context.HttpSessionContextIntegrationFilter"/> <bean id="authenticationProcessingFilter" class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilter"> <property name="authenticationManager" ref="authenticationManager"/> <!-- A bundle must be available that provides the /login HttpContext that contains the login page with the login form --> <property name="authenticationFailureUrl" value="/login.html?failure=true"/> <property name="defaultTargetUrl" value="/"/> <!-- The bundle that provides the /security HttpContext is provided by the Cohga security bundle --> <property name="filterProcessesUrl" value="/security/j_acegi_security_check.do"/> <property name="rememberMeServices" ref="rememberMeServices"/> </bean> <bean id="securityContextHolderAwareRequestFilter" class="org.acegisecurity.wrapper.SecurityContextHolderAwareRequestFilter"/> <bean id="rememberMeProcessingFilter" class="org.acegisecurity.ui.rememberme.RememberMeProcessingFilter"> <property name="authenticationManager" ref="authenticationManager"/> <property name="rememberMeServices" ref="rememberMeServices"/> </bean> <bean id="anonymousProcessingFilter" class="org.acegisecurity.providers.anonymous.AnonymousProcessingFilter"> <property name="key" value="changeThis"/> <property name="userAttribute" value="anonymous,ROLE_ANONYMOUS"/> </bean> <!-- Problems between the user and the server will be handled with this filter, it converts the error to a format suitable for display directly to the user, i.e. an HTML page --> <bean id="exceptionTranslationFilter" class="org.acegisecurity.ui.ExceptionTranslationFilter"> <property name="authenticationEntryPoint"> <bean class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint"> <property name="loginFormUrl" value="/login.html"/> <property name="forceHttps" value="false"/> </bean> </property> <property name="accessDeniedHandler"> <bean class="org.acegisecurity.ui.AccessDeniedHandlerImpl"> <property name="errorPage" value="/login.html?accessDenied=true"/> </bean> </property> </bean> <!-- Problems between the client and the server will be handled with this filter, it converts the error to a format that the client and decode and understand, i.e. a JSON response --> <bean id="jsonExceptionTranslationFilter" class="org.acegisecurity.ui.ExceptionTranslationFilter"> <property name="authenticationEntryPoint"> <bean class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint"> <property name="loginFormUrl" value="/login/execute.do"/> <property name="forceHttps" value="false"/> </bean> </property> <property name="accessDeniedHandler"> <bean class="org.acegisecurity.ui.AccessDeniedHandlerImpl"> <property name="errorPage" value="/login/execute.do?accessDenied=true"/> </bean> </property> </bean> <bean id="filterInvocationInterceptor" class="org.acegisecurity.intercept.web.FilterSecurityInterceptor"> <property name="authenticationManager" ref="authenticationManager"/> <property name="accessDecisionManager"> <bean class="org.acegisecurity.vote.AffirmativeBased"> <property name="allowIfAllAbstainDecisions" value="false"/> <property name="decisionVoters"> <list> <bean class="org.acegisecurity.vote.RoleVoter"/> <bean class="org.acegisecurity.vote.AuthenticatedVoter"/> </list> </property> </bean> </property> <!-- Make sure that user is at least anonymous before getting access, Weave will do further checks based on ACLs to see if the user must login --> <property name="objectDefinitionSource"> <value> CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON PATTERN_TYPE_APACHE_ANT /server/status=ROLE_ADMIN /private.html=ROLE_USER /**=IS_AUTHENTICATED_ANONYMOUSLY </value> </property> </bean> <bean id="rememberMeServices" class="org.acegisecurity.ui.rememberme.TokenBasedRememberMeServices"> <property name="userDetailsService" ref="userDetailsService"/> <property name="key" value="changeThis"/> </bean> <bean id="authenticationManager" class="org.acegisecurity.providers.ProviderManager"> <property name="providers"> <list> <ref local="daoAuthenticationProvider"/> <bean class="org.acegisecurity.providers.anonymous.AnonymousAuthenticationProvider"> <property name="key" value="changeThis"/> </bean> <bean class="org.acegisecurity.providers.rememberme.RememberMeAuthenticationProvider"> <property name="key" value="changeThis"/> </bean> </list> </property> </bean> <bean id="daoAuthenticationProvider" class="org.acegisecurity.providers.dao.DaoAuthenticationProvider"> <property name="userDetailsService" ref="userDetailsService"/> <property name="userCache"> <bean class="org.acegisecurity.providers.dao.cache.EhCacheBasedUserCache"> <property name="cache"> <bean class="org.springframework.cache.ehcache.EhCacheFactoryBean"> <property name="cacheManager"> <bean class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"/> </property> <property name="cacheName" value="userCache"/> </bean> </property> </bean> </property> </bean> <bean id="userDetailsService" class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl"> <property name="userMap"> <value> alice=123,ROLE_USER bob=password,ROLE_USER,disabled carol=secret,ROLE_USER ted,abc,ROLE_USER,ROLE_ADMIN </value> </property> </bean> </beans> |
The above example is a fairly basic security filter that stores user information directly in the file but one thing to note here is that only one client is actually protected, private
.
If there is more than one client configured for Weave then a user could have access to that one because from the above configuration the user will be logged on anonymously unless they have previously gone to the login page, or if they accessed the 'private' client directly.
So what is actually going on then? Well the important parts here are the two lines in the objectDefinitionSource
:
/private.html=ROLE_USER /**=IS_AUTHENTICATED_ANONYMOUSLY |
Taking the second line first, this specifies that any resource (not previously matched) requires that the user be (at least) an anonymous user, but because of the first line any request for a resource matching private.html
require that the user be part of the ROLE_USERS group, which means that they'll have to login to get the the private
client since the user must access private.html
to get to the private
client.
Obviously there is more to the first line than meets the eye. It turns out that this URL is interpreted by the server as being requests to load a specific client configuration (called private
in the above example) from config.xml
.
So for our above example we can assume that the config.xml
file contains at least something similar to the following:
<?xml version="1.0" encoding="UTF-8"?> <config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <client:config id="private"> <client:default>true</client:default> <client:debug>false</client:debug> <client:title>Weave Private HTML Client</client:title> ... </client:client> </client> |
Further, if we wish to provide a public and private client then we could add an additional client configuration, as follows:
<?xml version="1.0" encoding="UTF-8"?> <config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <client:config id="private"> <client:default>false</client:default> <client:debug>false</client:debug> <client:title>Weave Private Client</client:title> ... </client:client> <client:config id="public"> <client:default>true</client:default> <client:debug>false</client:debug> <client:title>Weave Public Client</client:title> ... </client:client> </client> |
Now the user has two different client configurations available, private
and public
, and they can access private
using the URL /weave/private.html
and public
using /weave/public.html
.
And, because of the way we have setup Acegi they will be asked to login to access private
but will have direct access to public
.
Of course this can be extended to provide multiple clients, both secure and un-secure, but creating different client configurations in config.xml and adding additional lines to the objectDefinitionSource
.
Note that in future this may change and the security information provided in th objectDefinitionSource
will be provided to Acegi based on the ACLs configured in config.xml rather than having to duplicate the information (see Access Control Lists later for more information). And, if fact by using ACLs in config.xml you can get by with just the IS_AUTHENTICATED_ANONYMOUSLY line and leave the config.xml file to determine who can access the client config, the disadvantage to this is that currently if the Weave server determines that the user does not have access to a client config then it will redirect the user to the login page, whereas if Acegi performs the access control then it may try perform the user authentication through some other means, for example using NTLM.
By using different roles, different users can be granted access to different client configurations.
For example, assuming we have three clients configured in client.xml, public
, internal
and private
, and we want anyone including the public to have access to public
, we want anyone except the public to have access to internal
and we only want a small group of people to have access to private
, then our objectDefinitionSource
would be:
/private.html=ROLE_ADMINISTRATOR /internal.html=ROLE_USER,ROLE_ADMINISTRATOR /**=IS_AUTHENTICATED_ANONYMOUSLY |
Then we would update our userDetailsService
to include the new USER_ADMINISTRATORS
role for those users who should get access to the private
client (note that we have also given administrators access to the internal
client).
<bean id="userDetailsService" class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl"> <property name="userMap"> <value> alice=123,ROLE_USER,ROLE_ADMINISTRATOR bob=password,ROLE_USER,disabled carol=secret,ROLE_USER ted,abc,ROLE_USER </value> </property> </bean> |
As mentioned in the introduction, the second half of the security system requires the configuration of Access Control Lists (ACL) to restrict access to items you wish to protect.
When a process initiated by the user attempts to access a restricted item (which is anything with an ACL attached) the groups that the user belongs are checked against the ACL to determine if the user should be given access to the item.
ACL's can be setup to either deny access to everything and selectively enable access, or to allow access to everything and selectively deny access. The former is more secure and recommended.
An ACL provides a list of groups that can either be denied access or allowed access and are processed linearly until there is a match that positively denies or grants approval. Also, there is a special group, anonymous
, that can be used to allow or deny access to users that are logged in anonymously.
Additionally, ACL's can reference other ACL's to provide a hierarchy with recursive checking performed to determine accessibility.
ACL's can be setup either in-line, that is included directly in the item they're guarding access to, or can configured individually and referenced by an item.
IMPORTANT NOTE
THERE IS NO ACCESS CONTROL AT ALL UNLESS AT LEAST ONE ACL IS DEFINED
This means that a default installation will provide no access control to any items until at least one ACL is defined, even if it is default.acl
.
Once at least one ACL is defined then access control restrictions will be enabled. This mean that if you are creating a public (or non-sensitive) installation then you do not need to worry about access control lists at all.
It is recommended that if you are going to have any sensitive information then the default ACL should be enabled first and set to deny access to everyone.