//
// weijun.wang@sun.com

HTTP SPNEGO
===========

JPlan 116: SPNEGO HTTP authentication
    http://jplan.sfbay/feature/116)
RFE 6260531: SPNEGO HTTP authentication
    http://monaco.sfbay/detail.jsf?cr=6260531)
CCC 6244039: more HTTP authentication schemes to support in Java
    http://ccc.sfbay/6244039


What's HTTP SPNEGO
==================

HTTP SPNEGO supports the Negotiate authentication scheme in an HTTP 
communication. There are 2 types of authentication here:

1. Web Authentication. The Web Server responses with
       HTTP/1.1 401 Unauthorized
       WWW-Authenticate: Negotiate
   the client will need to send a header like
       Authorization: Negotiate YY.....
   to authenticate itself to the server
2. Proxy Authentication. The Web Server responses with
       HTTP/1.1 407 Proxy Authentication Required 
       Proxy-Authenticate: Negotiate
   the client will need to send a header like
       Proxy-Authorization: Negotiate YY.....
   to authenticate itself to the proxy server

The new codes support both types of authentication.


How to use the new feature
==========================

There is no new public API function involved in the new feature, but
several configurations are needed to perform a success communication:

1. Since the SPNEGO mechanism will call the Kerberos V5 login module to
   do real works. Kerberos configurations are needed. which includes:

   a) Some way to provide Kerberos realm and KDC address. This can be
      achieved with the Java system property java.security.krb5.realm
      and java.security.krb5.kdc. For example:
            java -Djava.security.krb5.realm=REALM_NAME \
                 -Djava.security.krb5.kdc=kdc.realm.name \
                 ClassName

   b) A JAAS config file denoting what login module to use. HTTP SPNEGO
      codes will look for the standard GSS_INITIATE_ENTRY entry named
      "com.sun.security.jgss.initiate".

      For example, you can provide a file spnegoLogin.conf:
          com.sun.security.jgss.initiate {
              com.sun.security.auth.module.Krb5LoginModule 
                  required useTicketCache=true;
          };
      and run java with:
            java -Djava.security.krb5.realm=REALM_NAME \
                 -Djava.security.krb5.kdc=kdc.realm.name \
                 -Djava.security.auth.login.config=spnegoLogin.conf \
                 ClassName


      Another JAAS login entry "http.auth.negotiate.server" is defined
      to be used by the server side.

2. Just like other HTTP authentication scheme, the client can provide
   a customized java.net.Authenticator to feed username and password to
   the HTTP SPNEGO module when they are needed (e.g. there is no keytab
   cache available). The only authentication information needed to be
   checked in your Authenticator is the scheme which can be retrieved
   with getRequestingScheme(). The value should be "Negotiate". 

   This means your Authenticator implementation will look like:

    class MyAuthenticator extends Authenticator {

	public PasswordAuthentication getPasswordAuthentication () {
            if (getRequestingScheme().equalsIgnoreCase("negotiate")) {
                String krb5user;
                char[] krb5pass;
                // get krb5user and krb5pass in your own way
                ....
                return (new PasswordAuthentication (krb6user, 
                            krb5pass.toCharArray()));
            } else {
                ....
            }
	}
    }

3. The client can still provide system property http.auth.preference to
   denote that a certain scheme should always be used as long as the
   server request for it. You can use "SPNEGO" or "Kerberos" for this
   system property. "SPNEGO" means you prefer to challenge the Negotiate
   scheme using the GSS/SPNEGO mechanism; "Kerberos" means you prefer
   to challenge the Negotiate scheme using the GSS/Kerberos mechanism.
   Normally, when authenticating against a Microsoft product, you can
   use "SPNEGO". The value "Kerberos" also works for Microsoft servers.
   It's only needed when you encounter a server which knows Negotiate
   but doesn't know about SPNEGO.

   If http.auth.preference is not set, the internal order choosen is:
      GSS/SPNEGO -> Digest -> BTLM -> Basic

   Noticed that Kerberos does not appear in this list, since whenever
   Negotiate is supported, GSS/SPNEGO is always chosen.

4. If the server has provided more than one authentication schemes
   (including Negotiate), according to the processing order mentioned
   in the last section, Java will try to challenge the Negotiate scheme.
   However, if the protocol cannot be established successfully (e.g.
   The kerberos configuration is not correct, or the server's hostname
   is not recorded in the KDC principal DB, or the username and password
   provided by Authenticator is wrong),  then the 2nd strongest scheme
   will be automatically used. You can notice this behaviour in the test
   case: TEST_NAME="Authenticate fallback".

   Attention: If http.auth.preference is set to SPNEGO or Kerberos, then
   we assume you only want to try the Negotiate scheme even if it fails.
   we won't fallback to any other scheme and your program will result in
   throwing an IOException saying it receives a 401 or 407 error from
   the HTTP response. This behaviour can be observed in the test case:
   TEST_NAME="Authenticate no fallback"


Test
====

The test is a bash script spnegoTest, which makes use of the Java class 
WebGet. WebGet.java is included. To run the test, you need these files:

    spnegoTest
    spnegoLogin.conf       JAAS login config file
    spnegoLog.properties   logging config file

The test environment includes 1 or 2 KDC server, 1 or 2 Web server, and 
1 proxy server. The web server and the proxy server need to support 
multiple authentication schemes setting to test the fallback feature.

The environment variables set inside spnegoTest are:

    WWW_REALM       The Kerberos realm the Web server belongs to
    WWW_KDC         The Kerberos KDC for the WWW_REALM
    WWW_URL         The URL to test against. It should be protected with
                    Negotiate and Basic authentication

    PROXY_REALM     The Kerberos realm the proxy server belongs to
    PROXY_KDC       The Kerberos KDC for the PROXY_REALM
    PROXY_URL       The URL to test against, Should be available to
                    anonymous request
    PROXY_PARA      The proxy server setting. The proxy server should
                    prompt for Negotiate and Basic authentication

    GOOD_PASS       Correct user/pass for Basic authentication
    GOOD_KPASS      Correct user/pass for Kerberos
    BAD_PASS        Wrong user/pass for Basic authentication
    BAD_KPASS       Wrong user/pass for Kerberos

    WWW_TAB         The keytab file for WWW_REALM
    PROXY_TAB       The keytab file for PROXY_REALM
    TAB_PATH        The standard keytab cache file path

    FILE_CONTENT    The content of URL expected

The values set in spnegoTest reflect a temporary testing environment,
where we use MS-Windows 2000 Advanced Server as the KDC server and Web 
server, and MS ISA 2000 Server as the proxy server.

In order to test the using of keytab cache, you need to get the keytab
files before starting the test. The pathname of the 2 keytab files (one
for the WWW_REALM, the other for the PROXY_REALM) should be set inside
the test script spnegoTest as WWW_TAB and PROXY_TAB respectively. During
the test process, they will be copied to the system recognized place
(TAB_PATH) in turn.

This is a manual step since on most systems the kerberos realm is setup
in krb5.conf, and you need a root privilege to edit the it to get the 2
ticket cache files. Normally, the process will look like:

    # edit the krb5.conf using $WWW_REALM
    kinit www_user_name
    cp $TAB_PATH $WWW_TAB
    # edit the krb5.conf using $PROXY_REALM
    kinit proxy_user_name
    cp $TAB_PATH $PROXY_TAB

Fortunately, you normally will only need to do this once in a day.

However, on MS-Windows platform, the kinit tool provided with the JRE 
has command options including realm, KDC, principal name, and password,
thus make it possible to generate the keytab files from a batch script.

Finally, you can run the test with

    $ bash spnegoTest || echo $?