Quick-start assistance.

readme.txt

@@ -28,6 +28,14 @@ DOCUMENTATION
 Please refer to the Reference Guide, which is located in the docs/reference
 directory. In addition, JavaDocs are located in the docs/api directory.
 
+-------------------------------------------------------------------------------
+ADDING ACEGI SECURITY TO YOUR OWN APPLICATION
+-------------------------------------------------------------------------------
+
+Take a look in samples/quick-start. There we give you the fragments to add to
+your existing web.xml and applicationContext.xml, along with a couple of files
+that need to be added to your WAR file.
+
 -------------------------------------------------------------------------------
 OBTAINING SUPPORT
 -------------------------------------------------------------------------------

samples/quick-start/.cvsignore

@@ -0,0 +1,5 @@
+classes
+dist
+api
+build.properties
+temporary

samples/quick-start/readme.txt

@@ -0,0 +1,51 @@
+===============================================================================
+                             QUICK-START SAMPLE
+===============================================================================
+
+Acegi Security's flexibility can be a bit daunting. Because projects only have
+so much budget, and people only have so much time, often the complexity of
+getting started can seem too high a price to pay. The quick-start sample is
+designed to provide you the basic building blocks needed to be added to your
+existing application.
+
+Quick-start is not executable or deployable. It's just a convenient, simple
+place where you can see what needs to be added to your web application's
+existing files and directories.
+
+What you _will_ need to change in the quick-start configuration:
+
+- It protects a /secure directory from HTTP requests. The /secure directory
+  is included (along with a debug.jsp you might find useful), but can be
+  deleted as soon as you are up and running. You'll need to setup your own
+  URLs to protect in the applicationContext.xml. Search for the 
+  FilterInvocationInterceptor bean.
+
+What you _may_ need to change in the quick-start configuration:
+
+- It uses an in-memory list of users as your authentication repository. This
+  means you edit the XML file to add users, change their roles etc. If you'd
+  prefer to use a database, remove the InMemoryDaoImpl from the 
+  applicationContext.xml, and add in a JdbcDaoImpl bean. For an example of
+  using the JdbcDaoImpl, search the reference guide.
+
+What does this buy you? Not a great deal more than using the Servlet spec
+(although we do support regular expressions and Ant paths for URL matching)!
+Seriously, you can use the Servlet spec to protect URLs, so why bother?
+The quick-start sample provides you the BASE security building blocks for
+your application. Whilst there's nothing wrong with using it instead of the
+Servlet spec security just for the better path support or avoiding the
+multitude of container authentication configurations, most people will use it
+because this foundation allows you to simply tweak configuration if you wish
+to:
+
+- Protect your business beans (search for MethodSecurityInterceptor in docs)
+- Use enterprise-wide single sign on (see CAS section in docs)
+- Use custom authorization voters (see Authorization section in docs)
+- Deploy custom authentication providers (see Authentication section in docs)
+- Perform BASIC authentication (search for BasicProcessingFilter in docs)
+- Automate HTTPS redirection (see Channel Security section in docs)
+
+Good luck! Don't forget we're happy to help. See the end of the docs for
+contact details.
+
+$Id$

samples/quick-start/war-root/WEB-INF/.cvsignore

@@ -0,0 +1,2 @@
+lib
+

samples/quick-start/war-root/WEB-INF/applicationContext.xml

@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
+
+<!--
+  - These entries must be added to your EXISTING applicationContext.xml. 
+  - This applicationContext.xml cannot be used in its current form. It only
+  - contains fragments of a real applicationContext.xml.
+  -
+  - $Id$
+  -->
+
+<beans>
+
+	<!-- =================== SECURITY BEANS YOU SHOULD CHANGE ================== -->
+	
+	<!-- If you replace this bean with say JdbcDaoImpl, just ensure your replacement
+	     has the same bean id (authenticationDao) -->
+	<bean id="authenticationDao" class="net.sf.acegisecurity.providers.dao.memory.InMemoryDaoImpl">
+  		<property name="userMap">
+			<value>
+				marissa=koala,ROLE_TELLER,ROLE_SUPERVISOR
+				dianne=emu,ROLE_TELLER
+				scott=wombat,ROLE_TELLER
+				peter=opal,disabled,ROLE_TELLER
+			</value>
+		</property>
+	</bean>
+
+	<!-- Note the order that entries are placed against the objectDefinitionSource is critical.
+	     The FilterSecurityInterceptor will work from the top of the list down to the FIRST pattern that matches the request URL.
+	     Accordingly, you should place MOST SPECIFIC (ie a/b/c/d.*) expressions first, with LEAST SPECIFIC (ie a/.*) expressions last -->
+	<bean id="filterInvocationInterceptor" class="net.sf.acegisecurity.intercept.web.FilterSecurityInterceptor">
+    	<property name="authenticationManager"><ref bean="authenticationManager"/></property>
+    	<property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
+    	<property name="runAsManager"><ref bean="runAsManager"/></property>
+ 		<property name="objectDefinitionSource">
+			<value>
+			    CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+			    PATTERN_TYPE_APACHE_ANT
+				/secure/**=ROLE_SUPERVISOR
+			</value>
+		</property>
+	</bean>
+
+	<!-- =================== SECURITY BEANS YOU WILL RARELY (IF EVER) CHANGE ================== -->
+	<!-- However, it is a good idea to change each <property name="key">'s to a new random value -->
+	
+	<bean id="daoAuthenticationProvider" class="net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider">
+     	<property name="authenticationDao"><ref bean="authenticationDao"/></property>
+		<property name="key"><value>my_password</value></property>
+	</bean>
+
+	<bean id="runAsManager" class="net.sf.acegisecurity.runas.RunAsManagerImpl">
+     	<property name="key"><value>my_run_as_password</value></property>
+ 	</bean>
+
+	<bean id="runAsAuthenticationProvider" class="net.sf.acegisecurity.runas.RunAsImplAuthenticationProvider">
+     	<property name="key"><value>my_run_as_password</value></property>
+ 	</bean>
+
+	<bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager">
+		<property name="providers">
+		  <list>
+		    <ref bean="runAsAuthenticationProvider"/>
+		    <ref bean="daoAuthenticationProvider"/>
+		  </list>
+		</property>
+	</bean>
+
+	<bean id="roleVoter" class="net.sf.acegisecurity.vote.RoleVoter"/>
+
+	<bean id="accessDecisionManager" class="net.sf.acegisecurity.vote.AffirmativeBased">
+   		<property name="allowIfAllAbstainDecisions"><value>false</value></property>
+		<property name="decisionVoters">
+		  <list>
+		    <ref bean="roleVoter"/>
+		  </list>
+		</property>
+	</bean>
+
+	<bean id="authenticationProcessingFilter" class="net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilter">
+		<property name="authenticationManager"><ref bean="authenticationManager"/></property>
+		<property name="authenticationFailureUrl"><value>/acegilogin.jsp?login_error=1</value></property>
+		<property name="defaultTargetUrl"><value>/</value></property>
+		<property name="filterProcessesUrl"><value>/j_acegi_security_check</value></property>
+	</bean>
+
+	<bean id="securityEnforcementFilter" class="net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter">
+		<property name="filterSecurityInterceptor"><ref bean="filterInvocationInterceptor"/></property>
+		<property name="authenticationEntryPoint"><ref bean="authenticationProcessingFilterEntryPoint"/></property>
+	</bean>
+
+	<bean id="authenticationProcessingFilterEntryPoint" class="net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint">
+		<property name="loginFormUrl"><value>/acegilogin.jsp</value></property>
+		<property name="forceHttps"><value>false</value></property>
+	</bean>
+
+</beans>

samples/quick-start/war-root/WEB-INF/lib/acegi-security.jar.txt

@@ -0,0 +1,15 @@
+You'll need to copy acegi-security.jar into your WEB-INF/lib directory.
+You can find the JAR in the /dist directory of any ZIP distribution.
+
+Acegi-security.jar requires the following JARs in WEB-INF/lib:
+
+commons-logging.jar
+commons-codec.jar
+commons-collections.jar
+jakarta-oro.jar
+spring.jar
+
+Most of the above JARs are included with Spring. Those that are not are
+definitely included in the Acegi Security "with dependencies" release ZIP.
+
+$Id$

samples/quick-start/war-root/WEB-INF/web.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' 'http://java.sun.com/dtd/web-app_2_3.dtd'>
+
+<!--
+  - These entries must be added to your EXISTING web.xml. This web.xml
+  - cannot be used in its current form. It only contains fragments of a real
+  - web.xml.
+  -
+  - $Id$
+  -->
+
+<web-app>
+
+	<!-- It is assumed you are already using Spring's ContextLoaderListener -->
+	
+	<!-- Do not forget to remove any existing Servlet spec security directives from your current web.xml -->
+
+	<filter>
+        <filter-name>Acegi Authentication Processing Filter</filter-name>
+        <filter-class>net.sf.acegisecurity.util.FilterToBeanProxy</filter-class>
+        <init-param>
+            <param-name>targetClass</param-name>
+            <param-value>net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilter</param-value>
+        </init-param>
+    </filter>
+
+    <filter>
+        <filter-name>Acegi Security System for Spring Auto Integration Filter</filter-name>
+        <filter-class>net.sf.acegisecurity.ui.AutoIntegrationFilter</filter-class>
+    </filter>
+
+    <filter>
+        <filter-name>Acegi HTTP Request Security Filter</filter-name>
+        <filter-class>net.sf.acegisecurity.util.FilterToBeanProxy</filter-class>
+        <init-param>
+            <param-name>targetClass</param-name>
+            <param-value>net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter</param-value>
+        </init-param>
+    </filter>
+	
+    <filter-mapping>
+      <filter-name>Acegi Authentication Processing Filter</filter-name>
+      <url-pattern>/*</url-pattern>
+    </filter-mapping>
+
+    <filter-mapping>
+      <filter-name>Acegi Security System for Spring Auto Integration Filter</filter-name>
+      <url-pattern>/*</url-pattern>
+    </filter-mapping>
+    
+    <filter-mapping>
+      <filter-name>Acegi HTTP Request Security Filter</filter-name>
+      <url-pattern>/*</url-pattern>
+    </filter-mapping>
+
+</web-app>

samples/quick-start/war-root/acegilogin.jsp

@@ -0,0 +1,42 @@
+<%@ taglib prefix='c' uri='http://java.sun.com/jstl/core' %>
+<%@ page import="net.sf.acegisecurity.ui.AbstractProcessingFilter" %>
+<%@ page import="net.sf.acegisecurity.AuthenticationException" %>
+
+<html>
+  <head>
+    <title>Login</title>
+  </head>
+
+  <body>
+    <h1>Login</h1>
+
+	<P>If you've used the standardInMemoryDaoImpl config, try these users:
+	<P>
+	<P>username <b>marissa</b>, password <b>koala</b> (granted ROLE_SUPERVISOR)
+	<P>username <b>dianne</b>, password <b>emu</b> (not a supervisor)
+	<p>username <b>scott</b>, password <b>wombat</b> (not a supervisor)
+	<p>
+	
+    <%-- this form-login-page form is also used as the 
+         form-error-page to ask for a login again.
+         --%>
+    <c:if test="${not empty param.login_error}">
+      <font color="red">
+        Your login attempt was not successful, try again.<BR><BR>
+        Reason: <%= ((AuthenticationException) session.getAttribute(AbstractProcessingFilter.ACEGI_SECURITY_LAST_EXCEPTION_KEY)).getMessage() %>
+      </font>
+    </c:if>
+
+    <form action="<c:url value='j_acegi_security_check'/>" method="POST">
+      <table>
+        <tr><td>User:</td><td><input type='text' name='j_username'></td></tr>
+        <tr><td>Password:</td><td><input type='password' name='j_password'></td></tr>
+
+        <tr><td colspan='2'><input name="submit" type="submit"></td></tr>
+        <tr><td colspan='2'><input name="reset" type="reset"></td></tr>
+      </table>
+
+    </form>
+
+  </body>
+</html>

samples/quick-start/war-root/logoff.jsp

@@ -0,0 +1,3 @@
+<%session.invalidate();
+response.sendRedirect("index.jsp");
+%>

samples/quick-start/war-root/secure/debug.jsp

@@ -0,0 +1,47 @@
+<%@ page import="net.sf.acegisecurity.context.Context" %>
+<%@ page import="net.sf.acegisecurity.context.ContextHolder" %>
+<%@ page import="net.sf.acegisecurity.context.SecureContext" %>
+<%@ page import="net.sf.acegisecurity.Authentication" %>
+<%@ page import="net.sf.acegisecurity.GrantedAuthority" %>
+<%@ page import="net.sf.acegisecurity.adapters.AuthByAdapter" %>
+
+<% Context context = ContextHolder.getContext();
+if (context != null) { %>
+	Context on ContextHolder is of type: <%= context.getClass().getName() %><BR><BR>
+	
+<%	if (context instanceof SecureContext) { %>
+		The Context implements SecureContext.<BR><BR>
+<%		SecureContext sc = (SecureContext) context;
+		
+		Authentication auth = sc.getAuthentication();
+		if (auth != null) { %>
+			Authentication object is of type: <%= auth.getClass().getName() %><BR><BR>
+			Authentication object as a String: <%= auth.toString() %><BR><BR>
+			
+			Authentication object holds the following granted authorities:<BR><BR>
+<%			GrantedAuthority[] granted = auth.getAuthorities();
+			for (int i = 0; i < granted.length; i++) { %>
+				<%= granted[i].toString() %> (getAuthority(): <%= granted[i].getAuthority() %>)<BR>
+<%			}
+
+			if (auth instanceof AuthByAdapter) { %>
+				<BR><B>SUCCESS! Your container adapter appears to be properly configured!</B><BR><BR>
+<%			} else { %>
+				<BR><B>SUCCESS! Your web filter appears to be properly configured!</B><BR>
+<%			}
+			
+		} else { %>
+			Authentication object is null.<BR>
+			This is an error and your container adapter will not operate properly until corrected.<BR><BR>
+<%		}
+	} else { %>
+		<B>ContextHolder does not contain a SecureContext.</B><BR>
+		This is an error and your container adapter will not operate properly until corrected.<BR><BR>
+<%	}
+} else { %>
+	<B>ContextHolder on ContextHolder is null.</B><BR>
+	This indicates improper setup of the container adapter. Refer to the reference documentation.<BR>
+	Also ensure the correct subclass of AbstractMvcIntegrationInterceptor is being used for your container.<BR>
+<%}
+%>
+