RACROUTE REQUEST=VERIFY(X) exits

A RACROUTE REQUEST=VERIFY or RACROUTE REQUEST=VERIFYX request is used to determine whether a user ID is defined to RACF® and whether the user has supplied a valid password or password phrase and group name. During TSO logon processing, the VERIFY request also determines whether a user who is entering the system has supplied a valid operator identification card (OIDCARD) and is authorized to access the terminal. During IMS™ and CICS® signon processing, the VERIFY request determines whether a user who is entering the system is authorized to use IMS or CICS and to access the terminal.

If the user ID, password or password phrase, operator identification card, group name, terminal, and application are accepted, RACF builds an accessor environment element (ACEE) for the user.

Note: When no user ID, group, and password are passed to RACROUTE REQUEST=VERIFY, RACROUTE builds a default ACEE containing an asterisk (*) (X'5C') for the user ID and group name and returns to the issuer of the VERIFY request with a return code of 0, indicating a successful completion.

The ACEE identifies the scope of the user's authorization that will be used during the current terminal session or batch job. You can use the RACROUTE REQUEST=VERIFY(X) exit routine to supply a user ID for undefined users or to perform additional authorization checks for users. Many of the values passed to the RACROUTE REQUEST=VERIFY(X) preprocessing and postprocessing exits are derived from the parameters specified on the RACROUTE macro. For more details, see z/OS Security Server RACROUTE Macro Reference.

When the user ID passed to RACROUTE REQUEST=VERIFY begins with ** (X'5C5C'), an identity context reference is being passed instead of a user ID and password. RACF calls the R_cacheserv SAF callable service to map the identity context reference to a user ID known to the RACF domain, and builds an ACEE using information from the identity context cache. The mapping of the identity context reference to a RACF user ID occurs before the preprocessing exit (ICHRIX01) is invoked. The user ID field in the exit parameter list (RIXUID) is set to the RACF user ID, the password field (RIXPWD) is set to zero, and the identity context extension field (RIXICTX) is set to point to an identity context extension (ICTX). The ICTX contains information about the original user that RACF includes in audit records; at the successful completion of the VERIFY request it will be anchored in the ACEE by the field ACEEICTX. Because an identity context reference identifies a user who has already been authenticated, the flag RIXPSCKN in the exit parameter list is set to indicate that password checking should be bypassed, as if PASSCHK=NO was specified on the RACROUTE.

When an identity context reference is passed, RACF does not use the following keywords in its subsequent processing, and the exit parameter list does not contain values for them even if they were specified on the RACROUTE request:

JOBNAME
SGROUP
SUSERID
SNODE
EXENODE
STOKEN
REMOTE
START

An ICTX can also be provided by the ICTX= keyword on the RACROUTE REQEST=VERIFY input parameter list. If it is provided both on the parameter list and resolved from an identity context reference (ICR), the one resolved from the ICR is the one used by RACF and passed to the exit in RIXICTX.

The exit must not free the ICTX area or change its length (ICTXLEN), but it can change the fields within the ICTX by changing the lengths and contents of the fields within the bounds of the existing area. It can delete fields by setting the field lengths to 0. If RIXICTX=0 on entry, it can provide a new ICTX block as described by the ICTX= keyword on the RACROUTE request, but it or the requestor is responsible for freeing the area in the event the request fails and an ACEE is not built that anchors the ICTX.