X-Git-Url: http://www.project-moonshot.org/gitweb/?p=mod_auth_gssapi.git;a=blobdiff_plain;f=README;h=3851f923df201932f160b5435b455be279a6a7ca;hp=c31eceb7aae744cb1841ea5e596ae933ba0053fb;hb=7f11db955b8440668fc806b4203f584bb44f58c1;hpb=4b6ed2bfeeb912272e57fe9365cb175fd06ed6b0

diff --git a/README b/README
index c31eceb..3851f92 100644
--- a/README
+++ b/README
@@ -1,3 +1,266 @@
+mod_auth_gssapi
+===============
+
+Intro
+-----
+
 This module has been built as a replacement for the aging mod_auth_kerb.
-It's aim is to use only GSSAPI calls and be as much as possible agnostic
+Its aim is to use only GSSAPI calls and be as much as possible agnostic
 of the actual mechanism used.
+
+Dependencies
+------------
+
+A modern version of MIT's Krb5 distribution or any GSSAPI implementation
+that supports the [credential store
+extension](http://k5wiki.kerberos.org/wiki/Projects/Credential_Store_extensions)
+is necessary to achieve full functionality. Reduced functionality is
+provided without these extensions.
+
+    krb5 (>=1.11)
+    Apache (>=2.4)
+
+### Tests
+
+To run tests, you also need:
+
+* The Kerberos 5 Key-Distribution-Center (`krb5-kdc` package on Debian)
+* [nss_wrapper](https://cwrap.org/nss_wrapper.html)
+* [socket_wrapper](https://cwrap.org/socket_wrapper.html)
+
+Installation
+------------
+
+    ./configure
+    make
+    make install
+
+
+Configuration
+-------------
+
+Apache authentication modules are usually configured per location, see the
+[mod_authn_core](https://httpd.apache.org/docs/2.4/mod/mod_authn_core.html)
+documentation for the common directives
+
+### Basic configuration
+
+The simplest configuration scheme specifies just one directive, which is the
+location of the keytab.
+
+#### Example
+    <Location /private>
+        AuthType GSSAPI
+        AuthName "GSSAPI Single Sign On Login"
+        GssapiCredStore keytab:/etc/httpd.keytab
+        Require valid-user
+    </Location>
+
+Your Apache server need read access to the keytab configured.
+If your Kerberos implementation does not support the credential store
+extensions you can also simply set the KRB5_KTNAME environment variable in the
+Apache init script and skip the GssapiCredStore option completely.
+
+
+Configuration Directives
+------------------------
+
+### GssapiSSLonly
+
+Forces the authentication attempt to fail if the connection is not being
+established over TLS
+
+#### Example
+    GssapiSSLonly On
+
+
+### GssapiLocalName
+
+Tries to map the client principal to a local name using the gss_localname()
+call. This requires configuration in the /etc/krb5.conf file in order to allow
+proper mapping for principals not in the default realm (for example a user
+coming from a trusted realm).
+See the 'auth_to_local' option in the [realms] section of krb5.conf(5)
+
+When this options is used the resolved name is set in the REMOTE_USER variable
+however the complete client principal name is also made available in the
+GSS_NAME variable.
+
+#### Example
+    GssapiLocalName on
+
+
+### GssapiConnectionBound
+
+When using GSS mechanisms that require more than one round-trip to complete
+authentication (like NTLMSSP) it is necessary to bind to the authentication to
+the connection in order to keep the state between round-trips. With this option
+enable incomplete context are store in the connection and retrieved on the next
+request for continuation.
+
+#### Example
+    GssapiConnectionBound On
+
+
+### GssapiSignalPersistentAuth
+For clients that make use of Persistent-Auth header, send the header according
+to GssapiConnectionBound setting.
+
+#### Example
+    GssapiSignalPersistentAuth On
+
+
+### GssapiUseSessions
+
+In order to avoid constant and costly re-authentication attempts for every
+request, mod_auth_gssapi offers a cookie based session method to maintain
+authentication across multiple requests. GSSAPI uses the mod_sessions module
+to handle cookies so that module needs to be activated and configured.
+GSSAPI uses a secured (encrypted + MAC-ed) payload to maintain state in the
+session cookie. The session cookie lifetime depends on the lifetime of the
+GSSAPI session established at authentication.
+NOTE: It is important to correctly set the SessionCookieName option.
+See the
+[mod_sessions](http://httpd.apache.org/docs/current/mod/mod_session.html)
+documentation for more information.
+
+#### Example
+    GssapiUseSessions On
+    Session On
+    SessionCookieName gssapi_session path=/private;httponly;secure;
+
+
+### GssapiSessionKey
+
+When GssapiUseSessions is enabled a key use to encrypt and MAC the session
+data will be automatically generated at startup, this means session data will
+become unreadable if the server is restarted or multiple servers are used and
+the client is load balanced from one to another. To obviate this problem the
+admin can choose to install a permanent key in the configuration so that
+session data remain accessible after a restart or by multiple servers
+sharing the same key.
+
+The key must be a base64 encoded raw key of 32 bytes of length.
+
+#### Example
+    GssapiSessionKey key:VGhpcyBpcyBhIDMyIGJ5dGUgbG9uZyBzZWNyZXQhISE=
+
+
+### GssapiCredStore
+
+The GssapiCredStore option allows to specify multiple credential related
+options like keytab location, client_keytab location, ccache location etc.
+
+#### Example
+    GssapiCredStore keytab:/etc/httpd.keytab
+    GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
+
+
+### GssapiDelegCcacheDir
+
+If delegation of credentials is desired credentials can be exported in a
+private directory accessible by the Apache process.
+The delegated credentials will be stored in a file named after the client
+principal and the subprocess environment variable KRB5CCNAME will be set
+to point to that file.
+
+#### Example
+    GssapiDelegCcacheDir /var/run/httpd/clientcaches
+
+A user foo@EXAMPLE.COM delegating its credentials would cause the server to
+create a ccache file named /var/run/httpd/clientcaches/foo@EXAMPLE.COM
+
+
+### GssapiUseS4U2Proxy
+
+Enables the use of the s4u2Proxy Kerberos extension also known as
+[constrained delegation](https://ssimo.org/blog/id_011.html)
+This option allows an application running within Apache to operate on
+behalf of the user against other servers by using the provided ticket
+(subject to KDC authorization).
+This options requires GssapiDelegCcacheDir to be set. The ccache will be
+populated with the user's provided ticket which is later used as evidence
+ticket by the application.
+
+#### Example
+    GssapiUseS4U2Proxy On
+    GssapiCredStore keytab:/etc/httpd.keytab
+    GssapiCredStore client_keytab:/etc/httpd.keytab
+    GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
+    GssapiDelegCcacheDir /var/run/httpd/clientcaches
+
+**NOTE:** The client keytab is necessary to allow GSSAPI to initiate via keytab
+on its own. If not present an external mechanism needs to kinit with the
+keytab and store a ccache in the configured ccache file.
+
+
+### GssapiBasicAuth
+Allows the use of Basic Auth in conjunction with Negotiate.
+If the browser fails to use Negotiate is will instead fallback to Basic and
+the username and password will be used to try to acquire credentials in the
+module via GSSAPI. If credentials are acquire successfully then they are
+validated against the server's keytab.
+
+- **Enable with:** GssapiBasicAuth On
+- **Default:** GssapiBasicAuth Off
+
+#### Example
+    <Location /gssapi>
+      AuthType GSSAPI
+      AuthName "Login"
+      GssapiBasicAuth On
+      GssapiCredStore keytab:/etc/httpd/http.keytab
+      Require valid-user
+    </Location>
+
+
+### GssapiAllowedMech
+
+List of allowed mechanisms. This is useful to restrict the mechanism that
+can be used when credentials for multiple mechanisms are available.
+By default no mechanism is set, this means all locally available mechanisms
+are allowed.  The recognized mechanism names are: krb5, iakerb, ntlmssp
+
+#### Example
+    GssapiAllowedMech krb5
+    GssapiAllowedMech ntlmssp
+
+
+### GssapiBasicAuthMech
+
+List of mechanisms against which Basic Auth is attempted. This is useful to
+restrict the mechanisms that can be used to attempt password auth.
+By default no mechanism is set, this means all locally available mechanisms
+are allowed, unless GssapiAllowedMech is set, in which case those are used.
+GssapiBasicAuthMech always takes precedence over GssapiAllowedMech.
+The recognized mechanism names are: krb5, iakerb, ntlmssp
+
+#### Example
+    GssapiBasicAuthMech krb5
+
+
+#### GssapiNameAttributes
+
+Enables the module to source Name Attributes from the client name
+(authorization data associated with the established context) and exposes them
+as environment variables.
+
+Value format: ENV_VAR_NAME ATTRIBUTE_NAME
+
+This option can be specified multiple times, once for each attribute to expose.
+The Special value "json" is used to expose all attributes in a json formatted
+string via the special environment variable GSS_NAME_ATTRS_JSON
+The environment variable GSS_NAME_ATTR_ERROR is set with the Gssapi returned
+error string in case the inquire name function fails to retrieve attributes,
+and with the string "0 attributes found", if no attributes are set.
+
+Note: These variables are NOT saved in the session data stored in the cookie so they
+are available only on the first authenticated request when GssapiUseSessions is
+used.
+
+Note: It is recommended but not required to use only capital letters and underscores
+for environment variable names.
+
+#### Example
+    GssapiNameAttributes json
+    GssapiNameAttributes RADIUS_NAME urn:ietf:params:gss:radius-attribute_1