com.sun.security.auth.module
Class Krb5LoginModule

java.lang.Object
  com.sun.security.auth.module.Krb5LoginModule

All Implemented Interfaces:

LoginModule

public class Krb5LoginModule
extends Object
implements LoginModule

This LoginModule authenticates users using Kerberos protocols.

The configuration entry for Krb5LoginModule has several options that control the authentication process and additions to the Subject's private credential set. Irrespective of these options, the Subject's principal set and private credentials set are updated only when commit is called. When commit is called, the KerberosPrincipal is added to the Subject's principal set and KerberosTicket is added to the Subject's private credentials.

If the configuration entry for KerberosLoginModule has the option storeKey set to true, then KerberosKey will also be added to the subject's private credentials. KerberosKey, the principal's key will be either obtained from the keytab or derived from user's password.

This LoginModule recognizes the doNotPrompt option. If set to true the user will not be prompted for the password.

The user can specify the location of the ticket cache by using the option ticketCache in the configuration entry.

The user can specify the keytab location by using the option keyTab in the configuration entry.

The principal name can be specified in the configuration entry by using the option principal. The principal name can either be a simple user name or a service name such as host/mission.eng.sun.com. The principal can also be set using the system property sun.security.krb5.principal. This property is checked during login. If this property is not set, then the principal name from the configuration is used. In the case where the principal property is not set and the principal entry also does not exist, the user is prompted for the name.

The following is a list of configuration options supported for Krb5LoginModule:

refreshKrb5Config:

Set this to true, if you want the configuration to be refreshed before the login method is called.

useTicketCache:

Set this to true, if you want the TGT to be obtained from the ticket cache. Set this option to false if you do not want this module to use the ticket cache. (Default is False). This module will search for the tickect cache in the following locations: For Windows 2000, it will use Local Security Authority (LSA) API to get the TGT. On Solaris and Linux it will look for the ticket cache in /tmp/krb5cc_uid where the uid is numeric user identifier. If the ticket cache is not available in either of the above locations, or if we are on a different Windows platform, it will look for the cache as {user.home}{file.separator}krb5cc_{user.name}. You can override the ticket cache location by using ticketCache

ticketCache:

Set this to the name of the ticket cache that contains user's TGT. If this is set, useTicketCache must also be set to true; Otherwise a configuration error will be returned.

renewTGT:

Set this to true, if you want to renew the TGT. If this is set, useTicketCache must also be set to true; otherwise a configuration error will be returned.

doNotPrompt:

Set this to true if you do not want to be prompted for the password if credentials can not be obtained from the cache or keytab.(Default is false) If set to true authentication will fail if credentials can not be obtained from the cache or keytab.

useKeyTab:

Set this to true if you want the module to get the principal's key from the the keytab.(default value is False) If keyatb is not set then the module will locate the keytab from the Kerberos configuration file.

If it is not specifed in the Kerberos configuration file then it will look for the file {user.home}{file.separator}krb5.keytab.

keyTab:

Set this to the file name of the keytab to get principal's secret key.

storeKey:

Set this to true to if you want the principal's key to be stored in the Subject's private credentials.

principal:

The name of the principal that should be used. The principal can be a simple username such as "testuser" or a service name such as "host/testhost.eng.sun.com". You can use the principal option to set the principal when there are credentials for multiple principals in the keyTab or when you want a specific ticket cache only. The principal can also be set using the system property sun.security.krb5.principal. In addition, if this system property is defined, then it will be used. If this property is not set, then the principal name from the configuration will be used.

This LoginModule also recognizes the following additional Configuration options that enable you to share username and passwords across different authentication modules:

    useFirstPass   if, true, this LoginModule retrieves the
                   username and password from the module's shared state,
                   using "javax.security.auth.login.name" and
                   "javax.security.auth.login.password" as the respective
                   keys. The retrieved values are used for authentication.
                   If authentication fails, no attempt for a retry
                   is made, and the failure is reported back to the
                   calling application.

    tryFirstPass   if, true, this LoginModule retrieves the
                   the username and password from the module's shared
                   state using "javax.security.auth.login.name" and
                   "javax.security.auth.login.password" as the respective
                   keys.  The retrieved values are used for
                   authentication.
                   If authentication fails, the module uses the
                   CallbackHandler to retrieve a new username
                   and password, and another attempt to authenticate
                   is made. If the authentication fails, 
                   the failure is reported back to the calling application

    storePass      if, true, this LoginModule stores the username and
                   password obtained from the CallbackHandler in the
                   modules shared state, using 
                   "javax.security.auth.login.name" and 
                   "javax.security.auth.login.password" as the respective
                   keys.  This is not performed if existing values already
                   exist for the username and password in the shared
                   state, or if authentication fails.

    clearPass     if, true, this LoginModule clears the
                  username and password stored in the module's shared
                  state  after both phases of authentication
                  (login and commit)  have completed.
 

Examples of some configuration values for Krb5LoginModule in JAAS config file and the results are:

doNotPrompt=true;

This is an illegal combination since useTicketCache is not set and the user can not be prompted for the password.

ticketCache = < filename >;

This is an illegal combination since useTicketCache is not set to true and the ticketCache is set. A configuration error will occur.

renewTGT=true;

This is an illegal combination since useTicketCache is not set to true and renewTGT is set. A configuration error will occur.

storeKey=true useTicketCache = true doNotPrompt=true;;

This is an illegal combination since storeKey is set to true but the key can not be obtained either by prompting the user or from the keytab.A configuration error will occur.

keyTab = < filename > doNotPrompt=true ;

This is an illegal combination since useKeyTab is not set to true and the keyTab is set. A configuration error will occur.

debug=true

Prompt the user for the principal name and the password. Use the authentication exchange to get TGT from the KDC and populate the Subject with the principal and TGT. Output debug messages.

useTicketCache = true doNotPrompt=true;

Check the default cache for TGT and populate the Subject with the principal and TGT. If the TGT is not available, do not prompt the user, instead fail the authentication.

principal=< name >useTicketCache = true doNotPrompt=true;

Get the TGT from the default cache for the principal and populate the Subject's principal and private creds set. If ticket cache is not available or does not contain the principal's TGT authentication will fail.

useTicketCache = true ticketCache=< file name >useKeyTab = true keyTab=< keytab filename > principal = < principal name > doNotPrompt=true;

Search the cache for the principal's TGT. If it is not available use the key in the keytab to perform authentication exchange with the KDC and acquire the TGT. The Subject will be populated with the principal and the TGT. If the key is not available or valid then authentication will fail.

useTicketCache = true ticketCache=< file name >

The TGT will be obtained from the cache specified. The Kerberos principal name used will be the principal name in the Ticket cache. If the TGT is not available in the ticket cache the user will be prompted for the principal name and the password. The TGT will be obtained using the authentication exchange with the KDC. The Subject will be populated with the TGT.

useKeyTab = true keyTab=< keytab filename > principal= < principal name > storeKey=true;

The key for the principal will be retrieved from the keytab. If the key is not available in the keytab the user will be prompted for the principal's password. The Subject will be populated with the principal's key either from the keytab or derived from the password entered.

useKeyTab = true keyTab=< keytabname > storeKey=true doNotPrompt=true;

The user will be prompted for the service principal name. If the principal's longterm key is available in the keytab , it will be added to the Subject's private credentials. An authentication exchange will be attempted with the principal name and the key from the Keytab. If successful the TGT will be added to the Subject's private credentials set. Otherwise the authentication will fail.

useKeyTab = true keyTab=< file name > storeKey=true principal= < principal name > useTicketCache=true ticketCache=< file name >;

The principal's key will be retrieved from the keytab and added to the Subject's private credentials. If the key is not available, the user will be prompted for the password; the key derived from the password will be added to the Subject's private credentials set. The client's TGT will be retrieved from the ticket cache and added to the Subject's private credentials. If the TGT is not available in the ticket cache, it will be obtained using the authentication exchange and added to the Subject's private credentials.

Constructor Summary

Krb5LoginModule()

Method Summary

boolean	abort() This method is called if the LoginContext's overall authentication failed.
boolean	commit() This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded).
void	initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options) Initialize this LoginModule.
boolean	login() Authenticate the user
boolean	logout() Logout the user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Krb5LoginModule

public Krb5LoginModule()

Method Detail

initialize

public void initialize(Subject subject,
                       CallbackHandler callbackHandler,
                       Map<String,?> sharedState,
                       Map<String,?> options)

Initialize this LoginModule.

Specified by:

initialize in interface LoginModule

Parameters:

subject - the Subject to be authenticated.

callbackHandler - a CallbackHandler for communication with the end user (prompting for usernames and passwords, for example).

sharedState - shared LoginModule state.

options - options specified in the login Configuration for this particular LoginModule.

login

public boolean login()
              throws LoginException

Authenticate the user

Specified by:

login in interface LoginModule

Returns:

true in all cases since this LoginModule should not be ignored.

Throws:

FailedLoginException - if the authentication fails.

LoginException - if this LoginModule is unable to perform the authentication.

commit

public boolean commit()
               throws LoginException

This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded).

If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the login method), then this method associates a Krb5Principal with the Subject located in the LoginModule. It adds Kerberos Credentials to the the Subject's private credentials set. If this LoginModule's own authentication attempted failed, then this method removes any state that was originally saved.

Specified by:

commit in interface LoginModule

Returns:

true if this LoginModule's own login and commit attempts succeeded, or false otherwise.

Throws:

LoginException - if the commit fails.

abort

public boolean abort()
              throws LoginException

This method is called if the LoginContext's overall authentication failed. (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed).

If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the login and commit methods), then this method cleans up any state that was originally saved.

Specified by:

abort in interface LoginModule

Returns:

false if this LoginModule's own login and/or commit attempts failed, and true otherwise.

Throws:

LoginException - if the abort fails.

logout

public boolean logout()
               throws LoginException

Logout the user.

This method removes the Krb5Principal that was added by the commit method.

Specified by:

logout in interface LoginModule

Returns:

true in all cases since this LoginModule should not be ignored.

Throws:

LoginException - if the logout fails.