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.
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
38 ### Basic configuration
40 The simplest configuration scheme specifies just one directive, which is the
41 location of the keytab.
46 AuthName "GSSAPI Single Sign On Login"
47 GssapiCredStore keytab:/etc/httpd.keytab
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.
57 Configuration Directives
58 ------------------------
62 Forces the authentication attempt to fail if the connection is not being
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)
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
85 ### GssapiConnectionBound
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.
94 GssapiConnectionBound On
97 ### GssapiSignalPersistentAuth
98 For clients that make use of Persistent-Auth header, send the header according
99 to GssapiConnectionBound setting.
102 GssapiSignalPersistentAuth On
105 ### GssapiUseSessions
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.
116 [mod_sessions](http://httpd.apache.org/docs/current/mod/mod_session.html)
117 documentation for more information.
122 SessionCookieName gssapi_session path=/private;httponly;secure;
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 servers 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.
135 The key must be a base64 encoded raw key of 32 bytes of length.
138 GssapiSessionKey key:VGhpcyBpcyBhIDMyIGJ5dGUgbG9uZyBzZWNyZXQhISE=
143 The GssapiCredStore option allows to specify multiple credential related
144 options like keytab location, client_keytab location, ccache location etc.
147 GssapiCredStore keytab:/etc/httpd.keytab
148 GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
151 ### GssapiDelegCcacheDir
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.
160 GssapiDelegCcacheDir /var/run/httpd/clientcaches
162 A user foo@EXAMPLE.COM delegating its credentials would cause the server to
163 create a ccache file named /var/run/httpd/clientcaches/foo@EXAMPLE.COM
166 ### GssapiUseS4U2Proxy
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.
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
184 **NOTE:** The client keytab is necessary to allow GSSAPI to initiate 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.
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 against the server's keytab.
196 - **Enable with:** GssapiBasicAuth On
197 - **Default:** GssapiBasicAuth Off
204 GssapiCredStore keytab:/etc/httpd/http.keytab
209 ### GssapiAllowedMech
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
217 GssapiAllowedMech krb5
218 GssapiAllowedMech ntlmssp
221 ### GssapiBasicAuthMech
223 List of mechanisms against which Basic Auth is attempted. This is useful to
224 restrict the mechanisms that can be used to attempt 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 precedence over GssapiAllowedMech.
228 The recognized mechanism names are: krb5, iakerb, ntlmssp
231 GssapiBasicAuthMech krb5