RACROUTE REQUEST=VERIFY: Identify and verify a RACF-defined user

The RACROUTE REQUEST=VERIFY macro provides RACF® user identification and verification. The macro instruction identifies a user and verifies that the user is defined to RACF and has done either of the following tasks:

He has supplied a valid password phrase, or
He has supplied a valid password or operator-identification card (OIDCARD parameter) or both.

You can protect applications by using profiles in the APPL class along with this macro to control the users able to use applications. For more information about protecting applications, see z/OS Security Server RACF Security Administrator's Guide.

A subsystem can use REQUEST=VERIFY and the new keywords to create an ACEE. (For information on VLF considerations for ACEEs, see z/OS Security Server RACF System Programmer's Guide.)If RACF is not active or not installed, SAF, using the new keywords, builds a default ACEE to satisfy the request. The purpose of this use of REQUEST=VERIFY is for job submission and user verification checking.

The following order of priority exists for replacing the fields in the existing TOKEN:

Keywords specified on the request take precedence over corresponding fields in the TOKNIN and STOKEN parameters.
All fields within the token specified by the TOKNIN keyword take precedence over those specified by STOKEN.
The fields for the submitter's ID, submitter's group, submit node, execution node, session, port of entry and its class, as obtained from the token specified by the STOKEN keyword are last.

If you do not want certain fields overridden, do not specify keywords for those fields.

To issue the RACROUTE REQUEST=VERIFY macro, the calling module must be authorized (APF-authorized, in system key 0–7, or in supervisor state) or the NEWPASS, PHRASE, NEWPHRASE, ICRX, ICTX, and IDID keywords must be omitted and the calling module must be in the RACF-authorized caller table and fetched from an authorized library and reentrant.

However, the caller does not need to be authorized or in the RACF-authorized caller table when specifying ENVIR=VERIFY on the RACROUTE REQUEST=VERIFY macro.

Guideline: If you run programs that issue the RACROUTE REQUEST=VERIFY macro, run those programs APF-authorized. See z/OS Security Server RACF System Programmer's Guide for information on the authorized caller table.

The caller cannot hold any locks when issuing RACROUTE REQUEST=VERIFY.

Automatic direction of application updates does not propagate RACROUTE REQUEST=VERIFY requests that update the RACF database; however, the following ICHEINTY requests issued by RACROUTE REQUEST=VERIFY are propagated:

The ICHEINTY setting the revoke flag in the user profile when a user is being revoked due to inactivity or incorrect password attempts.
The ICHEINTY increasing the revoke count when a user enters an incorrect password.
The ICHEINTY that resets the revoke count to 0 when a user enters a valid password.

The ICHEINTY issued by RACROUTE REQUEST=VERIFY to change the password in the user's profile is not eligible for propagation by automatic direction of application updates because it is already eligible for propagation by automatic password direction.

Note:

Unless the caller specifies the ACEE= parameter on a RACROUTE REQUEST=VERIFY,ENVIR=CREATE macro instruction, the ACEE is always placed below 16MB.
If the caller specifies the ACEE= parameter, is executing in 31-bit addressing mode, and does not specify LOC=BELOW on the RACROUTE macro instruction, the ACEE is placed, if possible, above 16MB.
Some functions (such as EXTRACT) require that an ACEE exist. RACF supports use of the *BYPASS* user ID to create an ACEE to satisfy these cases when no other ACEE is available.
To create this environment, specify the user ID as *BYPASS*, specify PASSCHK=NO, and do not specify a password field at all. A successful use is not audited but a failure may be audited if requested.

If an ACEE with a user ID of *BYPASS* is used with REQUEST=AUTH, a return code of 4 is returned. Depending upon the application, this may allow access to a resource.