README

   1 mod_auth_gssapi
   2 ===============
   3
   4 Intro
   5 -----
   6
   7 This module has been built as a replacement for the aging mod_auth_kerb.
   8 It's aim is to use only GSSAPI calls and be as much as possible agnostic
   9 of the actual mechanism used.
  10
  11 Dependencies
  12 ------------
  13
  14 A modern version of MIT's Krb5 distribution or any GSSAPI implementation
  15 that supports the [credential store
  16 extension](http://k5wiki.kerberos.org/wiki/Projects/Credential_Store_extensions)
  17 is necessary to achieve full functionality. Reduced functionality is
  18 provided without these extensions.
  19
  20 krb5 (>=1.11)
  21 Apache (>=2.4)
  22
  23 Installation
  24 ------------
  25
  26 ./configure
  27 make
  28 make install
  29
  30
  31 Configuration
  32 -------------
  33
  34 Apache authentication modules are usually configured per location, see the
  35 [mod_authn_core](https://httpd.apache.org/docs/2.4/mod/mod_authn_core.html)
  36 documentation for the common directives
  37
  38 ### Basic configuration
  39
  40 The simplest configuration scheme specifies just one directive, which is the
  41 location of the keytab.
  42
  43 #### Example
  44 <Location /private>
  45     AuthType GSSAPI
  46     AuthName "GSSAPI Single Sign On Login"
  47     GssapiCredStore keytab:/etc/httpd.keytab
  48     Require valid-user
  49 </Location>
  50
  51 Your Apache server need read access to the keytab configured.
  52 If your Kerberos implementation does not support the credential store
  53 extensions you can also simply set the KRB5_KTNAME environment variable in the
  54 Apache init script and skip the GssapiCredStore option completely.
  55
  56
  57 Configuration Directives
  58 ------------------------
  59
  60 ### GssapiSSLonly
  61
  62 Forces the authentication attempt to fail if the connection is not being
  63 established over TLS
  64
  65 Example:
  66     GssapiSSLonly On
  67
  68
  69 ### GssapiLocalName
  70
  71 Tries to map the client principal to a local name using the gss_localname()
  72 call. This requires configuration in the /etc/krb5.conf file in order to allow
  73 proper mapping for principals not in the default realm (for example a user
  74 coming from a trusted realm).
  75 See the 'auth_to_local' option in the [realms] section of krb5.conf(5)
  76
  77 When this options is used the resolved name is set in the REMOTE_USER variable
  78 however the complete client principal name is also made available in the
  79 GSS_NAME variable.
  80
  81 Example:
  82     GssapiLocalName on
  83
  84
  85 ### GssapiConnectionBound
  86
  87 When using GSS mechanisms that require more than one round-trip to complete
  88 authentication (like NTLMSSP) it is necessary to bind to the authentication to
  89 the connection in order to keep the state between round-trips. With this option
  90 enable incomplete context are store in the connection and retrieved on the next
  91 request for continuation.
  92 When using this option you may also ant to set the Persistent-Auth header for
  93 those clients that make use of it.
  94
  95 Example:
  96     GssapiConnectionBound On
  97     Header set Persistent-Auth "true"
  98
  99
 100 ### GssapiUseSessions
 101
 102 In order to avoid constant and costly re-authentication attempts for every
 103 request, mod_auth_gssapi offers a cookie based session method to maintain
 104 authentication across multiple requests. GSSAPI uses the mod_sessions module
 105 to handle cookies so that module needs to be activated and configured.
 106 GSSAPI uses a secured (encrypted + MAC-ed) payload to maintain state in the
 107 session cookie. The session cookie lifetime depends on the lifetime of the
 108 GSSAPI session established at authentication.
 109 NOTE: It is important to correctly set the SessionCookieName option.
 110 See the
 111 [mod_sessions](http://httpd.apache.org/docs/current/mod/mod_session.html)
 112 documentation for more information.
 113
 114 Example:
 115     GssapiUseSessions On
 116     Session On
 117     SessionCookieName gssapi_session path=/private;httponly;secure;
 118
 119
 120 ### GssapiSessionKey
 121
 122 When GssapiUseSessions is enabled a key use to encrypt and MAC the session
 123 data will be automatically generated at startup, this means session data will
 124 become unreadable if the server is restarted or multiple serves are used and
 125 the client is load balanced from one to another. To obviate this problem the
 126 admin can choose to install a permanent key in the configuration so that
 127 session data remain accessible after a restart or by multiple servers
 128 sharing the same key.
 129
 130 The key must be a base64 encoded raw key of 32 bytes of length.
 131
 132 Example:
 133     GssapiSessionKey key:VGhpcyBpcyBhIDMyIGJ5dGUgbG9uZyBzZWNyZXQhISE=
 134
 135
 136 ### GssapiCredStore
 137
 138 The GssapiCredStore option allows to specify multiple credential related
 139 options like keytab location, client_keytab location, ccache location etc.
 140
 141 Example:
 142     GssapiCredStore keytab:/etc/httpd.keytab
 143     GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
 144
 145
 146 ### GssapiDelegCcacheDir
 147
 148 If delegation of credentials is desired credentials can be exported in a
 149 private directory accessible by the Apache process.
 150 The delegated credentials will be stored in a file named after the client
 151 principal and the subprocess environment variable KRB5CCNAME will be set
 152 to point to that file.
 153
 154 Example:
 155     GssapiDelegCcacheDir /var/run/httpd/clientcaches
 156
 157
 158 A user foo@EXAMPLE.COM delegating its credentials would cause the server to
 159 create a ccache file named /var/run/httpd/clientcaches/foo@EXAMPLE.COM
 160
 161 ### GssapiUseS4U2Proxy
 162
 163 Enables the use of the s4u2Proxy Kerberos extension also known as
 164 [constrained delegation](https://ssimo.org/blog/id_011.html)
 165 This option allows an application running within Apache to operate on
 166 behalf of the user against other servers by using the provided ticket
 167 (subject to KDC authorization).
 168 This options requires GssapiDelegCcacheDir to be set. The ccache will be
 169 populated with the user's provided ticket which is later used as evidence
 170 ticket by the application.
 171
 172 Example:
 173     GssapiUseS4U2Proxy On
 174     GssapiCredStore keytab:/etc/httpd.keytab
 175     GssapiCredStore client_keytab:/etc/httpd.keytab
 176     GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
 177     GssapiDelegCcacheDir /var/run/httpd/clientcaches
 178
 179 NOTE: The client keytab is necessary to allow GSSAPI to initate via keytab
 180 on its own. If not present an external mechanism needs to kinit with the
 181 keytab and store a ccache in the configured ccache file.
 182
 183
 184 ### GssapiBasicAuth
 185 Allows the use of Basic Auth in conjunction with Negotiate.
 186 If the browser fails to use Negotiate is will instead fallback to Basic and
 187 the username and password will be used to try to acquire credentials in the
 188 module via GSSAPI. If credentials are acquire successfully then they are
 189 validated agaist the server's keytab.
 190
 191 Enable with: GssapiBasicAuth On
 192 Default: GssapiBasicAuth Off
 193
 194 Example:
 195 <Location /gssapi>
 196   AuthType GSSAPI
 197   AuthName "Login"
 198   GssapiBasicAuth On
 199   GssapiCredStore keytab:/etc/httpd/http.keytab
 200   Require valid-user
 201 </Location>