gov.va.med.vistalink.security.VistaLoginModule ICR (5225)

Name

Value

NUMBER

5225

IA #

5225

DATE CREATED

2008/07/01

CUSTODIAL PACKAGE

VISTALINK SECURITY

USAGE

Supported

TYPE

Other

DBIC APPROVAL STATUS

APPROVED

NAME

gov.va.med.vistalink.security.VistaLoginModule

GENERAL DESCRIPTION

public final class VistaLoginModule extends
java.lang.Object implements javax.security.auth.spi.LoginModule:

VistaLoginModule is a JAAS-compliant LoginModule to log users on to a Vista
system. An application never needs to access the VistaLoginModule class
directly. Rather, as a JAAS login module, its methods are invoked indirectly
by an application through the JAAS login context class
(javax.security.auth.login.LoginContext).

Client/server applications using VistALink for logins/connections make use of
VistaLoginModule thru JAAS configuration, by specifying
gov.va.med.vistalink.security.VistaLoginModule as the LoginModule class in a
jaas.config login configuration, and then invoking a JAAS login in application
code.

The key classes for invoking a login with this login module are:

- a callback handler, either CallbackHandlerSwing, CallbackHandlerSwingCCOW,
or CallbackHandlerUnitTest

- the login context (javax.security.auth.login.LoginContext)

- the Kernel principal returned after a successful login
(VistaKernelPrincipalImpl)

STATUS

Active

KEYWORDS

VistaLink

DURATION

Till Otherwise Agreed

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

SERVER_ADDRESS_KEY

public static java.lang.String SERVER_ADDRESS_KEY:
returns the JAAS configuration key to store/retrieve server IP address.

SERVER_ADDRESS_KEY_V1

public static java.lang.String SERVER_ADDRESS_KEY_V1:
returns the JAAS configuration key to store/retrieve server IP address, that
was used in VistALink v1.0 only.

SERVER_PORT_KEY

public static java.lang.String SERVER_PORT_KEY:
returns the JAAS configuration key to store/retrieve server port.

SERVER_PORT_KEY_V1

public static java.lang.String SERVER_PORT_KEY_V1:
returns the JAAS configuration key to store/retrieve server port, that was
used in VistALink v1.0 only.

SERVER_SPI_KEY

public static java.lang.String SERVER_SPI_KEY:
returns the JAAS configuration key to select the VistaLoginModuleSPI
implementation used for providing back-end Kernel login services.

public boolean login() throws
VistaLoginModuleException, VistaLoginModuleLoginsDisabledException,
VistaLoginModuleNoJobSlotsAvailableException,
VistaLoginModuleNoPathToListenerException,
VistaLoginModuleTooManyInvalidAttemptsException,
VistaLoginModuleUserCancelledException, VistaLoginModuleUserTimedOutException:

Should never be called by an application directly. Instead, this method is
invoked behind the scenes by the proxy of the JAAS LoginContext.

However, exceptions thrown by this method can be caught when invoking the
login() method of a JAAS login context.

When an application invokes login() on the LoginContext, the LoginContext
calls this method to initiate a login to a VistaLink M server. Once a
successful login has occurred, the authenticated connection will be stored in
the JAAS subject, in a VistaKernelPrincipal.

VARIABLES

TYPE

VARIABLES DESCRIPTION

throws

Output

Throws:

gov.va.med.vistalink.security.VistaLoginModuleException - a
VistaLoginModuleException is thrown if the login for this module fails.

gov.va.med.vistalink.security.VistaLoginModuleLoginsDisabledException - thrown
if logins are disabled

gov.va.med.vistalink.security.VistaLoginModuleNoJobSlotsAvailableException -
thrown if no job slots are available

gov.va.med.vistalink.security.VistaLoginModuleNoPathToListenerException -
thrown if the specified listener can't be reached

gov.va.med.vistalink.security.
VistaLoginModuleTooManyInvalidAttemptsException - thrown if too many bad login
attempts are made

gov.va.med.vistalink.security.VistaLoginModuleUserCancelledException - thrown
if user cancels the login

gov.va.med.vistalink.security.VistaLoginModuleUserTimedOutException - thrown
if user times out of the login

logout

public boolean logout() throws
VistaLoginModuleException:

Should never be called by an application directly. Instead, this method is
invoked behind the scenes by the proxy of the JAAS LoginContext.

However, exceptions thrown by this method can be caught when invoking the
logout() method of a JAAS login context.

For applications to call, to logout a user from an open connection/session to
a VistaLink M server. Doing this drops the connection, freeing up resources on
the M server.

VARIABLES	TYPE	VARIABLES DESCRIPTION
throws	Output	Throws: gov.va.med.vistalink.security.VistaLoginModuleException - thrown if the logout fails on the M side.

DATE ACTIVATED

2008/07/11