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.
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.
92 When using this option you may also ant to set the Persistent-Auth header for
93 those clients that make use of it.
96 GssapiConnectionBound On
97 Header set Persistent-Auth "true"
100 ### GssapiUseSessions
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.
111 [mod_sessions](http://httpd.apache.org/docs/current/mod/mod_session.html)
112 documentation for more information.
117 SessionCookieName gssapi_session path=/private;httponly;secure;
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.
130 The key must be a base64 encoded raw key of 32 bytes of length.
133 GssapiSessionKey key:VGhpcyBpcyBhIDMyIGJ5dGUgbG9uZyBzZWNyZXQhISE=
138 The GssapiCredStore option allows to specify multiple credential related
139 options like keytab location, client_keytab location, ccache location etc.
142 GssapiCredStore keytab:/etc/httpd.keytab
143 GssapiCredStore ccache:FILE:/var/run/httpd/krb5ccache
146 ### GssapiDelegCcacheDir
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.
155 GssapiDelegCcacheDir /var/run/httpd/clientcaches
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
161 ### GssapiUseS4U2Proxy
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.
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
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.
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.
191 Enable with: GssapiBasicAuth On
192 Default: GssapiBasicAuth Off
199 GssapiCredStore keytab:/etc/httpd/http.keytab