Security for submitting a JCL job to the internal reader

For CICS to be able to secure who can submit JCL, there are a number of configuration and security definitions required.

JCL jobs can be submitted by writing JCL in two ways:
  • Using WRITEQ TD commands to an extrapartition TDQ defined to the internal reader
  • Using SPOOLWRITE commands when a USERID("INTRDR") was specified on the SPOOLOPEN command
There are three user IDs involved in job submission:
  • Region user ID.
  • Signed-on user ID. This is the user ID that the task is running under (the default user ID if not logged on).
  • Job user ID. This is specified by a USER parameter on the JOB card. If the JOB statement doesn’t contain a USER parameter, the default will depend on the security settings. If this isn’t the region user ID, CICS will add USER=job_userid to the JOB card. In releases earlier than CICS TS 5.5, the default is always the region user ID.

Protection for JCL jobs that are submitted through the TDQ is provided by resource security on the TDQ. Additional protection is provided by surrogate user checking if the USER parameter is specified on the JOB card. For details, see Security when using a TDQ to submit JCL.

Protection for JCL jobs that are submitted by using spool commands is provided by surrogate user checking. For details, see Security when using the SPOOLWRITE commands to submit JCL.

In addition, it is necessary to have a profile for the region user ID in the JESSPOOL class to give the region user ID authority to submit jobs for the job user IDs. See z/OS surrogate user checking for details of the RACF definitions and error messages if the surrogate check fails.

Security when using a TDQ to submit JCL

Protection is provided by a resource security check of the TDQ. For details, see Security for transient data.

Additional security configuration and checking depends on whether a user ID is specified on the job card written to the TDQ by using the WRITEQ TD command.

If a user ID is specified
Example: 
//JOBNAME JOB USER=JOBUSER

CICS performs an additional surrogate check when writing the job card to the TDQ. This surrogate check verifies whether the task user ID has permission to submit jobs on behalf of the job user ID (JOBUSER in the above example).

To enable this security check, you must set the following options:
  • CICS surrogate user checking is enabled by the system initialization parameter XUSER=YES.
  • The feature toggle for surrogate user checking for spool commands is enabled:
    com.ibm.cics.spool.surrogate.check=true

If the surrogate check fails, a NOTAUTH response will be returned from the WRITEQ TD command. See CICS surrogate user checking for details of the RACF definitions and error messages if the surrogate check fails.

If a user ID is not specified
Example: 
//JOBNAME JOB
CICS will add a USER parameter to the statement written to the TDQ. The job user ID added will be set to the value specified by the JOBUSERID option in the TDQ definition.
//JOBNAME JOB USER=jobuserid
If JOBUSERID is not defined in the TDQ definition, the job user ID will be set to the CICS region user ID. No additional surrogate checking will be done by CICS.
//JOBNAME JOB USER=regionuserid

Security when using the SPOOLWRITE commands to submit JCL

To use spool commands, CICS must be started with the system initialization parameter SPOOL=YES.

If a JOB card that is written using a SPOOLWRITE command has a USER parameter, protection is provided by a surrogate check will be made if the following options are defined:
  • CICS surrogate user checking is enabled by the system initialization parameter XUSER=YES.
  • The feature toggle for surrogate user checking for spool commands is enabled:
    com.ibm.cics.spool.surrogate.check=true

If the surrogate check fails, a NOTAUTH response will be returned from the SPOOLWRITE command. See CICS surrogate user checking for details of the RACF definitions and error messages if the surrogate check fails.

If a JOB card that is written using a SPOOLWRITE command doesn't have a USER parameter, the job user ID will default to the region user ID. This will be subject to a surrogate check. You can change the default to job user ID to be the signed-on user ID if you set the following feature toggle: 
com.ibm.cics.spool.defaultjobuser=TASK

Specifying the region user ID on the JOB card

If you want a job to be able to run under the region user ID without needing to change the JCL dynamically, you can specify USER=&SYSUID on the JOB card. This will run the job under whatever region user ID the job was submitted from. This applies to JCL jobs written using the SPOOLWRITE command or using a TDQ. A surrogate security check, if applicable, will be made when jobs are submitted using &SYSUID to represent the region user ID.

z/OS surrogate user checking

Although the SPOOLWRITE and WRITEQ TD commands are issued by the signed-on user ID, the job is submitted by the region user ID. Therefore, if the job user ID is not the region user ID and no password is supplied, it is necessary to grant the region user ID surrogate authority to submit jobs on behalf of the job user ID. This is required regardless of whether CICS surrogate user checking is active or not.


RDEFINE SURROGAT job_userid.SUBMIT UACC(NONE) OWNER(sysadmin) 
PERMIT job_userid.SUBMIT CLASS(SURROGAT) ID(region_userid) ACCESS(READ)

If you configure your region user IDs to be able to submit jobs on behalf of any user, it is recommended that the region user IDs are not used for any other purpose than a user ID for running CICS.

The check takes place after the job is submitted. If the check fails, the job will fail with an ICH408I message issued to the console and job log, but no response will be returned to the application.

ICH408I USER(job_userid) GROUP(group) NAME(username) SUBMITTER(region_userid)                                 
LOGON/JOB INITIATION - SUBMITTER IS NOT AUTHORIZED BY USER

CICS surrogate user checking

CICS surrogate user checking will be made if the following options are defined:
  • CICS surrogate user checking is enabled by the system initialization parameter XUSER=YES.
  • The feature toggle for surrogate user checking for spool commands is enabled:
    com.ibm.cics.spool.surrogate.check=true

If the job user ID is not the signed-on user ID and no password is supplied, it is necessary to grant the signed-on user ID surrogate authority to submit jobs on behalf of the job user ID.


RDEFINE SURROGAT job_userid.SUBMIT UACC(NONE) OWNER(sysadmin) 
PERMIT job_userid.SUBMIT CLASS(SURROGAT) ID(signed_on_userid) ACCESS(READ)

If a surrogate check is applicable it will take place when the SPOOLWRITE or WRITEQ TD command writes the JOB card. If the check fails, the command will fail with a NOTAUTH response. In addition, a DFHXS1111 message will be issued to the CICS log, and an ICH408I message will be issued to the console and job log.

ICH408I USER(job_userid) GROUP(group) NAME(username) SUBMITTER(signed_on_userid)                 
LOGON/JOB INITIATION - SUBMITTER IS NOT AUTHORIZED BY USER

Learn more

If you want to migrate to using CICS surrogate user checking, follow the instructions in Upgrading security.