Verify that security is set up for the domain administrator

You can verify that security is set up correctly for the domain administrator role in IBM Cloud® Provisioning and Management for z/OS®. To do so, you can add an IBM-supplied template to the Software Services catalog and test run the template. This verification is referred to as performing the installation verification procedure or IVP for IBM Cloud Provisioning and Management for z/OS.

Before you begin

The IVP is supplied by IBM in the following location on your system: /usr/lpp/samples/cpm-sample-ivp/

The IVP contains the following parts:
cloud-provisioning-ivp-workflow.xml
Workflow definition file for the provisioning workflow.
cloud-provisioning-ivp.properties
Contains values for the console command and unsolicited message.
cloud-provisioning-ivp-actions.xml
Actions file that defines only a deprovision action.
cloud-provisioning-ivp-AdministratorDoc.pdf
Documentation file for the IVP.
cloud-provisioning-ivp.mf
Manifest file. This file provides a shortcut when you create the template. Rather than specifying each of the aforementioned files in the template individually, you can specify just the manifest file, then click Load to supply values for the other files.

About this task

The IVP contains a template that runs a provisioning workflow under your user ID.

The workflow consists of two steps:
  • If Step 1 completes successfully, your user ID is set up correctly for issuing operator commands. This step issues the START command to start a non-existent job (IZUTEST), which results in an unsolicited message (IEFC452I) when the job is not found. To issue the command, the step uses a REST service.
  • If Step 2 completes successfully, your user ID is set up correctly for reading messages that are written to the operations console. This step checks the result of the previous step for the presence of unsolicited message IEFC452I.

To perform the IVP, your user ID must be authorized as a domain administrator. If your installation defined security as described in Steps for setting up security or by using the IZUPRSEC sample job, the user IDs in the IZUADMIN group are authorized as domain administrators.

Procedure

  1. Add the sample template to the software services catalog.
    1. Log in to z/OSMF with a domain administrator user ID.
    2. Start of change In the z/OSMF desktop view, select Software Services. End of change
    3. Select the Templates tab.
    4. In the Templates table, click Add Template, then select Standard to use a standard template.
      If Add Template is not available, it might be because you are not a domain administrator. If so, contact your system programmer or security administrator for assistance.
    5. On the page that is displayed, supply the required values, as follows:
      1. For Template source file, specify the absolute z/OS UNIX path of the template manifest file for the IVP: /usr/lpp/zosmf/samples/cpm-sample-ivp/cloud-provisioning-ivp.mf
      2. Click Load to supply values for other fields on the window.
      3. Specify a template name, for example, SampleIVP.
      4. Optionally, select the Workflows disposition and Jobs disposition to delete the workflow and job on completion. The default is keep, which means that the workflow and job are preserved. You can remove them later, if you prefer.
      5. Click OK. The template is added to the software services catalog.
  2. Associate the template with the default tenant and create a resource pool.
    1. In the Templates table, select the template by clicking the check box for the template that you created, then click Actions > Associate Tenant.
    2. On the Associate Tenant window, accept the defaults. For resource pool selection, ensure that Create a dedicated resource pool is selected.
      A dedicated resource pool is allocated only to this template. In contrast, a shared resource pool can be used by multiple templates.
    3. Click OK.
      The Resource Management task opens to the Add Template and Resource Pool for Tenant window.
    4. On the Add Template and Resource Pool for Tenant window, enter the following values:
      • For the software services instance name prefix, specify a meaningful value, such as IVP.
      • For the maximum number of software services instances, specify a low value, such as 10.
      • The instance runs under Job Class A, which is the IBM default. If this job class is defined and active at your installation, you can use it. Otherwise, you must include a JOB statement with a valid job class job in the Add Template and Resource Pool for Tenant window. You can optionally include other JCL values on the JOB statement, such as the accounting information.
    5. Click OK.
      If message IYURP0013I is displayed, click OK to continue.
      The resource pool for the template is created with no network or workload management resources.
    6. Having used the Resource Management task to add a template to the tenant, return now to the Software task. Click the Software Services tab.
  3. Test run the template to provision a software instance.
    1. In the Templates table, select the template that you created.
      Notice that the template is in Draft state, which means that the template is ready to be provisioned.
    2. Click Actions, then select Test Run.
    3. Click OK.
      Message IYUSC0032I is displayed to indicate that the software services instance is started.
      If you used the suggested values, the instance name is ConsoleCommand_IVP00.
  4. Verify that the template is provisioned.
    1. Click the Instances tab.
    2. In the Instances table, check the state of your instance.
      • If the template state is Being Provisioned, click Refresh to refresh the table display. Provisioning might take several minutes to complete.
      • If the template state is Provisioning-Failed, your user ID needs an extra security authorization. Proceed to Step 5 and Step 6 for actions to take to resolve the problem.
      • If the template state is Provisioned, you started the instance successfully. Skip to Step 7.
  5. Determine which step failed.
    1. In the Instances table, click the instance name.
      The Instance details tab is shown, which includes the following details about the instance:
      • Domain name (default)
      • Tenant name (default)
      • Name of the provisioning workflow. The workflow name follows the convention ConsoleCommand_<prefix><instance-count>provision<generated string>.
    2. Click the workflow name to navigate to the workflow.
    3. In the workflow, check for the following results:
      1. Step 1 is Complete or Failed.
      2. Step 2 is Complete or Failed.
  6. Resolve the step failure.
    1. Work with your system programmer or security administrator to add the missing authorizations to your user ID.
      • If Step 1 failed, your user ID is not authorized to issue console commands.
      • If Step 2 failed, your user ID is not authorized to a console for viewing the unsolicited message.

      For the required authorizations, see the sample security job for z/OSMF console services (IZUGCSEC) in SYS1.SAMPLIB.

    2. Repeat Steps 1-4 of this procedure.
  7. Deprovision the instance.
    1. In Software Services, select the Instances tab.
    2. In the Instances table, select the instance that you created.
    3. Click Actions > Perform > Deprovision.
    4. In the Perform deprovision window, click OK.

What to do next

For a more advanced test of your security setup, you can create and test run a template that requires approval from a specified approver. In a production environment, the approver might be a middleware system programmer or a security administrator.

To perform this test, you create a new template based on the one you created previously. This time, you modify the workflow input variable file that was supplied with the IVP to add a performer (a runAsUser) and an approver for the template. You repeat some of the steps you performed in the previous procedure.

Follow these steps:
  1. In the Templates table, select your template.
  2. Create another template based on the one you created previously:
    1. Click Actions > CreateBased on.
      1. For Template name, specify the name of a new template, for example SampleIVP2.
      2. For Target file path, specify the name of an empty or non-existent directory, for example: /tmp/xxx. If the directory does not exist, z/OSMF attempts to create it.
      3. For Domain, select default to use the default domain.
    2. Click OK to create the template. The template is created in a draft state.
  3. Associate the template with the default tenant and create a resource pool, as you did in Step 2 of the previous procedure. If message IYURP0013I is displayed, click OK to continue.
  4. Specify a run-as-user and an approver for the template, as follows:
    1. Select Templates > Modify > Edit path, which opens the Workflow Editor.
    2. In the Workflow Editor, click the Input Properties tab, then specify your own user ID for the properties CONSOLE_ADMIN and CONSOLE_APPROVER.
      Tip: In Cloud Provisioning, when a template specifies a user ID under which a step must be performed, an approval record is created. Here, the user ID is referred to as the runAsUser ID for the step. Approval records must be approved by the approvers before the template can be run or published.
      In the example that follows, IBMUSER is specified for both properties. 
      # Licensed Materials - Property of IBM
# 5650-ZOS
# Copyright IBM Corp. 2018
#
# Status = HSMA230
#-------------------------------------------------------------------------------
#
# This is the command that will be issued
# via the z/OSMF REST Consoles API
#
CONSOLE_CMD = S IZUTEST#
# This is  the unsolicited keyword that
# z/OSMF REST Consoles API should expect
# in the response to the CONSOLE_CMD.
#
UNSOL_KEY_TO_DETECT = IEFC452I#
# This is the console Administrator user ID
# that should be used to issue the
# z/OSMF REST Consoles API if the user ID
# running the template does not have appropriate
# authorization.
#
CONSOLE_ADMIN = ibmuser
#
# This is the console Approval user ID used
# for approving the usage of the console
# Administrator user ID specified by
# the ADMIN_CONSOLE variable.
#
CONSOLE_APPROVER = ibmuser
    3. Click Save to save the input properties file.
    4. Close the Workflow Editor window.
  5. In the Templates > Modify page, click OK.
  6. In the Templates table, check the state of the template:
    • If the template state is Pending security update, click Refresh to refresh the table display.
    • If the state is Draft pending approval, the template requires approval. Resolving this state requires the approver user ID that you specified earlier to approve the template.
  7. Approve the template:
    1. In the Templates table, select the template that is in Draft pending approval state, then click Actions > Approvals.
    2. In the Approvals window, review the item to approve.
    3. To approve the template, select the row, then click Actions > Approve.
    4. Return to the Templates table. Notice that the template is now Draft approved.
  8. Test run the template by clicking Actions, then Test Run.
  9. In the Instances table, check the state of your instance:
    • If the template state is Being Provisioned, click Refresh to refresh the table display. Provisioning might take several minutes to complete.
    • If the template state is Provisioning-Failed, resolve the errors for any failed steps and test run the template again.
    • If the template state is Provisioned, you started the instance successfully.
  10. Deprovision the instance.

You can remove the template from the software services catalog when you are done.

Exploring this function further: Try running the IVP with other user IDs specified for the CONSOLE_ADMIN and CONSOLE_APPROVER properties. When these user IDs do not match, Cloud Provisioning automatically generates an additional approval record for your security administrator to approve. This behavior helps to ensure that security is maintained when provisioning is performed under different user IDs.

In the Workflow Editor:
  • For CONSOLE_ADMIN, specify the user ID under which the template is to run. This user ID requires the authority to enter commands from the z/OS operations console. Typically, this person is a middleware system programmer who provisions templates at your company.
  • For CONSOLE_APPROVER, specify the user ID of the person who must approve the provisioning of the template.

Avoid using a functional user ID for the approver. The approver user ID must be able to log in to z/OSMF.