...
- Tomcat (5.0.24+ for Sakai 1.5, 5.5 used for Sakai 2.0)
- Sakai 1.5.0, 1, 2.0, 2.0.1
- Backend (assuming MySQL 4.1 or Oracle)
For Sakai 2.0, the compatible Tomcat version has now been determined to be 5.5.x, thus this needs to be accounted for in the design process.
AUTHENTICATION PROCESS (Sakai 1.5.0, 1.5.1, 2.0, 2.0.1)
In summary, Sakai allows for Tomcat container authentication ("container.auth" setting in sakai.properties) to be enabled as well as customization of various interfaces (UserDirectoryProvider in particular) within Sakai to support authentication. Sakai authentication is now supporting an LDAPDirectoryProvider, and with each provider interface there are options to edit/store/ and modify users. By setting the "container.auth" parameter accordingly, Sakai is configured to trust remote user.
...
Solution Found: For both Sakai 1.5, 2.0, and 2.0.1
Keeping the requirements in mind (see Requirements doc), a better solution had to be found that didn't involve direct modification and maintenance of Sakai source code. The solution found is a combination of a Servlet Filter and Request Wrapper, each handling a portion of the filtering and request handling in conjunction with the existing Sakai Request Filter.
HOW TO CONFIGURE DISTAUTH AND SAKAI 1.5.0, 1.5.1, 2.0, and 2.0.1
The following are instructions for adding DistAuth login to Sakai 1.5 and 2.0 (This is assuming one login page that is protected by DistAuth, version 1 below)
Sakai 2.0.1
1. Setup any Sakai usernames you would like to have the ability to login to the site.
(this step will be replaced by automated provisioning)
2. Login to Sakai as admin. Set your admin account password to a secure value, then proceed.
3. Update the admin realm to include the usernames who should have administrative rights when they login to the Sakai instance.
Click the Realms navigation link.
Click the /site/!admin realm.
Click the Grant Ability link.
Add any usernames in the provide ID box.
Save your changes to the Realm.
Click Done to commit your changes to the Sakai Realm.
4. Obtain a copy of the UCDDistAuthFilterAndWrapper.jar version 1.01 and copy this into $CATALINA_HOME/common/lib. This makes the filter code available to any web-app on that instance of the servlet container (Tomcat).
Version 1.01 contains the filter and request wrapper combined.
5. Edit the sakai.properties file located in $CATALINA_HOME/sakai/sakai.properties by default.
Turn on the container.login behavior in sakai.properties. If you do not have a line add
container.login = true
6. Edit the login servlet's web.xml file and set up the servlet filter by modifying
$SAKAI_DEV\login\login\src\webapp\WEB-INF\web.xml
See the example web.xml below. The order is important within the web.xml file. Note that <filter> and <filter-mapping> elements must be contiguous within the web.xml file. The example below contains many parameters that are required for completeness but may not be used in your impementation. The ... notation is included to demonstrate that you may additional entries in your web.xml file. The critical elements that were used to test and the order-important elements are each included below.
EXAMPLE web.xml:
<webapp>
...
<filter>
<filter-name>sakai.request</filter-name>
<filter-class>org.sakaiproject.util.RequestFilter</filter-class>
</filter>
<filter>
<filter-name>sakai.request.container</filter-name>
<filter-class>org.sakaiproject.util.RequestFilter</filter-class>
<init-param>
<param-name>tool.placement</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>remote.user</param-name>
<param-value>false</param-value>
</init-param>
</filter>
<filter>
<filter-name>ucdfilter</filter-name>
<filter-class>edu.ucdavis.security.distauth.AuthenticationFilter</filter-class>
<init-param>
<param-name>LoginURL</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>InvalidCookieURL</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>InvalidLoginURL</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>InvalidTokenURL</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>InternalErrorURL</param-name>
<param-value>Error.html</param-value>
</init-param>
<init-param>
<param-name>TimeoutInterval</param-name>
<param-value>3600</param-value>
</init-param>
<init-param>
<param-name>TokenPath</param-name>
<param-value>/afs/ucdavis.edu/common/authinfo/</param-value>
</init-param>
<init-param>
<param-name>LogPath</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>LogFile</param-name>
<param-value>C:\distauth.log</param-value>
</init-param>
<init-param>
<param-name>ValidateUserAgainstDB</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>DatabaseQuery</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>ProtectionLevel</param-name>
<param-value>2</param-value>
</init-param>
<init-param>
<param-name>PassThrough</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>LogoutURL</param-name>
<param-value>https://secureweb.ucdavis.edu:443/form-auth/logout?</param-value>
</init-param>
<init-param>
<param-name>SendBackURL</param-name>
<param-value>https://secureweb.ucdavis.edu:443/form-auth/sendback?</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>sakai.request</filter-name>
<servlet-name>sakai.login</servlet-name>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>INCLUDE</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>sakai.request.container</filter-name>
<servlet-name>sakai.login.container</servlet-name>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<servlet>
<servlet-name>sakai.login</servlet-name>
<servlet-class>org.sakaiproject.tool.login.LoginTool</servlet-class>
<init-param>
<param-name>container</param-name>
<param-value>/sakai-login/container</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>sakai.login.container</servlet-name>
<servlet-class>org.sakaiproject.tool.login.ContainerLogin</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<!-- map the container login, and then cause it to trigger container authentication -->
<servlet-mapping>
<servlet-name>sakai.login.container</servlet-name>
<url-pattern>/container/*</url-pattern>
</servlet-mapping>
<filter-mapping>
<filter-name>ucdfilter</filter-name>
<servlet-name>sakai.login.container</servlet-name>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<listener>
<listener-class>org.sakaiproject.util.ToolListener</listener-class>
</listener>
...
</webapp>
7. Stop Tomcat
/etc/init.d/tomcat stop
or on Windows use the net command or the Services Control Panel
8. Rebuild Sakai and deploy to Tomcat
cd $SAKAI_DEV
maven bld dpl
9. Start Tomcat
/etc/init.d/tomcat start
or on Windows use the net command or the Services Control Panel
10. Now test that when you visit your Sakai instance's URL and click the login link you are sent to the UC Davis DistAuth Page for authentication. Note that it is important to use the dotted quad IP Address of FQDN in your URL. This is required for DistAuth to function. Do not use localhost o the localhost IP Address to test this. Check access and/or error logs for further details of the test.
Sakai 1.5
1. Download current version of DistAuth filter and wrapper , and place it in the Tomcat/shared/lib directory.
2. Add the following params to the ..\Tomcat 5.0\conf web.xml to declare the DistAuth Filter and mapping.. Basically these are configurable pieces that not everyone will need, but we should put them in. ProtectionLevel is most important (2 is default, 3 is AFS)
<filter>
...