runAsUser identity for a step

For workflow automation, you can specify the user ID under which a particular step is to be performed by including the element runAsUser (<runAsUser>) on the step element. The value that you specify on the runAsUser element is considered to be the runAsUser ID for the step.

When a runAsUser is not specified for a step, the step is performed under the step owner user ID.

The runAsUser ID element is intended for use with an automated workflow that originates from z/OS Cloud Provisioning. The runAsUser ID element is not applicable in other cases; its use can result in an error that prevents the step from being performed. For the intended use cases, see How a runAsUser ID is used in workflow automation.

If you specify the runAsUser element, you must ensure that the user ID that you specify is (or will resolve to) a valid z/OS user ID. The user ID can be lower case, upper case, or mixed case.

How a runAsUser ID is used in workflow automation

During workflow automation, a step is switched to the runAsUser ID for the operations that are shown in Table 1.
Table 1. How a runAsUser ID is used in workflow processing
Step type Automated operation How the runAsUser ID is used
Template step Step submits a JCL job (a batch execution step). Batch job runs under the runAsUser ID.
Template step Step runs a program in real time (an immediate execution step). Program runs under the runAsUser ID.
Template step Step copies an output file to its own storage. Read action is performed under the runAsUser ID.
Template step that includes the saveAsDataset element. Step writes the template contents to a data set. Save as a data set action is performed under the runAsUser ID.
Template step that includes the saveAsUnixFile element. Step writes the template contents to a UNIX file. Save as a UNIX file action is performed under the runAsUser ID.
REST step Step calls a REST service. REST service is invoked under the runAsUser ID.
For other step types and operations, the runAsUser ID is not applicable. Specifically, the runAsUser ID is not used for the following step types:
  • Instructions steps
  • Calling Steps

Specifying approvers for a step

In z/OS Cloud Provisioning, the runAsUser element is typically used with the approver element, as follows:
  • The runAsUser element (<runAsUser>) specifies the user identity under which the step is to be performed.
  • The approver element (<approver>) specifies who must grant approval before the step can be performed. Up to 12 approvers can be specified for a step. The use of an approver element requires that the runAsUser element by specified.
Various combinations of approvals are supported for the runAsUser element. In the examples that follow, assume that a workflow includes a step that is performed under an authorized administrator identity, which is represented by the runAsUser ID ADMIN-USERID.
  • In the following example, either HIREN or NICK must approve the step: 
    <runAsUser>ADMIN-USERID</runAsUser> 
<approver>HIREN NICK</approver>
  • In the following example, both HIREN and NICK must approve: 
    <runAsUser>ADMIN-USERID</runAsUser> 
<approver>HIREN</approver>
<approver>NICK</approver>
  • In the following example, CONNER and either HIREN or NICK must approve: 
    <runAsUser>ADMIN-USERID</runAsUser> 
<approver>CONNER</approver>
<approver>HIREN NICK</approver>

Using variable substitution

You can use variables to represent the runAsUser ID and approver ID. To indicate that substitution is used, include the attribute "substitution=true" on the element, and specify the substitution string on the element.

In the following example, the variable ADMIN-USERID is used to represent the runAsUser ID for a step: 
<runAsUser substitution="true">${instance-ADMIN-USERID}</runAsUser>

If you use variable substitution, understand that the variable must be an instance variable; it cannot be a global variable.

Static runAsUser IDs

If the runAsUser ID is resolved at workflow creation time, it is considered to be a static runAsUser ID. Here, the value is determined during substitution, by using values from the input properties file. Or, it might be set to a fixed value in the workflow definition.

At workflow creation time, z/OSMF checks the resulting value of substitution to ensure that it is a valid z/OS user ID and is permitted to z/OSMF (that is, permitted to the z/OSMF SAF profile prefix profile in the APPL class). If these checks fail, the workflow cannot be created.

As a recommended practice for a static runAsUser, include the variable in the workflow input properties file. Also, avoid using a variable that can be prompted for at workflow creation. For a description of the prompt= attribute for instance variables, see Using the element atCreate to qualify a variable definition.

Dynamic runAsUser IDs

If the runAsUser ID is assigned during workflow processing, it is considered to be a dynamic runAsUser ID. Suppose, for example, that Step A creates a user ID, which is then used by Step B for performing some action, such as issuing a command.

If a step is associated with a dynamic runAsUser ID, z/OSMF does not validate the runAsUser value at workflow creation time. Instead, the runAsUser value is checked when the step is run. When the step is being performed, the Workflows task processes the variable substitution to derive the actual user IDs for the step.

As a recommended practice for a dynamic runAsUser, use a variable that is not referenced in the workflow input properties file.

How the static or dynamic determination is made

The determination as to which runAsUser values are dynamic and which are static is made at workflow creation time, as follows:
  • If a runAsUser value is defined with substitution=true, it is considered to be dynamic if the initial substitution results in no change to the value.
  • If a runAsUser value is defined with substitution=false, or the initial substitution results in a change to the value, the runAsUser value is considered to be static.
Assume that a runAsUser value is represented by the variable reference ${instance-rau}. Table 2 shows how the static or dynamic determination is resolved for ${rau}, depending on a number of factors, such as whether the variable can be prompted or is pre-specified in the input properties file.
Table 2. Basic usage scenarios: How the static or dynamic determination is made for the runAsUser value
<runAsUser> <atCreate prompt=> <runAsUser substitution= Input properties file? Result of initial substitution Dynamic or static? Notes
${instance-rau} false true Not specified. ${instance-rau} Dynamic Dynamic because there is no change after substitution.
${instance-rau} true true Not specified. ${instance-rau} Dynamic Dynamic because there is no change after substitution.
${instance-rau} false true rau=IBMUSER IBMUSER Static Static because the value changed after substitution.
${instance-rau} true 1 true rau=IBMUSER ${instance-rau} Dynamic Dynamic because there is no change after substitution.
  1. Workflows processing ignores the prompt=true setting for a runAsUser when it resolves the substitution string. Here, the runAsUser value is always determined to be dynamic.