Introduction
Install
Configure
Credits
Other Resources
Project Site

SourceForge.net Logo

Configuration (v. 4.x)


Contents



Summary of Supported Directives


AuthType

For Kerberos authentication to work, AuthType must be set to one of the following:

  • KerberosV4
  • KerberosV5
This tells Apache and the browser which Kerberos protocol version to try to use to validate the user. This is the only option necessary for the module to be functional. You can append "SaveCredentials" to the end of the the KerberosV5 directive (ie: AuthType KerberosV5SaveCredentials) to enable credential cache saving capabilities. There is currently no SaveTickets tag-on for KerberosV4.


KrbAuthAuthoritative

This option takes one argument, which is either "on" or "off". It determines if mod_auth_kerb will allow other modules to try to authenticate the user after it fails to do so. The default is for this to be on.
Example: 

KrbAuthAuthoritative on


KrbAuthRealm

This option takes one argument, specifying the Kerberos realm to be used for authentication. This defaults to either the compiled in default realm, or the default realm taken from the local Kerberos configuration.
Example: 

KrbAuthRealm MIT.EDU


KrbLifetime

This option takes one argument, specifying the lifetime of the tickets. The number represents a different unit for Krb5 and Krb4. For KerberosV5, the number is in seconds. For KerberosV4, the number is in "5 minute intervals". In KerberosV5, it defaults to 30 minutes if SaveCredentials is turned on, or 5 minutes if it is not. KerberosV4 defaults to 5 minutes.
Example: 

KrbLifetime 300


KrbDefaultInstance

This option takes one argument, specifying the default instance if a user does not specify one. For instance, if you set it to root, then if a user entered "daniel" as their username, then it would authenticate against "daniel/root" (for KerberosV5). If this option is not specified, it defaults to "", in other words not touching the username that is submitted.
Example: 

KrbDefaultInstance root


KrbAnyInstance

This option takes one argument, which is either "on" or "off". It determines whether or not users are allowed to specify an instance with their username. If this option is turned off, then "whatever KrbDefaultInstance specifies, goes". You could use this to force users to only log in using their root instance. It is off by default.
Example: 

KrbAnyInstance on


KrbExpireReauth

This option takes one argument, which is either "on" or "off". It determines whether or not to make use of the Kerberos ticket expiring functionality. Either KRB5_SAVE_CREDENTIALS or KRB4_SAVE_TICKETS must have been defined at compile time for this option to be activated. It is off by default.
Example: 

KrbExpireReauth on


KrbAuthFailStatus

This option takes one argument, which is either "unauthorized" or "forbidden". It determines the behavior of a failed login attempt. Unauthorized is the default and is the standard "You are unauthorized" response that also triggers a browser to re-request your login/password pair. Forbidden, on the other hand, fails to a "you are forbidden to access this page" message and does not re-request the login/password pair. (or at least typically it does not, it is probably up to your browser)
Example: 

KrbAuthFailStatus forbidden


Krb4Srvtab

This option take one argument, specifying the path to the Kerberos V4 srvtab. KRB4 must have been defined at compile time for this option to be activated. It will simply use the "default srvtab" from Kerberos V4's configuration if this option is not specified.
Example: 

Krb4Srvtab /etc/mysrvtab


Krb4SaveTickets

This option takes one argument, which is either "on" or "off". It enables the ticket saving functionality. KRB4 and KRB4_SAVE_TICKETS must have been defined at compile time for this option to be activated. It is set to off by default.
Example: 

Krb4SaveTickets on


Krb5Keytab

This option takes one argument, specifying the location of the Kerberos V5 keytab file. KRB5 must have been defined at compile time for this option to be activated. By default, It will use the "default keytab" from Kerberos V5's config if it is not specified here.
Example: 

Krb5Keytab /etc/mykeytab


Krb5SaveCredentials

This option takes one argument, which is either "on" or "off". It will enable Kerberos V5 credential saving functionality. KRB5 and KRB5_SAVE_CREDENTIALS must be defined at compile time for this function to be available. The default is off. Setting this to on does the same thing as setting the AuthType to KerberosV5SaveCredentials.
Example: 

Krb5SaveCredentials on


Krb5Forwardable

This option takes one argument, which is either "on" of "off". It determines whether forwardable tickets are retrieved or not. KRB5 and KRB5_SAVE_CREDENTIALS must be defined at compile time for this function to be available. It is off by default.
Example: 

Krb5Forwardable on



Ticket Expiring Mode

Mod_auth_kerb can be configured to treat tickets just as they are treated on a workstation. In other words, you get a ticket with a lifetime of, say, 30 minutes for example, and after 30 minutes, you need to renew that ticket. What the ticket expiring mode does is it keeps the ticket file around, and does not overwrite it every time the user makes a request. Instead, it checks the file for the ticket granting ticket's lifetime, and if it has expired, it will require that the user re-issues their username and password. So basically, a user could hit a website, have to authenticate with their kerberos username and password, then assuming a ticket lifetime of maybe 15 minutes, could browse through the rest of the site (or at least what he/she is authorized to look at) until that 15 minutes is up, at which point the browser would be triggered to bring up the username/password login window (or whatever, depending on the browser).

This functionality is enabled by doing the following:

  1. At compile time, be sure to define KRB4 and/or KRB5 and their respective KRB4_SAVE_TICKETS and KRB5_SAVE_CREDENTIALS flags.
  2. In your access config you will need to specify "KrbExpireReauth on" and set one of the SaveTickets/SaveCredentials flags to on.
    Note: You =must= have one of SaveTickets or SaveCredentials turned on for this to work.

One thing to note is a problem with Internet Explorer and this functionality. A fix is hopefully in the works in the next major version.



Ticket File/Credential Cache Saving

Sometimes there is need to keep the ticket file or credential cache around after a user authenticates, normally for cgi scripts or for the ExpireReauth functionality described above. If you turn on Krb4SaveTickets or Krb5SaveCredentials, the tickets will be retrieved into a ticket file or credential cache that will not be removed. These files have the naming scheme:

  • V4: /tmp/apache_tkt_%s
  • V5: /tmp/krb5cc_%s
Where %s is the Kerberos username that was authenticated against. This works with the instance functionality as well, as it will name the file: /tmp/krb5cc_daniel.root if I authenticated as daniel/root. (it converts /'s to .'s) To utilize this functionality, you have have defined KRB5_SAVE_CREDENTIALS or KRB4_SAVE_TICKETS at compile time.

A CGI script can use these files by setting the KRB5CCNAME (v5) or KRBTKFILE (v4) environment variables to point to the filename as listed above. A sample script to use the KRB5CCNAME is here.



Other Notes

  • Reminder, you need to set the appropriate AllowOverride directive in your server access configuration so that a different AuthType will be allowed.
  • For the module to work with Kerberized browsers that understand Kerberos as a valid authentication type (Kerberized NCSA Mosaic), put the following in your server configuration: 
    BrowserMatch Mosaic use_kerberos_auth
  • A sample .htaccess file might look like: 
        AuthType KerberosV4
    AuthName "Kerberos Login"
    KrbAuthRealm KRB.NCSU.EDU
    require valid-user