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+, but not 5.5)
• Sakai 1.5.0 (or 1.5.1 if available)
• 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)

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"
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 not been implemented. The drawback to this option is modification/maintenance of Sakai source 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. An ideal solution has since been found using a servlet filter and modifying the code at the Sakai level.

TECHNICAL SOLUTION-- DESIGN ASPECT

The design of the technical solution found is described below:

Sakai 1.5:
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. See the "HOW TO CONFIGURE DISTAUTH AND SAKAI 1.5" section below.

HOW TO CONFIGURE DISTAUTH AND SAKAI 1.5

The following are instructions for adding DistAuth login to Sakai 1.5 (This is assuming a login page with both DistAuth and Sakai Login together, version 2 below)

• Put the UCDDistAuth.jar in the common areas where Tomcat needs to find them (common-lib, shared-lib) This is available from Scott Amerson at IET.
• Put the DistAuthLoginServlet.java file in the ..\sakaidev\chef-tool\src\java\org\sakaiproject\tool\authn directory. This is an attachment (rename file for capital letters.
• Put the new login.vm (assuming you haven't changed the out of box version) in ..\sakaidev\chef-tool\src\webapp\vm\authn. An example page vm file is provided as an attachment.
• Add the following to the web.xml in the sakaidev\chef-tool\src\webapp\WEB-INF directory
  <!?servlet declaration?

<servlet>

<servlet-name>

ucdlogin

</servlet-name>

<servlet-class>

org.sakaiproject.tool.authn.DistAuthLoginServlet

</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<!?further down, add the mapping?

<servlet-mapping>

<servlet-name>

ucdlogin

</servlet-name>

<url-pattern>

/ucdlogin/*

</url-pattern>

</servlet-mapping>

• 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>myfilter</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>

<init-param>

<param-name>LookupPath</param-name>

<param-value>/</param-value>

</init-param>

</filter>

<filter-mapping>

<filter-name>myfilter</filter-name>

<url-pattern>/tunnel/sakai-chef-tool/ucdlogin/*</url-pattern>

</filter-mapping>

• Rebuild chef-tools module in Sakai (or full Sakai if you haven't made significant changes). Redeploy to Tomcat?just copying the WAR file doesn't seem to be enough. Verify that the source codes being changed are indeed modified at the Tomcat level. I have not found a maven goal that does this specifically..
• Add top.login=false and container.auth=true to the sakai.properties file (this will turn off the password field on the login page)
• Make necessary changes to login servlet at the sitenavservlet level. This may add another button with text "UCD login" for example on the portal page.
• Restart Tomcat: test that when you hit login (you shouldn't be localhost, use your IP so that the domain cookie is set correctly and can be seen), that the form that has the "DistAuth log in" button is there. When you click this button, you should be taken to DistAuth. Check error logs for the debugging code that I have in Cookies/Filters, etc.

Screenshots are provided for 2 versions:
1. ) Dist Auth login and login buttons appear on site Login. Each will take you to a different location to authenticate.
2. ) One Login button replaces username and password form boxes on the site Login, takes you to a central login for both DistAuth and Sakai admin.