Form-Based Distributed Authentication in Sakai

PROBLEM OUTLINED

Form-Based Distributed Authentication is needed in Sakai, for both versions 1.5 and 2.0. This document outlines the best possible solution for implementing this method of authentication in Sakai, as outlined by Scott Amerson (IET) in accordance with feedback from various parties. These parties include Yale, Indiana, and the Sakai Development Team.

The possible solutions are outlined further in this document, in a matrix detailing various issues related to each implementation strategy. Also detailed in this document, is the high level overview of the authentication mechanism in Sakai.

This documentation is assuming the software that will be used for the implementation of authentication in Sakai is:

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, 2.1.x)

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.

Sakai uses the following steps in its authentication process:

Sakai checks "container auth":
*If Sakai trusts container, it then checks remote user vs user information (doesn't care about password). If this check passes, then done. If not, checks for providers (see below):

*If doesn't trust container, then it first checks the password. If the password fails, then it relies on the provider (only one can be implemented) to provide a means of maintaining user information. It is from then on that the provider either fails the authentication, or decides to store user information in Sakai

The implementation of Sakai at UCD, the latter path given will not be used because of the ability to incorporate DistAuth in the process early. A discussion of Form-Based DistAuth process is out of scope of this document, however the specific implementation strategy taken to incorporate Form-Based DistAuth into Sakai must meet the following requirements:
1.* Check for the presence of Cookie values "AuthUser" and "DA1", validate against IP and AFS space if required
2.* Set the remote user value accordingly, for Sakai's use
3.* Record the returnURL for the sendback from DistAuth

IMPLEMENTATION ALTERNATIVES

Below is a table defining the alternative strategies for implementing Form-Based DistAuth in Sakai:

The following options have been explored as possible solutions to the Sakai authentication problem. Here is a brief explanation of the given option:

Apache-Tomcat connector: The mod_jk2 connector implementation used for Shibboleth may be modified for this given implementation in Sakai (mod_jk connector should be used instead).

Catalina Valves/Realms: Tomcat inherently has a "single-signon" authentication valve which can be used when users are moving between webapps and should not be required to be authenticated again. Other custom implementations of valves and security realms may be implemented.

Tomcat Interceptors: Specific interceptors for different types of requests (e.g. JSPRequestInterceptor, etc.) may be implemented in order to trap the request before any process on the application server runs. Interceptors call a series of methods (10) per hit, so the performance may be an issue as well.

Servlet Filters: Filter requests that invoke servlets in a webapp. Sakai's architecture inherently invokes many servlets per pageload, so this may not be optimal.

Sakai modifications: Modifications to the framework of Sakai have been implemented and proven to work in Sakai 1.5 as a workaround. The drawback to this option is modification/maintenance of Sakai source code.

OPTION & NOTES	Apache-Tomcat connector	Catalina Valves/Realms	Tomcat Interceptors	Servlet filter	Sakai modifications
Programming Notes	Already created with Shibboleth, but needs to be modified/tested with Sakai	Specific to Catalina API's for Tomcat version	Specific to Tomcat API's	remoteUser()set, alternative means found of setting the user	getRemoteUser replaced with AuthUser cookie value
Time to implemement	Least	Most	Most	More	Low
Meets requirements?	Yes	Yes	Yes	Yes	Yes, modifications can be made
Any dependencies?	Running Apache, and Apache/Tomcat versions	Tomcat version, conf files and API	Tomcat version, conf files and API	Servlet 2.3+ API	Sakai version, need to manage Sakai code

TECHNICAL SOLUTION

The strategy proposed for implementing authentication in Sakai was to provide a proof of concept for the Sakai 1.5, Tomcat 5.0.28+, and Linux configuration. This was created on felix.ucdavis.edu:8100. This was a success (felix) using the Apache 2.0 + mod_jk connector configuration, however porting to Windows seemed to have issues with mod_perl compatibility. A solution was found using a servlet filter and modifying the code at the Sakai level, however this was most straightforward in Sakai 1.5.

TECHNICAL SOLUTION-- DESIGN ASPECT

The design of the technical solution found is described below:

Sakai 1.5, Sakai 2.0:

Required code:

UCDDistAuthFilterAndWrapper.jar, includes UCD Authentication Filter, and RequestWrapper to handle remote_user. See DistAuth Jar versions
updated web.xml config (different for Sakai 1.5 and 2.0)

Sakai 2.1.x+:

Required code:

ucd-form-based-distauth module, includes UCD Authentication Filter, and RequestWrapper to handle remote_user. https://mware.ucdavis.edu/svn/ucdsakai/trunk/ucd-form-based-distauth
updated web.xml config patch for login module in Sakai https://mware.ucdavis.edu/svn/ucdsakai/branches/sakai-core-2-1-x/login

Background (Please see previous documentation on early screenshots, functional specs, etc):

One solution that was found for Sakai 1.5, however not straight forward for Sakai 2.0. It is less than ideal, but just noted here as a solution that was found to work on both Windows and Linux. The details are provided below:
The loginservlet class was extended to a servlet called the DistAuthLoginServlet. The DistAuthLoginServlet preserves the same logic that the LoginServlet has, with exception to any password lookup/recognition information. Because the LoginServlet is used to capture form passwords, this logic can no longer be used and only DistAuth handles password information. Above is not the only difference between the DistAuthServlet and LoginServlet, the main difference is that the DistAuthLoginServlet replaces the "getRemoteUser" with the Kerberos name from the AuthUser cookie. The LoginServlet is used for inherent Sakai accounts (e.g. admin, etc.), while the DistAuthLoginServlet is the login that is protected by DistAuth. In addition to these modifications, other modifications need to be incorporated in the Sakai framework for DistAuth to be configured correctly, including the addition of a DistAuth filter to handle the DistAuth and DA1 cookie validation/parsing, etc. See the "HOW TO CONFIGURE DISTAUTH AND SAKAI 1.5, 2.0" section below.

Solution Found: For Sakai 1.5, 2.0, and 2.0.1, 2.1.x

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, 2.0.1, and 2.1.x

The following are instructions for adding DistAuth login to Sakai 1.5, 2.0, 2.1.x (This is assuming one login page that is protected by DistAuth, version 1 below)

Sakai 2.1.x

1. Remove any prior versions of DistAuth jars located in shared/lib/ or common/lib.

2. Setup any Sakai usernames you would like to have the ability to login to the site.
(this step will soon be replaced by automated provisioning)

3. Login to Sakai as admin. Set your admin account password to a secure value, then proceed.

4. 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.

5. Download the DistAuth filter and wrapper source from SVN: https://mware.ucdavis.edu/svn/ucdsakai/trunk/ucd-form-based-distauth OR https://mware.ucdavis.edu/svn/ucdsakai/branches/sakai-core-2-1-x-scottdev/ucd-form-based-distauth (most recent changes)

This DistAuth module contains filter and request wrapper combined, and is built by maven within Sakai.

6. 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

7. Apply the patch for the logging out of distauth and going to secureweb. This is now a BasicConfigurationService modification, and Jon Gorrono patched this service to go along with the logoutURL parameter in sakai.properties. See Jon G or Thomas about this code.

perform a patch command, when in the root of sakai, use:

*$SAKAI_DEV* directory, such as patch -p0< patch file location

8. Set the web.xml parameters for distauth via the login/login/src/webapp/WEB-INF directory (in sakai-core-2-1-x code). This directory contains web.xml configuration parameters, for setting filter mapping and filter params used by the DistAuth Servlet filter and wrapper.

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.

Please note, that there are fewer parameters necessary now than in past DistAuth jar versions. Here is an updated list of parameters to accomodate the changes from MyInfoVault and other projects.. These modifications have been necessary to remove extraneous parameters that are not relevant to Sakai

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>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>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>

<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>

8. Build the ucd-form-based-distauth module
cd $SAKAI_DEV/ucd-form-based-distauth
maven sakai

9. Stop Tomcat
/etc/init.d/tomcat stop
or on Windows use the net command or the Services Control Panel

10. Rebuild Sakai and deploy to Tomcat
cd $SAKAI_DEV
maven bld dpl

11. Start Tomcat
/etc/init.d/tomcat start
or on Windows use the net command or the Services Control Panel

12. 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 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>

<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>

<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>h3. 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)