Kernel APIs: $$CREATE^XUSAP

$$CREATE^XUSAP(): Create Application Proxy User

Reference Type: Controlled Subscription, Category: Signon/Security, ICR#: 4677

Description

The $$CREATE^XUSAP extrinsic function is a non-interactive API to create an Application Proxy User to support J2EE middle-tier applications. The Application Proxy User represents an application and not an end-user.

CAUTION: If the user running this extrinsic function does not hold the XUMGR security key, it returns an error upon the filing of the Application Proxy as the User Class.

NOTE: This API was released with Kernel Patch XU*8.0*361.

Overview

The Application Proxy User is a special category of user account that gets created in the NEW PERSON (#200) file and can run internal tasks or execute authorized Remote Procedure Calls (RPCs). The Application Proxy represents an application and not an end-user. The Application Proxy user account must adhere to the following criteria:

The name added to the NEW PERSON (#200) file must be unique and must be namespaced in accordance with M Programming Standards and Conventions (SAC) Section 2.6, “Name Requirements.”
It must have a user class of "Application Proxy," as defined in the USER CLASS (#201) file and pointed to by the USER CLASS (#9.5) field in the NEW PERSON (#200) file.
It must not have an Access or Verify code assigned to it.
It must not have a Primary menu assigned to it.
It must have one or more Secondary menu options assigned to it. The Secondary menu option must be owned by the application that the Application Proxy represents, or the application must have an Integration Control Registration (ICR) with the option owner. The Secondary menu option contains a list of RPCs that the Application Proxy is authorized to call, as described in the “RPC Security” section in the RPC Broker User Guide.
The RPCs that the menu options reference must have the APP PROXY ALLOWED (#.11) field in the REMOTE PROCEDURE (#8994) file set to YES. The RPCs must be owned by the application that the Application Proxy represents, or the application must have an ICR with the RPC owner.
The use of an Application Proxy must be restricted to accessing non-protected data. Federal laws specify when an actual end-user must be represented when accessing Personally Identifiable Information (PII) and Protected Health Information (PHI). Information regarding user authentication, identity, auditing, and authorization can be found in:
- VA Information Security Handbook 6500 Appendix F
- National Institute of Standards and Technology (NIST) e-Authentication Guidelines (800-63-2)
- Health Insurance Portability and Accountability Act of 1996 (HIPAA) federal law 45 CFR § 160 & § 164

Application Proxy Privacy and Auditing

Many VistA data interactions by human end-users must be represented with accurate and unambiguous user identity information, so that VistA audit mechanisms function as intended. Application Proxy user accounts do not identify the user and should be avoided, especially where the interaction is with PHI/PII data (regulated by federal law). The use of Application Proxy user accounts should be limited to background processes and machine-to-machine interactions.

Application Proxy Permission

Permission to use the $$CREATE^XUSAP API should be done early in the development process; as use of Application Proxy user accounts are reviewed by VA management due to security concerns.

Format

  $$CREATE^XUSAP(proxyusername[,filemanaccesscode][,options])

Input Parameters

proxyusername:	(required) This is the name of the Application Proxy User (e.g., VPR,APPLICATION PROXY). This name must be unique and should be namespaced.
filemanaccesscode:	(optional) This is the VA FileMan Access code. It cannot be an at-sign (@). NOTE: For more information, see the VA FileMan Advanced User Manual.
options:	(optional) This is the name of a single option name (e.g., VPR APPLICATION PROXY) or an array of options, such as XUOPT("XMUSER")=1. Applications can only access the Remote Procedure Calls (RPCs) contained in the options provided in this input parameter. RPCs are tied to "B"-type options.

Output

returns:

Returns:

IEN of entry created in NEW PERSON (#200) file—Successful; writes new Application Proxy User to the NEW PERSON (#200) file.
"0^Name In Use"—Unsuccessful; Application Proxy User of that name already exists in the NEW PERSON (#200) file.
-1—Unsuccessful due to either of the following:
- Could not create Application Proxy User.
- Error in call to UPDATE^DIE.
  
  NOTE: For more information on UPDATE^DIE-related error, users should check ^TMP("DIERR",$J).

Examples

Application Proxy Example (Good)

The following example shows a successful creation of an Application Proxy User:

    >IF $$CREATE^XUSAP("VPR,APPLICATION PROXY","","VPR APPLICATION PROXY")>0 W !,"Proxy Created"

    Proxy Created

The following is an example of an Application Proxy user account that is provisioned correctly:

NAME: VPR,APPLICATION PROXY             DATE ENTERED: SEP 01, 2011
  CREATOR: XUUSER,ONE
SECONDARY MENU OPTIONS: VPR APPLICATION PROXY
  TIMESTAMP: 62335,62903
User Class: APPLICATION PROXY           ISPRIMARY: Yes

The Proxy User List [XUSAP PROXY LIST] option lists the current Application Proxy user accounts, as shown in the following sample listing:

PROXY USER LIST                                JAN 28,2016  09:44    PAGE 1
NAME                                 User Class          IsPrimary  Active
--------------------------------------------------------------------------------

XOBVTESTER,APPLICATION PROXY         APPLICATION PROXY   Yes        
ANRVAPPLICATION,PROXY USER           APPLICATION PROXY   Yes        
VPFS,APPLICATION PROXY               APPLICATION PROXY   Yes        
RADIOLOGY,OUTSIDE SERVICE            APPLICATION PROXY   Yes        
LRLAB,HL                             APPLICATION PROXY   Yes        
LRLAB,POC                            APPLICATION PROXY   Yes        
TASKMAN,PROXY USER                   APPLICATION PROXY   Yes        
CLINICAL,DEVICE PROXY SERVICE        APPLICATION PROXY   Yes        
NHIN,APPLICATION PROXY               APPLICATION PROXY   Yes        
EDPTRACKING,PROXY                    APPLICATION PROXY   Yes        
KAAJEE,PROXY                         APPLICATION PROXY   Yes        
VPR,APPLICATION PROXY                APPLICATION PROXY   Yes        
AUTHORIZER,IB REG                    APPLICATION PROXY   Yes        
HOWDY,BOT                            APPLICATION PROXY   Yes        
LRLAB,TASKMAN                        APPLICATION PROXY   Yes        
VIABAPPLICATIONPROXY,VIAB            APPLICATION PROXY   Yes

CAUTION: Some of the listed Application Proxy user accounts do not follow the rules for namespacing. There are other serious infractions in current applications using Application Proxy user accounts, which puts the VA in the position of violating federal privacy laws by accessing PHI/PII information. VA Handbook 6500 Appendix F lists VA System Security Controls that are applicable to Application Proxy user accounts as well as human end-users. An Application Proxy should never be used to circumvent VA System Security Controls.

Application Proxy Example (Bad)

The following is an example of an Application Proxy user account that is not provisioned correctly:

NAME: TASKMAN,PROXY USER                FILE MANAGER ACCESS CODE: #
  DATE ENTERED: JUN 9,2009              CREATOR: LABTECH,FORTYEIGHT
  NAME COMPONENTS: 200
  SIGNATURE BLOCK PRINTED NAME: PROXY USER TASKMAN
  TIMESTAMP: 62362,53550
User Class: APPLICATION PROXY           ISPRIMARY: Yes

If provisioned correctly, the name “TASKMAN,PROXY USER” would be identified by the Kernel (XU) namespace, such as “XUTASKMAN,PROXY USER”. This particular Application Proxy does not require access to any menu options or RPCs, so it does not contain a SECONDARY MENU OPTION.

Another example of an Application Proxy user account that is not provisioned correctly:

NAME: CLINICAL,DEVICE PROXY SERVICE     DATE ENTERED: JUN 30,2010
  CREATOR: XUUSER,ONE
SECONDARY MENU OPTIONS: MD GUI MANAGER
SECONDARY MENU OPTIONS: MD GUI USER
  TIMESTAMP: 61907,71682
User Class: APPLICATION PROXY           ISPRIMARY: Yes

In this example, the SECONDARY MENU OPTIONs are in the Clinical Procedures (MD) namespace, so that if provisioned correctly, “CLINICAL,DEVICE PROXY SERVICE” would be more appropriately named “MDCLINICAL,DEVICE PROXY SERVICE”.