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
  93 Example:
  94     GssapiConnectionBound On
  95
  96
  97 ### GssapiSignalPersistentAuth
  98 For clients that make use of Persistent-Auth header, send the header according
  99 to GssapiConnectionBound setting.
 100
 101 Example:
 102     GssapiSignalPersistentAuth On
 103
 104
 105 ### GssapiUseSessions
 106
 107 In order to avoid constant and costly re-authentication attempts for every
 108 request, mod_auth_gssapi offers a cookie based session method to maintain
 109 authentication across multiple requests. GSSAPI uses the mod_sessions module
 110 to handle cookies so that module needs to be activated and configured.
 111 GSSAPI uses a secured (encrypted + MAC-ed) payload to maintain state in the
 112 session cookie. The session cookie lifetime depends on the lifetime of the
 113 GSSAPI session established at authentication.
 114 NOTE: It is important to correctly set the SessionCookieName option.
 115 See the
 116 [mod_sessions](http://httpd.apache.org/docs/current/mod/mod_session.html)
 117 documentation for more information.
 118
 119 Example:
 120     GssapiUseSessions On
 121     Session On
 122     SessionCookieName gssapi_session path=/private;httponly;secure;
 123
 124
 125 ### GssapiSessionKey
 126
 127 When GssapiUseSessions is enabled a key use to encrypt and MAC the session
 128 data will be automatically generated at startup, this means session data will
 129 become unreadable if the server is restarted or multiple serves are used and
 130 the client is load balanced from one to another. To obviate this problem the
 131 admin can choose to install a permanent key in the configuration so that
 132 session data remain accessible after a restart or by multiple servers
 133 sharing the same key.
 134
 135 The key must be a base64 encoded raw key of 32 bytes of length.
 136
 137 Example:
 138     GssapiSessionKey key:VGhpcyBpcyBhIDMyIGJ5dGUgbG9uZyBzZWNyZXQhISE=
 139
 140
 141 ### GssapiCredStore
 142
 143 The GssapiCredStore option allows to specify multiple credential related
 144 options like keytab location, client_keytab location, ccache location etc.
 145
 146 Example:
 147     GssapiCredStore keytab:/etc/httpd.keytab
 148     GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
 149
 150
 151 ### GssapiDelegCcacheDir
 152
 153 If delegation of credentials is desired credentials can be exported in a
 154 private directory accessible by the Apache process.
 155 The delegated credentials will be stored in a file named after the client
 156 principal and the subprocess environment variable KRB5CCNAME will be set
 157 to point to that file.
 158
 159 Example:
 160     GssapiDelegCcacheDir /var/run/httpd/clientcaches
 161
 162
 163 A user foo@EXAMPLE.COM delegating its credentials would cause the server to
 164 create a ccache file named /var/run/httpd/clientcaches/foo@EXAMPLE.COM
 165
 166 ### GssapiUseS4U2Proxy
 167
 168 Enables the use of the s4u2Proxy Kerberos extension also known as
 169 [constrained delegation](https://ssimo.org/blog/id_011.html)
 170 This option allows an application running within Apache to operate on
 171 behalf of the user against other servers by using the provided ticket
 172 (subject to KDC authorization).
 173 This options requires GssapiDelegCcacheDir to be set. The ccache will be
 174 populated with the user's provided ticket which is later used as evidence
 175 ticket by the application.
 176
 177 Example:
 178     GssapiUseS4U2Proxy On
 179     GssapiCredStore keytab:/etc/httpd.keytab
 180     GssapiCredStore client_keytab:/etc/httpd.keytab
 181     GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
 182     GssapiDelegCcacheDir /var/run/httpd/clientcaches
 183
 184 NOTE: The client keytab is necessary to allow GSSAPI to initate via keytab
 185 on its own. If not present an external mechanism needs to kinit with the
 186 keytab and store a ccache in the configured ccache file.
 187
 188
 189 ### GssapiBasicAuth
 190 Allows the use of Basic Auth in conjunction with Negotiate.
 191 If the browser fails to use Negotiate is will instead fallback to Basic and
 192 the username and password will be used to try to acquire credentials in the
 193 module via GSSAPI. If credentials are acquire successfully then they are
 194 validated agaist the server's keytab.
 195
 196 Enable with: GssapiBasicAuth On
 197 Default: GssapiBasicAuth Off
 198
 199 Example:
 200 <Location /gssapi>
 201   AuthType GSSAPI
 202   AuthName "Login"
 203   GssapiBasicAuth On
 204   GssapiCredStore keytab:/etc/httpd/http.keytab
 205   Require valid-user
 206 </Location>
 207
 208
 209 ### GssapiAllowedMech
 210
 211 List of allowed mechanisms. This is useful to restrict the mechanism that
 212 can be used when credentials for multiple mechanisms are available.
 213 By default no mechanism is set, this means all locally available mechanisms
 214 are allowed.  The recognized mechanism names are: krb5, iakerb, ntlmssp
 215
 216 Example:
 217     GssapiAllowedMech krb5
 218     GssapiAllowedMech ntlmssp
 219
 220
 221 ### GssapiBasicAuthMech
 222
 223 List of mechanisms against which Basic Auth is attempted. This is useful to
 224 restrict the mechanisms that can be used to attaempt password auth.
 225 By default no mechanism is set, this means all locally available mechanisms
 226 are allowed, unless GssapiAllowedMech is set, in which case those are used.
 227 GssapiBasicAuthMech always takes precendence over GssapiAllowedMech.
 228 The recognized mechanism names are: krb5, iakerb, ntlmssp
 229
 230 Example:
 231     GssapiBasicAuthMech krb5