Custom (Exit Program) - Genie Only
Overview
Genie can automatically sign a user into a session based on information provided by a user-defined exit program. This allows for automating sign on in a customizable way. Genie can be called with a URL parameter "token", as shown below:
http://yourserver:8080/profoundui/genie?token=XXXXXXXXXX
The contents of the token are user-defined, up to 2048 bytes can be passed. When this parameter is present, Genie will call exit program PUISSOEXIT in the product installation library and pass the token to it. This program can validate the token and (if successful) pass back an IBM i user profile to Genie. Genie will automatically start a session for this user profile, bypassing the 5250 sign on display.
Exit Program Usage
The exit program object PUISSOEXIT is not shipped with Profound UI, however a "skeleton" source member is supplied in member PUISSOEXIT in file QRPGLESRC in the product installation library (by default PROFOUNDUI). This source member will be replaced on each update installation of Profound UI, so users should make a copy of the source member into a non-Profound UI library.
The exit program object should be compiled with name PUISSOEXIT into the product installation library. The compiled object will NOT be replaced when updating Profound UI.
The exit program is run by the QTMHHTP1/PROFOUNDUI job.
The exit program uses the following parameter list. The parameter list MUST NOT be changed:
D PUISSOEXIT PI
D iToken 2048A Const
D oUser 10A
D oAllow N
D oMsg 128A
iToken contains the contents of the "token" URL parameter. This parameter is used for input-only. The value is right-padded with blanks to 2048 bytes. The exit program can validate this value to determine if the user should be able to sign in, and to determine what IBM i profile should be used.
oAllow is an output parameter that controls whether or not the user gets signed in. The parameter is set to '0' (Off) when the exit program is called. The exit program can set this to '1' (On) to allow automated sign on, or '0' (Off) to prevent it. When On is returned, parameter oUser must be set to a valid IBM i profile name.
oUser should be set by the exit program to the IBM i profile name to sign on automatically. The profile name must be given in uppercase. This parameter is ignored completely when the exit program returns oAllow = Off;
oMsg can be set by the exit program to display a custom error message when oAllow = Off. If this parameter is not populated by the exit program, a built-in error message is displayed. The parameter is ignored completely when oAllow = On.
If you are wanting to retrieve the HTTP Apache Enviroment variables using your PUISSOEXIT program you need see the information found here.
Exit Program Security
Note that security under this scenario is entirely user-defined. When the exit program indicates that automated sign on should occur and an IBM i profile name is received from it, a session will start immediately for that user profile, with no password required.
Care must be taken when designing the token contents and exit program validation logic so that unauthorized access to the system is not possible.
Restricting Access to Sign On Screens
You will likely want to prevent access to IBM i "Sign On" screens when using URL tokens. The following rules can be added to HTTP Server's configuration file to make the server respond with 403 Forbidden responses when a request for a URL with "/profoundui/genie" does not contain the token:
# Send 403 Forbidden response when request to genie does not contain token.
RewriteCond %{REQUEST_URI} ^/profoundui/(PUI0002100\.pgm|genie) [NC]
RewriteCond %{QUERY_STRING} !token=.+
RewriteRule .* - [F]
Some documentation pages have recently moved to a new section: Profound AppDev. If you are having trouble finding specific pages, try the documentation search capability or reach out to our Support team!