[OBSOLETE] Integrating System i User IDs with Valence

[robert.swanson]

[NOTE: With the release of Valence 2.0 the information in this post is obsolete (though the explanation of "current user" versus "job user" still holds true). With Valence 2.0, user switching is mostly automatic. See the Valence 2.0 user manual for further details].

Hello all,

As of today, with release 1.1, you can now have Valence override the current user on the CGI job processing user requests.

First, a quick explanation of this concept... If you go to WRKACTJOB and look at the Valence instances running under QHTTPSVR, you'll see something like this:

                             Work with Active Jobs                     S100DB6A 
                                                             07/11/08  11:02:23 
 CPU %:      .3     Elapsed time:   00:05:51     Active jobs:   358             
                     Current                                                    
 Opt  Subsystem/Job  User        Type  CPU %  Function        Status            
      QHTTPSVR       QSYS        SBS      .0                   DEQW             
        ADMIN        QTMHHTTP    BCH      .0  PGM-QZHBMAIN     SIGW             
        ADMIN        QTMHHTTP    BCI      .0  PGM-QZSRLOG      SIGW             
        ADMIN        QTMHHTTP    BCH      .0  PGM-QLWISVR      JVAW             
        ADMIN        QTMHHTTP    BCI      .0  PGM-QZSRHTTP     SIGW             
        ADMIN        QSECOFR     BCI      .0  PGM-QYUNLANG     TIMW             
        VALENCE11    QTMHHTTP    BCH      .0  PGM-QZHBMAIN     SIGW             
        VALENCE11    QTMHHTTP    BCI      .0  PGM-QZSRLOG      SIGW             
        VALENCE11    QTMHHTTP    BCI      .0  PGM-QZSRLOG      SIGW             
        VALENCE11    QTMHHTTP    BCI      .0  PGM-QZSRHTTP     SIGW             
        VALENCE11    QTMHHTTP    BCI      .0  PGM-QZSRHTTP     DEQW             
        VALENCE11    QTMHHTP1    BCI      .0  PGM-QZSRCGI      TIMW             
        VALENCE11    QTMHHTP1    BCI      .0  PGM-QZSRCGI      TIMW             

The default user for all Apache CGI jobs is QTMHHTP1, and this is what you'll typically see for the "Current User" in WRKACTJOB as users click their way through programs with Valence. You can change this default global user to whatever you want in your Apache server configuration settings, but for most intents and purposes QTMHHTP1 works fine.

That said, for various reasons you may need to use something other than a global default for the user ID. For example, if you're journaling files and would like to be able to see which user added, changed or deleted a particular record, seeing "QTMHHTP1" in the receiver data isn't going to give you much of a clue (other than that it likely wasn't done through a green screen program).

Likewise, if you have any 10-character fields in your legacy database files that are used to store the User ID of the person maintaining a record (or the last person that made a change), RPG programs updating these records with the user ID from the program status data structure (SDS) will also be plugging "QTMHHTP1" (or whatever value is your default global user).

There are also cases where security settings on your system will require "real" user profiles with specific authorities in order to access certain database files, sometimes making QTMHHTP1 problematic.

So how to address this? There are various options available for you to get your Apache jobs to override the user ID on the back-end CGI jobs servicing front-end requests, such as using Enterprise Identity Mapping (EIM), Lightweight Directory Access Protocol (LDAP), etc. But because Valence already handles user login security and session control, you will typically find it more efficient (and more seamless to the user) to allow Valence to handle the user swapping as well. With version 1.1, that is now an option for your programs by simply including three extra lines of code.

If you have a "System i User" defined for your Valence User IDs, then Valence can be set to override the current user to the appropriate value every time someone takes an action on the front-end. To do this, you must first activate the feature in the Apache configuration file for your Valence instance. Find the "OVERRIDE_JOB_USER" text in the file and change it as follows:

# Override CGI job to System i user active
SetEnv OVERRIDE_JOB_USER Y
PassEnv OVERRIDE_JOB_USER

Doing this will instantly make all Valence programs switch the current user of your CGI jobs to the value specified as the System i User in the Valence User Master. Note that whenever a Valence user has no System i user specified, or the System i user specified is invalid or inactive, the current user on the CGI job will defer back to the global default.

For your own programs to switch the current user as they're executed, you must include a few extra lines in your source. First, you will want the following compiler directive at the top of your program:

      /define OVERRIDE_JOB_USER

Then you will need to include the following copy source two more times (for a total of three) in your code -- once at the start of your executable lines (C specs) and then once again at the end of your program (you should already have this line in your D specs):

      /copy qcpylesrc/vvDevelop

This will automatically include the source code necessary to invoke the current user override procedure at the start of your program, and then "undo" the user override at the end of the program.

Note that this user override procedure retrieves the System i User ID from the session variable data structure. Therefore, it assumes you have the session ID named "sid" in your front-end javascript. If that's not the case, you must populate the global variable vvSessID in your RPG program immediately prior to the VVDEVELOP copy source at the start of the executable portion of your program, as follows:

     **----------------------------------------------  
     **  program start                                 
     **----------------------------------------------  
      /free                                            
       vvSessID =vvHttp_in('sid');                     
      /copy qcpylesrc,vvDevelop 

...And that's all there is to it!

To achieve this user swapping, Valence uses the QSYSGETPH, QWTSETP and QSYRLSPH APIs to retrieve, change and release profile handles. You can read up on these on the IBM System i website for more details.

[robert.swanson]

Tips for retrieving the Current User in RPG

This is a "Good to Know" follow up to the current user override of the previous post...

A lot of RPG programs pull the user ID from the program status data structure (SDS) at the start of the program. But did you know there are actually TWO user ID fields in that data structure? One is the job user, the other is the current user. Conventional green screen programs, especially ones that have been around for a long time, will typically reference the job user. For modern web programming, however, it's always the current user you're going to be interested in.

The breakdown of the SDS with the two user fields looks like this:

     d                sds              
     d Job_User              254    263
     d Current_User          358    367

When your program first launches, the Job_User field is filled with the user that started the job (typically QTMHHTP1 for Apache CGI jobs), and the Current_User field is filled with whoever is currently running the job, provided a mechanism is in place to change it. Typically, both fields will be the same, but if you use the Valence user override logic descibed in the previous entry of this thread (or any other method to perform a user swap), the Current_User will be changing as different users execute programs through the CGI job.

It's very important to understand that the fields in the SDS are only assigned when the program is first initialized. If you have your program set up so that it doesn't truly terminate between calls (i.e., via an unended activation group or leaving *INLR off), then subsequent calls to the same program may not actually change the Current_User field. Because of this, rather than using the SDS method shown above, I recommend you derive your current user by simply initializing it in a subprocedure field using inz(*user), as follows:

      //-Subprocedure Prototype------------------
     d GetCurrentUser  pr            10a      

      //-Variable Definitions--------------------
     d Cur_User        s             10a        

      //-Main Line-------------------------------
      /free    
       // Get current user for this job
       Cur_User = GetCurrentUser();      
       *inlr = *on;    
      /end-free        

     p-----------------------------------------
     p GetCurrentUser  b                                        
     p* Subprocedure to retrieve current user for this job                      
     p*                                                        
     d GetCurrentUser  pi            10a                        
     d*                                                        
     d UserID          s             10a   inz(*user)          
     d*                                                        
      /free                                                    
       return UserID;                                          
      /end-free                                                
     p                 e

Since the subprocedure field is initialized on each call to the subprocedure, this method will ensure you're always retrieving the current user. You can then use this to populate fields in your database.

Of course, you could also just retrieve the Valence-assigned System i user within your programs straight from the session variable, like this:

             // retrieve session ID
             SessionID = vvHttp_in('sid');            

             // retrieve session variable, plug into session data structure
             sessionDS = vvSecure_getSessVar(SessionID :VVSESSVAR);

             // plug System i user into local field
             Cur_User = SessionDS.VValias;

...however, this method doesn't actually look at the current user of the CGI job, it's just pulling the assigned alias set up for the user in Valence. The actual current user of the CGI job could still be QTMHHTP1 if it's not being overridden.


***UPDATE*** For Valence 4 and beyond, you should use this technique in your RPG program to get the IBM i user associated with the current session:

vvUtility_getCurrentUser(*omit:Cur_User);

[richard.milone]

Nice posts, Rob. Thanks for enlightening us on this topic. I'd like to add that none of the demo programs in Valence use the user override method. This is intentional to keep those programs simple. However, if developers want to see a full example you can look into any of the Valence administration programs like VVUSERS, VVGRPS, etc. As of Valence 1.1 all those programs are set up to work with the Valence user override.

[NickT]

Bypassing the Valence Vewport login

Hi,

Is it possible to bypass the Valence Viewport login if the user is already authenticated with the Apache server, for example if we were using Kerberos authentication and EIM? We already use theis method to bypass the 5250 signon screens for our users, so we wouldn't want them to have to log in to the Viewport.

Regards,

Nick

[sean.lanktree]

Hi Nick -

You can bypass the Valence login if you are using EIM. In order to do so, you must edit the Valence Apache configuration file. Look for the line "SetEnv LOGIN_METHOD" and change it to "SetEnv LOGIN_METHOD EIM". After saving the changes you must restart the Valence server instance.

[richard.milone]

Nick, just an FYI about how the EIM functionality within Valence works. When the user navigates to vvlogin.pgm, if the "SetEnv LOGIN_METHOD" is set to EIM, Valence will assume that EIM has already authenticated the user and will actually look at the current user of the CGI job that is handling the request. If that user is found as a user in the Valence Users file (using the System i User field), then the login will be automatic to Valence and no login screen will be presented. If the user is authorized to more than one environment the environment selector will still be displayed. If the user of the CGI job is not found in the Valence User file then the login window will show as usual. If you have any problems setting this up just let us know.