Crowd provides centralised authentication and single sign-on connectors for the web security framework Acegi. Acegi provides a modular and highly configurable approach to authentication and authorisation for J2EE applications.
If your web application already makes use of the Acegi framework for authentication and authorisation, you can use the Crowd Acegi connector to allow your application to easily delegate authentication and authorisation requests to Crowd.
The connectors are available with Crowd 1.2 and later and have been developed and tested with Acegi 1.0.5.
Please consult the Acegi quick start guide or reference guide for a thorough insight into the Acegi framework. You might also find useful information in our Crowd-Acegi integration tutorial.
![]() | This guide assumes developer-level knowledge and an Acegi-based web application This guide is for developers rather than administrators. This guide assumes you have Crowd 1.5.1 or later installed and that you want to integrate your Acegi-based web application with Crowd's security server. The documentation below describes how to integrate Crowd with your own application that uses the Acegi framework. It assumes you already use Acegi in your application. If you need help integrating the Acegi framework with your web application, have look at some of the Acegi documentation. |
![]() | Spring Security 2 If you're working with Spring Security, we have a separate tutorial. |
Prerequisites
- Download and configure Crowd. Refer to the Crowd Installation Guide for detailed information on how to do this. We will refer to the Crowd root folder as
CROWD
. - Have your Acegi-based custom application ready for tweaking. We will refer to your custom application as 'AcegiApp'.
Step 1. Configuring Crowd to Talk to your Acegi Application
Crowd needs to be aware that AcegiApp will be making authentication requests to Crowd. In brief, you will need to do the following:
- Add the AcegiApp application to Crowd.
- Add and configure the directories visible to AcegiApp.
- Add and map the groups which are allowed to authenticate with AcegiApp.
Please see Adding an Application for a detailed guide.
Step 2. Installing the Crowd Acegi Connector
2.1 Adding the Crowd Acegi Connector to your Acegi Application
You will need to add the Crowd Acegi connector library and its associated dependencies to your Acegi application. You can do this manually by copying over the JAR files to your Acegi application or, if your Acegi application is a Maven project, you can add the Crowd Acegi connector as a project dependency. Both methods are described below.
2.1.1 Manually Adding the Crowd Acegi Connector Libraries
Follow either 2.1.1 or 2.1.2 (not both).
Copy the Crowd integration libraries and configuration files. This is described in the Client Configuration documentation. You will need to copy at least the following file to your Acegi application:
Copy From |
Copy To |
---|---|
CROWD/client/crowd-integration-client-X.X.X.jar |
AcegiApp/WEB-INF/lib |
CROWD/client/lib/*.jar |
AcegiApp/WEB-INF/lib |
2.1.2 Adding the Crowd Acegi Connector as a Maven Dependency
Follow either 2.1.1 or 2.1.2 (not both).
See more information on Maven 2 integration.
2.2 Adding the Cache Configuration File
Copy the following file into your application's classpath:
Copy From |
Copy To |
---|---|
CROWD/client/conf/crowd-ehcache.xml |
AcegiApp/WEB-INF/classes/crowd-ehcache.xml |
This file can be tweaked to change the cache behaviour.
2.3 Configuring the Crowd Acegi Connector Properties
The Crowd Acegi connector needs to be configured with the details of the Crowd server.
- Copy the default
crowd.properties
file to the classpath of your Acegi application:Copy From
Copy To
CROWD/client/conf/crowd.properties
AcegiApp/WEB-INF/classes
- Edit the
crowd.properties
and populate the following fields appropriately:Key
Value
application.name
Same as application name defined when adding the application to Crowd in Step 1.
application.password
Same as application password defined when adding the application to Crowd in Step 1.
crowd.server.url
session.validationinterval
This is the time interval between requests which validate whether the user is logged in or out of the Crowd SSO server. Set to 0, if you want authentication checks to occur on each request. Otherwise set to the number of minutes you wish to wait between requests. Setting this value to 1 or higher will increase the performance of Crowd's integration.
You can read more about the crowd.properties file.
Step 3. Configuring your Acegi Application to Use the Crowd Acegi Connector
There are two ways you can integrate your application with Crowd:
- Centralised user management: The user repository available to your application will be the user repository allocated to your application via Crowd. This means that your application will use the centralised user repository for retrieving user details as well as performing authentication.
- Single sign-on: In addition to centralised authentication, SSO will be available to your application. If any other SSO-enabled applications (such as JIRA, Confluence, or your own custom applications) are integrated with Crowd, then SSO behaviour will be established across these applications. If you sign in to one application, you are signed in to all applications. If you sign out of one application, you are signed out of all applications.
First, you will need to add the Crowd client application context to wire up the Crowd beans that manage the communication to Crowd. You can do this by including the applicationContext-CrowdClient.xml
Spring configuration file, found in crowd-integration-client.jar
. For example, if you are configuring Spring using a context listener, you can add the following parameter in your your Acegi application's WEB-INF/web.xml
:
<context-param> <param-name>contextConfigLocation</param-name> <param-value> ... classpath:/applicationContext-CrowdClient.xml ... </param-value> </context-param>
Next, open the applicationContext.xml
file relevant to your application, which contains the Acegi configuration. This is the file in your application that defines the Acegi beans. You are likely to have a bean configuration similar to this snippet:
<bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy"> <property name="filterInvocationDefinitionSource"> <value> CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON PATTERN_TYPE_APACHE_ANT /images/**=#NONE# /scripts/**=#NONE# /styles/**=#NONE# /**=httpSessionContextIntegrationFilter,logoutFilter,authenticationProcessingFilter,securityContextHolderAwareRequestFilter,rememberMeProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor </value> </property> </bean>
3.1 Configuring Centralised User Management
Perform the following updates to your Acegi Spring configuration:
- Add the definition of the CrowdUserDetailsService:
<bean id="crowdUserDetailsService" class="com.atlassian.crowd.integration.acegi.user.CrowdUserDetailsServiceImpl"> <property name="authenticationManager" ref="crowdAuthenticationManager"/> <property name="groupMembershipManager" ref="crowdGroupMembershipManager"/> <property name="userManager" ref="crowdUserManager"/> <property name="authorityPrefix" value="ROLE_"/> </bean>
- Add the definition of the RemoteCrowdAuthenticationProvider:
<bean id="crowdAuthenticationProvider" class="com.atlassian.crowd.integration.acegi.RemoteCrowdAuthenticationProvider"> <constructor-arg ref="crowdAuthenticationManager"/> <constructor-arg ref="httpAuthenticator"/> <constructor-arg ref="crowdUserDetailsService"/> </bean>
- Update the definition of your AuthenticationManager / ProviderManager to use the CrowdAuthenticationProvider. If you need multiple authentication providers, you can append the CrowdAuthenticationProvider to your list.
<bean id="authenticationManager" class="org.acegisecurity.providers.ProviderManager"> <property name="providers"> <list> <ref local="crowdAuthenticationProvider"/> .... </list> </property> </bean>
![]() | Further extensions
|
![]() | Crowd's remote API We recommend that applications do not store the Crowd users locally. Rather, applications should query users via Crowd's remote API. |
3.2 Configuring Single Sign-On (SSO)
![]() | SSO is optional and requires centralised user management Single sign-on is optional. If you wish to configure SSO you must first configure centralised user management as described in step 3.1 above. |
Perform the following additional updates to your Acegi Spring configuration:
- Update the definition of the AuthenticationProcessingFilter to use the CrowdAuthenticationProcessingFilter:
<bean id="authenticationProcessingFilter" class="com.atlassian.crowd.integration.acegi.CrowdSSOAuthenticationProcessingFilter"> <property name="httpAuthenticator" ref="httpAuthenticator"/> <property name="authenticationManager" ref="authenticationManager"/> <property name="filterProcessesUrl" value="/console/j_security_check"/> <property name="authenticationFailureUrl" value="/login.jsp?error=true"/> <property name="defaultTargetUrl" value="/"/> ... </bean>
- Add the definition of the CrowdLogoutHandler:
<bean id="crowdLogoutHandler" class="com.atlassian.crowd.integration.acegi.CrowdLogoutHandler"> <property name="httpAuthenticator" ref="httpAuthenticator"/> </bean>
- Update the definition of the LogoutFilter to use the CrowdLogoutHandler:
<bean id="logoutFilter" class="org.acegisecurity.ui.logout.LogoutFilter"> <constructor-arg value="/index.jsp"/> <constructor-arg> <list> ... <ref bean="crowdLogoutHandler"/> <bean class="org.acegisecurity.ui.logout.SecurityContextLogoutHandler"/> </list> </constructor-arg> <property name="filterProcessesUrl" value="/logout.jsp"/> </bean>
Step 4. Restarting your Acegi Application
Bounce your application. You should now have centralised authentication and single sign-on with Crowd.
Authorisation
For the purposes of Crowd integration with Acegi, you should map Acegi's roles to Crowd's groups. To put it another way: in order to use Acegi's authorisation features, users in Crowd will have their Acegi roles specified by their group names.
For example if user 'admin' is in the 'crowd-admin' group, then the user 'admin' will be authorised to view pages restricted to the 'crowd-admin' role in Acegi.
<!-- authorisation --> <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 /console/secure/**=ROLE_crowd-admin /console/user/**=IS_AUTHENTICATED_FULLY </value> </property> </bean> <bean id="accessDecisionManager" 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>
RELATED TOPICS
- Using the Application Browser
- Adding an Application
- Configuring the Google Apps Connector
- Mapping a Directory to an Application
- Specifying an Application's Address or Hostname
- Testing a User's Login to an Application
- Enforcing Lower-Case Usernames, Groups and Roles for an Application
- Managing an Application's Session
- Deleting or Deactivating an Application
- Configuring Caching for an Application
- Overview of SSO
- Configuring Options for an Application