This file describes configuring Java for Kerberos for use with Sakai.

NOTE: To use this provider with an existing or new systemwide
configuration, contact your local administrator and/or follow the
steps in SYSTEMWIDE.txt. By default, most JDKs are NOT configured for
use with Kerberos.

By default, the provider provides authentication ONLY for existing 
accounts in the local Sakai user database (where Sakai user ids and 
Kerberos principals are the same). If you wish to allow anyone with a 
valid Kerberos principal to use Sakai, follow the instructions below 
under ADVANCED OPTIONS.

This provider implements a configurable, in-memory caching mechanism. 
By default, a user's successful authentication is valid for 5 minutes. 
This mechanism prevents WebDAV, which sends authenticates on every 
connection, from overloading local KDCs.

In addition, to protect the integrity of your Kerberos password, the 
use of a secure Web front-end is HIGHLY recommended.

Throughout this document, ${sakai.home} refers to the directory that
contains Sakai's configuration information. By default, this is the
"sakai" directory at the top-level of your Tomcat installation (known
here as $TOMCAT_HOME). For more information on configuring
${sakai.home}, refer to the configuration documentation in the top-level
"docs" directory of the Sakai source tree.

**GENERAL SETUP**

To use this provider using ${sakai.home}/sakai.properties:

1) Create a JAAS configuration file. A sample file -- sakai-jaas.conf 
-- with the following content is included:

/*
 * JAAS Login Configuration for Sakai 
 */

KerberosAuthentication {
   com.sun.security.auth.module.Krb5LoginModule required;
};

The provider uses the KerberosAuthentication context by default; it 
can be configured by changing the loginContext parameter in the 
components.xml file described in Step 3. Each context name is unique 
and may not be duplicated.

The installation of this file is described in Step 4.

2) A test program (JaasTest.java) is available to confirm Kerberos 
authentication. To run it:

$ javac JaasTest.java
$ java -Djava.security.auth.login.config=sakai-jaas.conf \
 JaasTest KerberosAuthentication

LoginContext for testing: KerberosAuthentication
Enter a username and password to test this LoginContext.

Kerberos username [user1]: user1
Kerberos password for user1: foo
Authentication succeeded.

If authentication fails, contact your local administrator for help.

3) Uncommment the configuration information in

    ../../component/project.xml

Then, change the domain parameter from "mydomain.edu" to your domain 
and, if necessary, the value of the cachettl parameter in

    ../../component/src/webapp/WEB-INF/components.xml

After deployment, you can also edit this file:

$TOMCAT_HOME/components/sakai-legacy-providers/WEB-INF/components.xml 

4) Once Sakai is deployed, copy sakai-jaas.conf to ${sakai.home} and 
then set options in ${sakai.home}/sakai.properties to configure the 
provider for use.

Three options control the behavior of this provider:

provider.kerberos.auth.login.config -- location of JAAS config file
provider.kerberos.krb5.conf -- location of krb5.conf
provider.kerberos.showconfig -- show extended config info (true/false)

Locations specified using the above options are used in place of the 
current system locations. Absolute path names are acceptable; if the 
file specified exists and is readable, it is used. Otherwise, the file 
path is assumed to be relative to ${sakai.home}. If no readable file 
is found, an error message is written to the log.

You MUST provide a value for provider.kerberos.auth.login.config 
unless you are using a systemwide configuration. Otherwise, all 
authentication will fail.

Examples:

provider.kerberos.auth.login.config=sakai-jaas.conf
provider.kerberos.auth.login.config=kerberos/sakai-jaas.conf
provider.kerberos.auth.login.config=/usr/local/sakai/sakai-jaas.conf

For general use. the last two options do not need to be specified. An
alternate Kerberos5 configuration file can specified using
provider.kerberos.krb5.conf; otherwise, the system default
(/etc/krb5.conf on Unix-based systems) is used. Setting the
provider.kerberos.showconfig option to "true" provides extended
configuration about the provider's settings in the catalina.out logs:

- Standard information (wrapped/edited for clarity)

INFO:
org.sakaiproject.component.kerberos.user.KerberosUserDirectoryProvider@1fd9cd5.init()
Domain=mydomain.edu
LoginContext=SakaiAuthentication
RequireLocalAccount=true KnownUserMsg=Integrity check on decrypted field failed
CacheTTL=300000

- Extended information (wrapped/edited for clarity)

INFO:
org.sakaiproject.component.kerberos.user.KerberosUserDirectoryProvider@1fd9cd5.init()
SakaiHome=/spare/sakai-201/jakarta-tomcat-5.5.9/sakai/
SakaiPropertyKrb5Conf=null
SakaiPropertyAuthLoginConfig=kerberos/sakai-jaas.conf
SystemPropertyKrb5Conf=null
SystemPropertyAuthLoginConfig=/spare/sakai-201/jakarta-tomcat-5.5.9/sakai/kerberos/sakai.jaas.conf

In the above, "null" entries indicate the use of systemwide defaults.

5) After startup, create a new Sakai account with your Kerberos 
principal as the user id. You should then be able to login using your 
Kerberos password.

**ADVANCED OPTIONS**

The Kerberos UserDirectoryProvider takes 5 configuration properties in 
its components.xml:

domain -- the 2nd-level domain name of the user's e-mail address
loginContext -- the name of the JAAS LoginContext to use
cachettl -- time (in milliseconds) to cache list of authenticated logins
requireLocalAccount -- require a local account to login (true/false)
knownUserMsg -- error message used to determine valid Kerberos principal

If you wish to allow anyone with a valid Kerberos principal to login 
into Sakai without a local account, you must configure the last two.

To do so:

1) Determine the error message to be used by passing a valid Kerberos 
principal and an INCORRECT password to the JaasTest application:

$ java -Djava.security.auth.login.config=sakai-jaas.conf \
 JaasTest KerberosAuthentication

(NOTE: for systemwide configuration testing, use:
	$ java JaasTest KerberosAuthentication
)

LoginContext for testing: KerberosAuthentication
Enter a username and password to test this LoginContext.

Kerberos username [user1]: user1
Kerberos password for user1: foo
Authentication failed.

Error message
 --> Integrity check on decrypted field failed (31) - PREAUTH_FAILED

In this case, we'll use "Integrity check on decrypted field failed" as 
the string to compare (the provider compares the first part of the 
string).

2) In the components.xml file, add these two lines:

<property name="requireLocalAccount"><value>false</value></property> 
<property name="knownUserMsg"><value>STRING</value></property>

where STRING is replaced by "Integrity check on decrypted field 
failed" Note: This string is the default, culled from RFC 1510.

