KAAJEE ICR (4851)

Name

Value

NUMBER

4851

IA #

4851

DATE CREATED

2006/04/21

CUSTODIAL PACKAGE

KERNEL

USAGE

Supported

TYPE

Other

DBIC APPROVAL STATUS

APPROVED

NAME

KAAJEE

GENERAL DESCRIPTION


KAAJEE addresses the Authentication and Authorization (AA) needs of
HealtheVet-VistA Web-based applications in the J2EE environment.

Most major J2EE application servers (e.g., BEA WebLogic V. 8.1 [SP4 or higher]
and Oracle's 9iAS) allow enterprises to override the default source of AA and
replace it with custom, enterprise-specific sources for AA.  In order to
rapidly develop an AA solution for HealtheVet-VistA web-based applications
without creating a new enterprise user store, KAAJEE takes full advantage of
this feature of creating a custom solution.  This enables KAAJEE to provide a
solution that has a similar look-and-feel of what VistA users are currently
accustomed to.

KAAJEE authenticates against a VistA M Server first with Access and Verify
codes via VistALink's AV connection spec (i.e.,
KaajeeVistaLinkConnectionSpec). After the user has been properly authenticated
against a VistA M Server, KAAJEE dynamically creates a temporary username and
password and populates this into a Structured Query Language (SQL) database
via custom Security Service Provider Interfaces (SSPIs). This username and
password is needed for the second level/phase/pass authentication for the J2EE
container.

Currently, Kernel maintains the primary HealtheVet-VistA user store (i.e., NEW
PERSON file [#200]), and provides both Authentication and Authorization (AA)
services for all HealtheVet-VistA applications. By leveraging Kernel, KAAJEE
aims to authenticate and authorize J2EE Web users to their applications using
Kernel's AA capabilities.

STATUS

Active

KEYWORDS

KAAJEE

DURATION

Till Otherwise Agreed

COMPONENT/ENTRY POINT

COMPONENT/ENTRY POINT	COMPONENT DESCRIPTION
login.jsp	Login Web page for authentication. This is the Login Web page where users enter their Access and Verify codes and choose an Institution from a drop-down list. For read-only access. The consuming application needs to place this file in their deployable artifact in the following directory/folder under the web context root: Directory File Name ========= ========= ..login\ login.jsp In addition, this login.jsp must configured in the application's web.xml file as a form-login-page. The following XML tags shows an example of how this may be configured in the application's web.xml file: <login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>login/login.jsp</form-login-page> <form-error-page>login/loginerror.jsp</form-error-page> </form-login-config> </login-config>
loginerror.jsp	This is the error page to be used with KAAJEE for Form-based authentication. When this page is presented to the user, the most likely cause is that the user is lacking the proper Security Keys required for the consuming application. For read-only access. The consuming application needs to place this file in their deployable artifact in the following directory/folder under the web context root: Directory File Name ========= ========= ..login\ loginerror.jsp In addition, this loginerror.jsp must be configured in the application's web.xml file as a form-error-page. The following XML tags shows an example of how this may be configured in the application's web.xml file: <login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>login/login.jsp</form-login-page> <form-error-page>login/loginerror.jsp</form-error-page> </form-login-config> </login-config>
loginerrordisplay.jsp	This is the error page that KAAJEE redirects to when authentication fails against a VistA M server after providing the access & verify codes plus the target institution. For read-only access. The consuming application needs to place this file in their deployable artifact in the following directory/folder under the web context root: Directory File Name ========= ========= ..login\ loginerrordisplay.jsp
SessionTimeout.jsp	Login session timeout Web page. This web page informs the user that his/her session has expired during login. For read-only access. The consuming application needs to place this file in their deployable artifact in the following directory/folder under the web context root: Directory File Name ========= ========= ..login\ SessionTimeout.jsp
loginCookieInfo.htm	Login persistent cookie information. This web page informs the user how the persistent cookie information is used. For read-only access. The consuming application needs to place this file in their deployable artifact in the following directory/folder under the web context root: Directory File Name ========= ========= ..login\ loginCookieInfo.htm
kaajeeConfig.xml	KAAJEE configuration file. Access to this file is restricted to read/write/modify as described in the KAAJEE documentation. For more detail regarding the parameters that may be modified, refer to the KAAJEE documentation. KAAJEE relies on a configuration file (i.e., kaajeeConfig.xml file) to read in all administrator-configurable settings. You can use the kaajeeConfig.xml file that is distributed with the KAAJEE software or you can create a KAAJEE configuration file in your J2EE Web-based application and export it along with your Web-based application. The consuming application may use 'kaajeeConfig.xml' as the name of the KAAJEE configuration file or any filename with an 'xml' extension. This name is identified by configuring web.xml to include a startup servlet (see also component gov.va.med.authentication.kernel.InitKaajeeServlet) similar to the following entry: <servlet> <servlet-name>KaajeeInit</servlet-name> <servlet-class>gov.va.med.authentication.kernel.InitKaajeeServlet</servlet -class> <init-param> <param-name>kaajee-config-file-location</param-name> <param-value>/WEB-INF/kaajeeConfig.xml</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet> The param-value of '/WEB-INF/kaajeeConfig.xml' associated with the param-name of 'kaajee-config-file-location' identifies the filename and location of the KAAJEE configuration file.
kaajee-x.x.x.xxx.jar	The kaajee-x.x.x.xxx.jar contains the KAAJEE java classes. Access to this file is limited to read-only. No modification are permitted. Note: The 'x.x.x.xxx' in the name 'kaajee-x.x.x.xxx.jar' is used as a placeholder and when referenced here in this Integration Agreement represents the current version. When actually using this file, replace 'x.x.x.xxx' with the current version of the KAAJEE JAR file. The kaajee-x.x.x.xxx.jar file must be distributed in your application's Enterprise Archive (.ear) file with an application-level classloader. When you are ready to deploy/distribute your application, perform the following steps: a. (required) Package the kaajee-x.x.x.xxx.jar file in your application's ear file (e.g., in a "../APP-INF/lib" folder descendent from the root level of your application's ear file). b. (required) Ensure that kaajee-x.x.x.xxx.jar is not located in a deeper level of the classloader hierarchy than that of an application, anywhere on the application server. Otherwise, the singletons will be instantiated with settings inappropriate for your application, and the KAAJEE security system will function inappropriately for your application.
['gov.va.med.authentication.kernel.KaajeeSessionAttributeLi', 'stener']	This class is included in the kaajee-x.x.x.xxx.jar file and is not a separate component. It is listed here only to describe how it is referenced in the consuming application's web.xml file. Configure KAAJEE Listeners (web.xml file) KAAJEE has two similar listeners, both of which perform logout actions for a user. Both of these listeners are available in case one listener does not work with a specific container/platform (e.g., WebLogic, Oracle 9iAS, etc.): Listener Description ======== =========== KaajeeSessionAttributeListener The KaajeeSessionAttributeListener listens for specific (individual) session attributes that are targeted for removal, which signals a user session ending, and performs user logout actions. (see also component gov.va.med.authentication.kernel.KaajeeHttpSessionListener) Configure these listeners in your application's web.xml file as follows: <listener> <listener-class> gov.va.med.authentication.kernel.KaajeeSessionAttributeListener </listener-class> </listener> (see also component gov.va.med.authentication.kernel.KaajeeHttpSessionListener)
HealtheVetVistaSmallBlue.jpg	HealtheVet-VistA small blue logo image file. For read-only access. This jpeg file is referenced by the KAAJEE login page to provide an image. The consuming application needs to place this file in their deployable artifact in the following directory/folder under the web context root: Directory File Name ========= ========= ..login\images\ HealtheVetVistaSmallBlue.jpg
HealtheVetVistaSmallWhite.jpg	HealtheVet-VistA small white logo image file. For read-only access. This jpeg file is referenced by the KAAJEE login page to provide an image. The consuming application needs to place this file in their deployable artifact in the following directory/folder under the web context root: Directory File Name ========= ========= ..login\images\ HealtheVetVistaSmallWhite.jpg
['gov.va.med.authentication.kernel.KaajeeHttpSessionListene', 'r']	This class is included in the kaajee-x.x.x.xxx.jar file and is not a separate component. It is listed here only to describe how it is referenced in the consuming application's web.xml file. Configure KAAJEE Listeners (web.xml file) KAAJEE has two similar listeners, both of which perform logout actions for a user. Both of these listeners are available in case one listener does not work with a specific container/platform (e.g., WebLogic, Oracle 9iAS, etc.): Listener Description ======== =========== KaajeeHttpSessionListener The KaajeeHttpSessionListener listens for session destruction. It is looking for the whole session being destroyed and performs user logout actions. (see also component gov.va.med.authentication.kernel.KaajeeSessionAttributeListener) Configure these listeners in your application's web.xml file as follows: (see also component gov.va.med.authentication.kernel.KaajeeSessionAttributeListener) <listener> <listener-class> gov.va.med.authentication.kernel.KaajeeHttpSessionListener </listener-class> </listener>
gov.va.med.authentication.kernel.LoginUserInfoVO	This class is included in the kaajee-x.x.x.xxx.jar file and is not a separate component. It is listed here only to describe how it may be referenced as a JavaBean by the consuming application. The session key, properties and getter methods listed below are for read-only access. Session key used to obtain userInfo JavaBean: SESSION_KEY The key under which this value is placed in the session object during login, and from which this object can be retrieved by the enclosing web application post-login. This SESSION_KEY is a public static final method that returns a string. Applications may use the userInfo JavaBean to obtain user demographic information. This can be achieved by using the JSP action <jsp:getProperty...> This JavaBean contains the following properties: UserDuz UserName01 UserNameDisplay UserLastName UserFirstName UserMiddleName UserPrefix UserSuffix UserDegree LoginStationNumber UserParentAdministrativeFacilityStationNumber UserParentComputerSystemStationNumber Alternatively, applications may access the getter methods directly. Methods with a return type of java.util.TreeMap: getPermittedNewPersonFileDivisions() Returns a list of the user's permitted divisions returned as a TreeMap. The key value in the TreeMap is the Station Number, which is a String. The object value stored under each key is a VistaDivisionVO object. (see also component gov.va.med.authentication.kernel.VistaDivisionVO) This list represents all of the divisions on the VistA M Server that the user could have logged into. Applications can display a list of other divisions that the user could switch to within the application, allowing the user to select a different division. It is then the application's responsibility to use the proper division for its own internal business rules, and also to pass the proper Division Station Number with each VistALink RPC call it makes to M. getLoginDivisionVistaProviderDivisions() returns a list of divisions (based on information in the SDS Institution table) whose Vista Provider is the same as the Vista Provider computer system of the login division. This list is returned as a TreeMap. The key value in the TreeMap is the Station Number, which is a String. The object value stored under each key is a VistaDivisionVO object. (see also component gov.va.med.authentication.kernel.VistaDivisionVO) This method is provided to applications to support division switching for all divisions supported at the same computing facility as the login division, regardless of whether explicit access has been granted to the user for any particular division. Applications can display a list of other divisions that the user could switch to within the application, allowing the user to select a different division. It is then the application's responsibility to use the proper division for its own internal business rules. The application developer should be aware that this method may not be appropriate when using VistALink RPC calls as the login user may not be permitted access to a specific division. Methods with a return type of java.lang.String: getLoginStationNumber() Returns the Station Number of the Division the user selected at login. This can be used as a key to retrieve additional information (e.g., name about the login division from the TreeMap of permitted divisions returned by the getPermittedDivisions method). getUserDegree() Returns the user's Degree value from the NAME COMPONENTS file (#20). getUserDuz() Return the user's DUZ from the NEW PERSON file (#200). getUserFirstName() Returns the users' First Name value from the NAME COMPONENTS file (#20) getUserLastName() Returns the user's Last Name value from the NAME COMPONENTS file (#20). getUserMiddleName() Returns the user's Middle Name value from the NAME COMPONENTS file (#20). getUserName01() Returns the user's name as it's stored in the NAME field (# .01) in the NEW PERSON file (#200). For example: KRNUSER,ONE E getUserNameDisplay() Returns the Display Name of the user, as put together by the Name Standardization APIs on M. For example: One E. Krnuser getUserParentAdministrativeFacilityStationNumber() Returns the parent facility of the Division used for login, as resolved on the login computer system based on that system's INSTITUTION file (#4) from the SDS V. 3.0 (or higher) tables. getUserParentComputerSystemStationNumber() Returns the computer system's default Institution/Computer System Institution, as identified in the system's KERNEL SYSTEM PARAMETERS file (#8989.3) getUserPrefix() Returns the user's Prefix value from the NAME COMPONENTS file (#20). getUserSuffix() Returns the user's Suffix value from the NAME COMPONENTS file (#20). toString() Returns a string representation of the values in the object.
gov.va.med.authentication.kernel.InitKaajeeServlet	This class is included in the kaajee-x.x.x.xxx.jar file and is not a separate component. It is listed here only to describe how it is referenced in the consuming application's web.xml file. Configure KAAJEE Startup Servlet (web.xml file) This Startup Servlet is needed by KAAJEE to read configuration parameters. For further information regarding these configuration parameters, refer to the current KAAJEE documentation. Configure this startup servlet in your application's web.xml file. The following XML tags shown below are an example of how to configure this startup servlet in the application's web.xml file: <servlet> <servlet-name>KaajeeInit</servlet-name> <servlet-class>gov.va.med.authentication.kernel.InitKaajeeServlet</servlet -class> <init-param> <param-name>kaajee-config-file-location</param-name> <param-value>/WEB-INF/kaajeeConfig.xml</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet> In the above example, the <param-value> contains the folder/path location and KAAJEE configuration filename relative to the applications's webroot context. Also, the <load-on-startup> value contains an integer value of the order in which you wish this servlet to start among other configured startup servlets.
gov.va.med.authentication.kernel.LoginController	This class is included in the kaajee-x.x.x.xxx.jar file and is not a separate component. It is listed here only to describe how it is referenced in the consuming application's web.xml file. This servlet is the main controller servlet that processes the login request. It must be configured in the application's web.xml file. For further details refer to the current KAAJEE documentation.
gov.va.med.authentication.kernel.VistaDivisionVO	This class is included in the kaajee-x.x.x.xxx.jar file and is not a separate component. It is listed here only to describe how it is referenced and associated with other component(s). VistaDivisionVO Object The VistaDivisionVO object is used to store an individual division, when division TreeMaps (i.e., tree structure, keyed on Division Station Number strings) are returned by the LoginUserInfoVO methods. Listed below are the Class Definition, Constructor Summary and Method Summary: public class VistaDivisionVO extends java.lang.Object implements java.io.Serializable Represents a VistA Division, including Station Name and Station Number. Constructor Summary VistaDivisionVO() Instantiates a VistaDivision with all fields set to a null string. The methods listed below are for read-only access: Method Summary boolean getIsDefault() Returns whether or not this is set to the default Login Division. java.lang.String getName() Returns the Station Name of the Division, presumably from the VistA M Server INSTITUTION file (#4) entry (depending on the source of the information the instance contains) java.lang.String getNumber() Returns the Station Number of the Division, presumably from the VistA M Server INSTITUTION file (#4) entry (depending on the source of the information the instance contains) java.lang.String toString() Returns a string representation of the Division information (See also component gov.va.med.authentication.kernel.LoginUserInfoVO regarding division TreeMaps returned) In order to retrieve this VistaDivisionVO object from these division TreeMaps, the following collection, iterator and methods may be used: java.util.Set Set java.util.TreeMap.keySet() java.util.Iterator Iterator java.util.Set.iterator()