Configuring security definition capture (SDC)

6.2 Applies to 6.2.

To manually capture required security definitions for applications during the development process, you must configure CICS security definition capture (SDC) within the region where the application is invoked.

If you want to capture required security definitions automatically, consider using security definition validation (SDV) instead. SDV is a CICS-provided example implementation of a full CI pipeline that utilizes SDC within its automated testing stage and initiates an approval process for any security definition changes. SDV can reuse existing SDC configurations, but it can also configure SDC in CICS regions where SDC doesn't already exist. This is configurable through the Galasa SDV Manager CPS properties. For an example, see Introducing Security Definition Validation to your CICS TS Application CI pipeline.

For more information about how SDC or SDV works, see How it works: Capturing and validating security definitions during the development process.

Before you begin

Your CICS region needs to be at CICS® TS 6.2 or later. It also needs to have SEC=YES defined in the SIT. Other security parameters are optional.

You must have already set up security request recording (SRR) within the region where the application is invoked. Ignore the step that gives users UPDATE authority to the SECRECORDING command.

Users who need to use SDC, such as developers and testers, must have authority to run the CXSD transaction, regardless of the interface that's used.

About this task

When developers or testers perform application tests while SDC is on, CICS captures the security definitions required to run the application.

You can start or stop SDC in either of the following ways:
  • For 3270 applications, by running the CXSD transaction
  • For the other applications, by calling the HTTP REST interface

When SDC stops, CICS submits a JCL job to process and output the required security definitions. The output security definitions are exported into security metadata in the format of YAML. The job can be submitted in either of the two ways: through a TDQUEUE or by writing it to SPOOL. How the job is submitted depends on the CICS configuration.

A sample JCL is provided at USSHOME/security/sdc.jcl, which you can customize for the job submission.

Procedure

  1. Copy the sample JCL (sdc.jcl) from USSHOME/security into USSCONFIG/security, where USSCONFIG is the location specified on the USSCONFIG SIT parameter.
    The file name must be sdc.jcl.
  2. Customize the JCL as follows:
    hlq
    Is the HLQ path of your CICS libraries. Change hlq to the installed library’s high-level qualifier.
    LOGSTRM

    Must remain as '&logstream'. CICS will substitute this value with the DFHSECR log stream journal name.

    For more information, see Configuring security request recording (SRR).

    ID
    Must remain as '&matchid'. CICS will substitute this value with the correct match ID generated by SDC.
    CYL
    Specifies the size of the temporary files that are used by the JCL. By default, the value CYL=5 is used. If you are using a very busy test system, you might experience B37 abends (Data set size is smaller than output). In that case, increase this value.
    HOURS
    Specifies, in hours, the maximum period of the data that is to be read from the log stream. The default is 24 hours. Data captured for the test must have been written within this period. If you have a very busy test system, you might want to reduce this value.
  3. Decide which method of job submission is to be used to process the captured security definitions and output the security metadata. The job can be submitted with either of the following methods:
    Transient data queue (TDQ)
    1. A TDQUEUE resource definition named CXST is provided in the DFH$XSD sample for the job submission. The JOBUSERID attribute must be set to that of someone with authority to view the security metadata, such as a security administrator.
    2. Add the DDNAME value to the CICS JCL that points to the internal reader (INTRDR), for example: 
      //CXST DD SYSOUT=(A,INTRDR),DCB=(RECFM=F,LRECL=80)
      Note:

      CXST is a protected TDQUEUE and can only be written to by internal CICS programs.

    3. Grant the users who need to invoke SDC surrogate authority to submit jobs on behalf of the job user ID. For more information, see Security for submitting a JCL job to the internal reader.
    SPOOL
    1. Set the SPOOL system initialization parameter to YES.
    2. Ensure that the INTRDRJOBUSER system initialization parameter is set to TASK so that the job runs under the task user ID.
    3. Grant the users who need to invoke SDC access to submit jobs under their user IDs. For more information, see Security for submitting a JCL job to the internal reader.
  4. If you're using the CXSD transaction to test a 3270 application. No further configuration is required.
  5. If you're using the HTTP REST interface to test the other applications, complete the following steps:
    1. Copy the DFH$XSDT TCPIPSERVICE resource definition from the DFH$XSD sample group to a new group and customize the following attributes:
      PORTNUMBER
      Specify a dedicated port on which CICS listens for incoming requests for SDC.
      AUTHENTICATE
      At a minimum, specify basic authentication (BASIC) for authenticated user to invoke SDC.
    2. Copy the DFH$XSDU URIMAP resource definition from the DFH$XSD sample group to the new group and customize the following attributes:
      SCHEME
      Specify either HTTP or HTTPS.
      TRANSACTION
      Must specify CXSD so that only relevant security definitions are captured during the process.
      TCPIPSERVICE
      Specify the name of the TCPIPSERVICE definition you configured in Step 5.a.
    3. Install your new group that contains the TCPIPSERVICE and URIMAP resources. Add the group to a LIST in the region's group lists.
    4. Check whether the REST interface is configured successfully by sending an HTTP GET request without parameters to the endpoint. The endpoint derives from the hostname and port configured in the TCPIPSERVICE definition and the path in the URIMAP definition, for example, http://endpoint:port/dfhsdc.

      If the interface is configured successfully, an HTTP response is returned. The response includes a JSON body that indicates the SDC status and a response code and message, for example:

      HTTP/1.1 404 NOT FOUND 
{
  "srr_id": null,
  "message": "SDC IS NOT SWITCHED ON"
}

Results

You have configured SDC in your CICS region.