Capturing security definitions during development using security definition capture

6.2 and later Applies to 6.2 and later.

Security definition capture (SDC) enables an application developer to capture the security definitions required by an application during their development process. You start SDC before testing an application to record security definitions that are required by the application if security were on. You can invoke SDC through either the CXSD transaction or an HTTP REST interface, depending on the applications to be tested.

These instructions describe how to start and stop SDC manually in a manual testing scenario. Alternatively, you can automate the control of SDC and application testing, for example, by using the Galasa SDV Manager. See Introducing Security Definition Validation to your CICS TS Application CI pipeline for an example.

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

  • You must have already configured SDC in the CICS® region where the application is to be invoked.
  • Developers have installed the CICS applications to be tested in the development region as usual.
  • The region where SDC runs is defined with SEC=YES. However, other security SIT parameters are optional. SDC captures the required security definitions irrespective of those SIT parameters.

About this task

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
Recommendation: It's recommended that whoever invokes SDC use their user ID that is dedicated to testing or development and do not perform other tasks in the system during the testing. This way, SDC records only the security definitions that are relevant to the application. This means:
  • If you're using the CXSD transaction, you need to sign on to CICS using a dedicated user ID before running CXSD.
  • If you're calling the HTTP REST interface, you need to supply a dedicated user ID when prompted for a user ID.

You can follow the procedure to collect a baseline of the application’s required security definitions, or repeat it to continuously compare required changes to the security definitions for maintenance.

Capturing security definitions for 3270 applications

To test 3270 applications, the developer runs the CXSD transaction to start and stop SDC.

  1. When the application is ready for testing, invoke CXSD ON to start SDC of the terminal.
  2. While SDC is on, perform manual testing as usual, ensuring the range of paths are tested.
  3. Invoke CXSD OFF to stop SDC, which results in a message that indicates the SDC job has been submitted.

Capturing security definitions for the other applications

To test applications of the other types, the developer starts and stops SDC through the HTTP REST interface. The endpoint takes the form of http://endpoint:port/dfhsdc, depending on the configuration described in Configuring security definition capture (SDC).

  1. To start SDC, send a POST request without any input parameters to the endpoint.

    If SDC is started successfully, you will see this response.

    HTTP/1.1 201 Created
{
  "srr_id": "_1053208",
  "message": "SDC HAS BEEN SWITCHED ON"
}

    For a complete list of all responses of the SDC calls, see Responses to SDC HTTP calls.

  2. While SDC is on, perform manual testing as usual, ensuring the range of paths are tested.
  3. When testing is complete, send a DELETE request to stop SDC and submit a job automatically. The request body must be in the JSON format, for example:
    {
  “submit”: true
}
    submit

    Controls whether a job is submitted when SDC stops.

    It is a boolean value: true or false. If no parameter is specified, true is the default.

    When set to true, a job is submitted automatically when SDC stops.

    If you want to submit the JCL yourself, you can set it to false to stop SDC without submitting a job.

Result

You have captured required security definitions for the tested applications. The required security definitions are output into security metadata.

You can check the job is submitted and completes successfully based on configuration described in Configuring security definition capture (SDC).

What's next

  1. Review the results of the batch job.

    If you have configured SPOOL to submit the job that generates the security metadata, the job is submitted under your user ID. You need to pass the results to the reviewer.

    If you have configured the CXST TDQUEUE to submit the job, the job is submitted under the user ID specified on the JOBUSERID attribute of the TDQUEUE. This user is often the reviewer.

    The reviewer must be in a role that has authority to view sensitive security definitions, such as a security administrator. The reviewer then ensures that the required security definitions as indicated in the security metadata are expected.

  2. When the security metadata is verified, the security administrator updates security definitions in the ESM. The user ID in the security metadata is replaced by a group name representing the role of the user who uses the applications.