7 This module has been built as a replacement for the aging mod_auth_kerb.
8 Its aim is to use only GSSAPI calls and be as much as possible agnostic
9 of the actual mechanism used.
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.
25 To run tests, you also need:
27 * The Kerberos 5 Key-Distribution-Center (`krb5-kdc` package on Debian)
28 * [nss_wrapper](https://cwrap.org/nss_wrapper.html)
29 * [socket_wrapper](https://cwrap.org/socket_wrapper.html)
42 Apache authentication modules are usually configured per location, see the
43 [mod_authn_core](https://httpd.apache.org/docs/2.4/mod/mod_authn_core.html)
44 documentation for the common directives
46 ### Basic configuration
48 The simplest configuration scheme specifies just one directive, which is the
49 location of the keytab.
54 AuthName "GSSAPI Single Sign On Login"
55 GssapiCredStore keytab:/etc/httpd.keytab
59 Your Apache server need read access to the keytab configured.
60 If your Kerberos implementation does not support the credential store
61 extensions you can also simply set the KRB5_KTNAME environment variable in the
62 Apache init script and skip the GssapiCredStore option completely.
65 Configuration Directives
66 ------------------------
70 Forces the authentication attempt to fail if the connection is not being
79 Tries to map the client principal to a local name using the gss_localname()
80 call. This requires configuration in the /etc/krb5.conf file in order to allow
81 proper mapping for principals not in the default realm (for example a user
82 coming from a trusted realm).
83 See the 'auth_to_local' option in the [realms] section of krb5.conf(5)
85 When this options is used the resolved name is set in the REMOTE_USER variable
86 however the complete client principal name is also made available in the
93 ### GssapiConnectionBound
95 When using GSS mechanisms that require more than one round-trip to complete
96 authentication (like NTLMSSP) it is necessary to bind to the authentication to
97 the connection in order to keep the state between round-trips. With this option
98 enable incomplete context are store in the connection and retrieved on the next
99 request for continuation.
102 GssapiConnectionBound On
105 ### GssapiSignalPersistentAuth
106 For clients that make use of Persistent-Auth header, send the header according
107 to GssapiConnectionBound setting.
110 GssapiSignalPersistentAuth On
113 ### GssapiUseSessions
115 In order to avoid constant and costly re-authentication attempts for every
116 request, mod_auth_gssapi offers a cookie based session method to maintain
117 authentication across multiple requests. GSSAPI uses the mod_sessions module
118 to handle cookies so that module needs to be activated and configured.
119 GSSAPI uses a secured (encrypted + MAC-ed) payload to maintain state in the
120 session cookie. The session cookie lifetime depends on the lifetime of the
121 GSSAPI session established at authentication.
122 NOTE: It is important to correctly set the SessionCookieName option.
124 [mod_sessions](http://httpd.apache.org/docs/current/mod/mod_session.html)
125 documentation for more information.
130 SessionCookieName gssapi_session path=/private;httponly;secure;
135 When GssapiUseSessions is enabled a key use to encrypt and MAC the session
136 data will be automatically generated at startup, this means session data will
137 become unreadable if the server is restarted or multiple servers are used and
138 the client is load balanced from one to another. To obviate this problem the
139 admin can choose to install a permanent key in the configuration so that
140 session data remain accessible after a restart or by multiple servers
141 sharing the same key.
143 The key must be a base64 encoded raw key of 32 bytes of length.
146 GssapiSessionKey key:VGhpcyBpcyBhIDMyIGJ5dGUgbG9uZyBzZWNyZXQhISE=
151 The GssapiCredStore option allows to specify multiple credential related
152 options like keytab location, client_keytab location, ccache location etc.
155 GssapiCredStore keytab:/etc/httpd.keytab
156 GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
159 ### GssapiDelegCcacheDir
161 If delegation of credentials is desired credentials can be exported in a
162 private directory accessible by the Apache process.
163 The delegated credentials will be stored in a file named after the client
164 principal and the subprocess environment variable KRB5CCNAME will be set
165 to point to that file.
168 GssapiDelegCcacheDir /var/run/httpd/clientcaches
170 A user foo@EXAMPLE.COM delegating its credentials would cause the server to
171 create a ccache file named /var/run/httpd/clientcaches/foo@EXAMPLE.COM
174 ### GssapiUseS4U2Proxy
176 Enables the use of the s4u2Proxy Kerberos extension also known as
177 [constrained delegation](https://ssimo.org/blog/id_011.html)
178 This option allows an application running within Apache to operate on
179 behalf of the user against other servers by using the provided ticket
180 (subject to KDC authorization).
181 This options requires GssapiDelegCcacheDir to be set. The ccache will be
182 populated with the user's provided ticket which is later used as evidence
183 ticket by the application.
186 GssapiUseS4U2Proxy On
187 GssapiCredStore keytab:/etc/httpd.keytab
188 GssapiCredStore client_keytab:/etc/httpd.keytab
189 GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
190 GssapiDelegCcacheDir /var/run/httpd/clientcaches
192 **NOTE:** The client keytab is necessary to allow GSSAPI to initiate via keytab
193 on its own. If not present an external mechanism needs to kinit with the
194 keytab and store a ccache in the configured ccache file.
198 Allows the use of Basic Auth in conjunction with Negotiate.
199 If the browser fails to use Negotiate is will instead fallback to Basic and
200 the username and password will be used to try to acquire credentials in the
201 module via GSSAPI. If credentials are acquire successfully then they are
202 validated against the server's keytab.
204 - **Enable with:** GssapiBasicAuth On
205 - **Default:** GssapiBasicAuth Off
212 GssapiCredStore keytab:/etc/httpd/http.keytab
217 ### GssapiAllowedMech
219 List of allowed mechanisms. This is useful to restrict the mechanism that
220 can be used when credentials for multiple mechanisms are available.
221 By default no mechanism is set, this means all locally available mechanisms
222 are allowed. The recognized mechanism names are: krb5, iakerb, ntlmssp
225 GssapiAllowedMech krb5
226 GssapiAllowedMech ntlmssp
229 ### GssapiBasicAuthMech
231 List of mechanisms against which Basic Auth is attempted. This is useful to
232 restrict the mechanisms that can be used to attempt password auth.
233 By default no mechanism is set, this means all locally available mechanisms
234 are allowed, unless GssapiAllowedMech is set, in which case those are used.
235 GssapiBasicAuthMech always takes precedence over GssapiAllowedMech.
236 The recognized mechanism names are: krb5, iakerb, ntlmssp
239 GssapiBasicAuthMech krb5