Security for submitting a JCL job to the internal reader

To secure who can submit JCL, CICS® requires a number of configuration and security definitions.

JCL jobs can be submitted in two ways:
  • Using a WRITEQ TD command to an extrapartition TDQ defined to the internal reader
  • Using the following SPOOL commands:
    • SPOOLOPEN with USERID("INTRDR") specified
    • SPOOLWRITE
There are three user IDs involved in job submission:
CICS region user ID
This is the region user ID used to start CICS.
task 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 the user ID specified by a USER parameter on the JOB card.

If the JOB statement doesn’t contain a USER parameter, the default depends on the security settings as follows:

JCL submitted through a TDQ
  • First choice: The user ID specified in the JOBUSERID option in the TDQ definition
  • Second choice: CICS region user ID

For details, see Security when using a TDQ to submit JCL.

JCL submitted by SPOOL commands
  • 6.2 and later Set by the INTRDRJOBUSER system initialization parameter, which can be either of the following IDs:
    • task user ID
    • CICS region user ID
  • 6.1 The job user ID defaults to the region user ID. This can be changed to default to the task user ID by setting com.ibm.cics.spool.defaultjobuser=TASK.
Security tip: As security best practices, a zero trust strategy is recommended whereby any work should run under the identify of the user doing the work. Therefore,
  • 6.2 and later The default (task user ID) of INTRDRJOBUSER is in accordance with this strategy.
  • 6.1 Setting com.ibm.cics.spool.defaultjobuser=TASK is in accordance with this strategy.

For details, see Security when using the SPOOL commands to submit JCL.

If the job user ID isn’t the CICS region user ID, CICS adds USER=job_userid to the JOB card.

Tip: Specifying the CICS region user ID by using symbolics on the JOB card

If you want a job to be able to run under the CICS region user ID without needing to change the JCL dynamically, you can specify USER=&SYSUID on the JOB card. This runs the job under whatever CICS 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, is made when jobs are submitted using &SYSUID to represent the CICS region user ID.

What security protection applies

Resource security on the TDQ provides protection for JCL jobs that are submitted through the TDQ. Additional protection is provided by CICS 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 security. For details, see Security when using the SPOOL commands to submit JCL.

In addition, you must have a profile for the CICS region user ID in the JESSPOOL class to give the CICS region user ID the 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

To submit JCL to the internal reader through TDQ job submission, the DDNAME attribute on the TDQUEUE resource definition must be configured to point toward a DDNAME specified within the CICS runtime JCL.
Example
//DDNAME   DD  SYSOUT=(A,INTRDR),DCB=(RECFM=F,LRECL=80)
The DDNAME in this line of JCL would then be used for the DDNAME attribute on the TDQUEUE resource definition.

The TDQ should have a record size of 80 bytes, the same as each line of JCL that is submitted to the internal reader. The BLOCKFORMAT should also be BLOCKED so that the TDQ waits until the termination characters are found.

In a user application, you can use the following command to write JCL line by line:
EXEC CICS WRITEQ QUEUE(XXXX) TD FROM(_JCLLINE_)
When the JCL needs to be terminated and submitted to the internal reader, a final WRITEQ can be performed specifying the EOF terminator:
EXEC CICS WRITEQ(XXXX) TD FROM("/*EOF")

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=job_userid

CICS can perform 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 (job_userid in this example).

For information on how to enable this additional surrogate check, see CICS surrogate user checking.

If the surrogate check fails, a NOTAUTH response is 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 adds a USER parameter to the statement written to the TDQ. The job user ID added is set to the value specified by the JOBUSERID option in the TDQ definition.
//JOBNAME JOB USER=job_userid
If JOBUSERID is not defined in the TDQ definition, the job user ID is set to the CICS region user ID. No additional surrogate checking is done by CICS.
//JOBNAME JOB USER=region_userid

For more information on the TDQ definition, see TDQUEUE resources.

Security when using the SPOOL commands to submit JCL

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

You can submit a JCL by using a SPOOLOPEN command with USERID("INTRDR") specified. SPOOLWRITE commands are used to write the JCL statements.

If the JOB card has a USER parameter, a surrogate check is performed to verify whether the task user ID has permission to submit jobs on behalf of the job user ID.

For information on how to enable this surrogate check, see CICS surrogate user checking.

If the surrogate check fails, a NOTAUTH response is 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 the JOB card doesn't have a USER parameter, the job user ID defaults to a user ID that is set elsewhere:
  • 6.2 and later The job user ID defaults to the user ID that is set by the INTRDRJOBUSER system initialization parameter. By the default of INTRDRJOBUSER, the task user ID is assumed, and no additional surrogate checking is done by CICS. It is also possible to set INTRDRJOBUSER to use the CICS region user ID instead of the task user ID as the default job user ID, in which case it is subject to a surrogate check.
  • 6.1 The job user ID defaults to the region user ID. This is subject to a surrogate check. You can change the default for the job user ID to be the task user ID if you set the following feature toggle: com.ibm.cics.spool.defaultjobuser=TASK .

z/OS® surrogate user checking

Although the SPOOLWRITE and WRITEQ TD commands are issued by the task user ID, the job is submitted by the CICS region user ID. Therefore, if the job user ID is not the CICS region user ID and no password is supplied, you must grant the CICS 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 CICS region user IDs to be able to submit jobs on behalf of any user, it is recommended that the CICS 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 fails with an ICH408I message issued to the console and job log, but no response is 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 is enabled if:
  • 6.2 and later System initialization parameter XUSER=YES is in effect.
  • 6.1 System initialization parameter XUSER=YES is in effect and 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 task user ID and no password is supplied, you need to grant the task 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(task_userid) ACCESS(READ)

If a surrogate check is applicable, it takes place when the SPOOLWRITE or WRITEQ TD command writes the JOB card. If the check fails, the command fails with a NOTAUTH response. In addition, DFHXS1111 (6.2 and later and DFHXS1117) messages are issued to the CICS log, and an ICH408I message is issued to the console and job log.

ICH408I USER(job_userid) GROUP(group) NAME(username) SUBMITTER(task_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.