com.ibm.itim.apps.jaas.callback
Class PlatformCallbackHandler

java.lang.Object
  |
  +--com.ibm.itim.apps.jaas.callback.PlatformCallbackHandler

All Implemented Interfaces:

javax.security.auth.callback.CallbackHandler

public class PlatformCallbackHandler

extends java.lang.Object

implements javax.security.auth.callback.CallbackHandler

Default JAAS authentication callback handler for the identity platform. This handler supports the callbacks required by the identity platform. This handler, or a handler that also supports the required callbacks, must be used to authentication to the platform. These required callbacks are the javax.security.auth.callback.NameCallback, javax.security.auth.callback.PasswordCallback, TenantCallback, ChallengeResponseCallback, and LanguageCallback. In a single-tenant deployment the TenantCallback does not need to return a value, an empty string is acceptable. The ChallengeResponseCallback and LanguageCallback need only return values if the authenticating user has forgotten their password. However, since the CallbackHandler interface does not provide for selective handling, all Callbacks must be supported even if they do not provide values.

An additional callback may be issued if the platform context information is not provided as properties to the application in the security file. The LoginModule requires context information so that it can communicate with the platform to perform the authentication.The properties needed in the security file are:

url - URL of the platform

factory - JNDI initial context factory for looking up EJBs.

name - User Id to use to authenticate to the platform for login. Note: this is not the usre being authenticated, but a priveledged EJB user for connecting to the login EJB.

pswd - Password of the principal.

If these properties are not set in the file, the PlatformCallback will be issued to the handler and it must be fulfilled. See setPlatformContext() for setting the PlatformContext on this handler.

See Also:

TenantCallback, ChallengeResponseCallback, PlatformContext

Constructor Summary

PlatformCallbackHandler(java.lang.String userID, java.util.Locale locale)
Constructs the handler with a user id and locale.

PlatformCallbackHandler(java.lang.String userID, java.lang.String password)
Constructs the handler with a user id and password.

PlatformCallbackHandler(java.lang.String tenantID, java.lang.String userID, java.util.Locale locale)
Constructs the handler with a user id, locale, and tenant id.

PlatformCallbackHandler(java.lang.String tenantID, java.lang.String userID, java.lang.String password)
Constructs the handler with a user id, password, and tenant id.

Method Summary

java.util.Map	getChallenges() Deprecated. Use getUserChallenges() instead
int	getRemainingAttempts() Returns the number of unsuccessful login attempts remain before the user's account is suspended.
java.util.Map	getUserChallenges() Retrieves the required challenges to be fulfilled by client for authentication without password.
void	handle(javax.security.auth.callback.Callback[] callbacks) Handles the required callbacks.
void	setPlatformContext(PlatformContext context) Sets the platform context.
void	setResponses(java.util.Map responses) Changes the responses to the challenges for the user.

Methods inherited from class java.lang.Object

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

Constructor Detail

PlatformCallbackHandler

public PlatformCallbackHandler(java.lang.String userID,
                               java.lang.String password)

Constructs the handler with a user id and password.

Parameters:

userID - ID representing authenticating user.

password - Private password of the user.

PlatformCallbackHandler

public PlatformCallbackHandler(java.lang.String tenantID,
                               java.lang.String userID,
                               java.lang.String password)

Constructs the handler with a user id, password, and tenant id. This constructor is to be used in multi-tenant deployments.

Parameters:

tenantID - ID representing the tenant of the user.

userID - ID representing authenticating user.

password - Private password of the user.

PlatformCallbackHandler

public PlatformCallbackHandler(java.lang.String userID,
                               java.util.Locale locale)

Constructs the handler with a user id and locale. This constructor is meant to be used when attempting authentication through the challenge and response process.

Parameters:

userID - ID representing authenticating user.

locale - Locale of the user.

PlatformCallbackHandler

public PlatformCallbackHandler(java.lang.String tenantID,
                               java.lang.String userID,
                               java.util.Locale locale)

Constructs the handler with a user id, locale, and tenant id. This constructor is to be used in multi-tenant deployments when attempting to authenticate using the challenge and response process.

Parameters:

tenantID - ID representing the tenant of the user.

userID - ID representing authenticating user.

locale - Locale of the user.

Method Detail

setPlatformContext

public void setPlatformContext(PlatformContext context)

Sets the platform context. This is required so that the login can be made against the correct platform. This can optionally be set with properties the security file for this application. The benefit of using this method is the ability to reuse the same PlatformContext object on subsequent calls reducing overhead. The properties needed in the security file are:

url - URL of the platform

factory - JNDI initial context factory for looking up EJBs.

principal - User Id to use to authenticate to the platform for login. Note: this is not the usre being authenticated, but a priveledged EJB user for connecting to the login EJB.

pswd - Password of the principal.

Parameters:

context - PlatformContext to connect with.

getChallenges

public java.util.Map getChallenges()
                            throws java.rmi.RemoteException,
                                   ApplicationException,
                                   AuthenticationException

Deprecated. Use getUserChallenges() instead

Retrieves the required challenges to be fulfilled by client for authentication without password. The challenges will be returned in a Map where the keys will be the challenges. The values of the map are the responses. To set the reponses, update the map with the responses and call setResponses(). The client must not alter the challenges (keys) in any way or the authentication attempt will fail. Note: The platform context must be set prior to this call as the platform will be providing the challenges.

Returns:

Map of challenges (keys) and responses (values). The responses will be null initially. The client must fill the values with the appropriate responses. The responses must be Strings. Note: If there are no challenges defined for the specified userid, an empty Map will be returned.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to locate user.

AuthenticationException - Thrown if unable to retrieve challenges.

getUserChallenges

public java.util.Map getUserChallenges()
                                throws java.rmi.RemoteException,
                                       ApplicationException,
                                       javax.security.auth.login.FailedLoginException

Retrieves the required challenges to be fulfilled by client for authentication without password. The challenges will be returned in a Map where the keys will be the challenges. The values of the map are the responses. To set the reponses, update the map with the responses and call setResponses(). The client must not alter the challenges (keys) in any way or the authentication attempt will fail. Note: The platform context must be set prior to this call as the platform will be providing the challenges.

Returns:

Map of challenges (keys) and responses (values). The responses will be null initially. The client must fill the values with the appropriate responses. The responses must be Strings. Note: If there are no challenges defined for the specified userid, an empty Map will be returned.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to locate user.

javax.security.auth.login.FailedLoginException - Thrown if unable to retrieve challenges.

Since:

4.6

getRemainingAttempts

public int getRemainingAttempts()
                         throws java.rmi.RemoteException,
                                ApplicationException

Returns the number of unsuccessful login attempts remain before the user's account is suspended.

Returns:

Number of remaining attempts. -1 is returned if there are no bounds on the number of attempts that are allowed.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to locate user.

setResponses

public void setResponses(java.util.Map responses)

Changes the responses to the challenges for the user.

Parameters:

responses - Map of challenges and the corresponding responses for the user.The challenges must be the same as the ones obtained from the getChallenges() call.

handle

public void handle(javax.security.auth.callback.Callback[] callbacks)
            throws java.io.IOException,
                   javax.security.auth.callback.UnsupportedCallbackException

Handles the required callbacks.

Specified by:

handle in interface javax.security.auth.callback.CallbackHandler

Parameters:

callbacks - Callback[] of authentication callbacks to be handled.

Throws:

javax.security.auth.callback.UnsupportedCallbackException - Thrown if a callback is passed to the handler it does not support.

java.io.IOException