README

Nginx module to use SPNEGO+GSSAPI+Kerberos for HTTP authentication
==================================================================
Testing
-------
Authentication has been tested with (at least) the following:
  Software
  Nginx             1.2.3
  Internet Explorer 8.0.7600.16385
  Firefox           10.0.6
  Chrome            20.0.1132.57
  Curl              7.19.5 (GSS-Negotiate), 7.27.0 (SPNEGO/fbopenssl)

The underlying kerberos library used for these tests was MIT KRB5 1.7

History
-------
Michael Shadle paid YoctoPetaBorg from RentACoder to develop this extension as
ngx_http_auth_sso_module.  Michael then renamed it to
ngx_http_auth_spnego_module.  This initial module provided spnego support using
Microsoft's sample spnegohelp files.  Since then, SPNEGO support has made its
way into various GSS/Kerberos libraries.

Various other people have contributed minor patches to make the extension work
in their environments.

Provenance
----------
The initial codebase was a fork of Apache's mod_auth_gss_krb5 0.0.5
(http://modgssapache.sf.net) with changes to support nginx.

Compilation
-----------
When compiling from source build as usual adding the --add-module option:

  ./configure --add-module=$PATH_TO_MODULE

inside top Nginx source directory.

Configuration
-------------
The module has following directives:

- auth_gss: "on"/"off", for ease of unsecuring while leaving other
  options in the config file,

- auth_gss_realm: what Kerberos realm name to use, for now only used to
  remove it from full user@realm.name,

- auth_gss_keytab: absolute path-name to keytab file containing service
  credentials,

- auth_gss_service_name: what service name to use when acquiring
  credentials. (TOFIX: HTTP but should be a list in case of some other
  browsers wanting perhaps khttp or http)

TOFIX: for now they are all merely location specific. i.e. no way to
specify main or per server defaults, except for ...

Examples
--------

... current "hardcodeds" ;-}

location /topsecret {
  auth_gss on;
  auth_gss_realm LOCALDOMAIN;
  auth_gss_keytab /etc/krb5.keytab;
  auth_gss_service_name HTTP;
}

Additional Information
----------------------
Generating a keytab with an HTTP SPN will be specific to your environment. As
with many things, ask your local administrators or try examples on Google until
you find something that works.