Run as User Configuration

The following API commands enable you to configure the Run as User accounts:

config server:runasuser::add

The config server:runasuser::add command enables you to add a new user to the list of users that are available for running jobs on an Agent. Whenever you define a job, you can choose a Run as User from the list of predefined users.

Before adding a new Run as User, you might want to use the config server:runasuser::test command to test the connection to the user and verify the authentication details that you defined in your configuration file.

The following video demonstrates how to manage Run as Users: https://youtu.be/Xfv-2UStyBE

CLI Syntax

Copy 
ctm config server:runasuser::add <server> <agent> <user> [password] [-f <configuration file>]

The following table describes the config server:runasuser::add command parameters.

Parameter

Description

server

Name of Control-M/Server.

agent

Name of host or alias of the Agent.

Admins with full config authorization can use All for all Agents.

user

Name of user.

password

A valid password for the specified user.

You can also specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence.

configuration file

Full path to a JSON file that contains authentication details for the Run as User. You can choose one of the following options:

  • Password Authentication: A password for the user, either plain text or a predefined secret.

  • Key Authentication: A key and passphrase for an SSH connection to a remote host. The passphrase can be either plain text or a predefined secret.

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

Content of Configuration File

  • The following example configuration file contains a password in plain text:

    Copy 
    {
       "password": "pass1"
    }

  • The following example configuration file contains the name of a predefined secret instead of a password:

    Copy 
    {
       "password": "Secret:topSecretPassword"
    }

  • The following example configuration file contains key authentication details for an SSH connection. In this example, the passphrase is specified as a predefined secret:

    Copy 
    {
       "key": 
       {
          "keyname": "keyName",
          "passphrase": "Secret:topSecretPassphrase"
       }
    }

REST API Syntax

In the following cURL example, note that the path to the configuration file is prefixed with an @ (at) character.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$server/runasuser"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

When using a REST API command to add a Run as User, the configuration file must contain full user credentials, including the Agent and user name, as shown in the following example.

In this example, authentication details are for an SSH connection to a remote host (based on a key and passphrase).

Copy 
{
   "user": "user1",
   "agent": "All",
   "key": 
   {
      "keyname": "keyName",
      "passphrase": "passphrase1"
   }
}

config server:runasuser::get

The config server:runasuser::get command enables you to get the details of a specific Run as User. You can use this command to verify that a certain user exists in the list of defined users. Each Run as User is uniquely identified by its combination of Agent and user name.

CLI Syntax

Copy 
ctm config server:runasuser::get <server> <agent> <user>

The following table describes the config server:runasuser::get command parameters.

Parameter

Description

server

Name of Control-M/Server.

agent

Name of host or alias of the Agent.

Admins with full config authorization can use All for all Agents.

user

Name of user.

If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

REST API Syntax

cURL:

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader"
$endpoint/config/server/$server/runasuser/realAgent/user1

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server:runasuser::update

The config server:runasuser::update command enables you to update the authentication parameters of an existing Run as User. Each Run as User is uniquely identified by its combination of Agent and user name.

Before updating the Run as User, you might want to use the config server:runasuser::test command to test the connection to the user and verify the validity of the user's authentication details.

CLI Syntax

Copy 
ctm config server:runasuser::update <server> <agent> <user> [password] [-f <configuration file>]

The following table describes the config server:runasuser::update command parameters.

Parameter

Description

server

Name of Control-M/Server.

agent

Name of host or alias of the Agent.

Admins with full config authorization can use All for all Agents.

user

Name of user.

If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

password

A new valid password for the specified user.

You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence.

password

Full path to a JSON file that contains authentication details that you want to update for the Run as User. You can choose one of the following options:

  • Password Authentication: A password for the user, either plain text or a predefined secret.

  • Key Authentication: A key and passphrase for an SSH connection to a remote host. The passphrase can be either plain text or a predefined secret.

For an example of the contents of a configuration file, see the description under the config server:runasuser::add command.

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The REST API command specifies the Agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). In the following cURL example, note that the path to the configuration file is prefixed with an @ character.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$server/runasuser/realAgent/user1"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server:runasuser::delete

The config server:runasuser::delete command enables you to deletes a Run as User from the list of users that are available for running jobs on an Agent. Each Run as User is uniquely identified by its combination of Agent and user name.

CLI Syntax

Copy 
ctm config server:runasuser::delete <server> <agent> <user>

The following table describes the config server:runasuser::delete command parameters.

Parameter

Description

server

Name of Control-M/Server.

agent

Name of host or alias of the Agent.

Admins with full config authorization can use All for all Agents.

user

Name of user.

If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

If annotation is enabled for the Configuration Management category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader"
-X DELETE $endpoint/config/server/$server/runasuser/realAgent/user1

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server:runasuser::test

The config server:runasuser::test command enables you to test the connection for a Run as User that you specify. You can use this command in the following ways:

  • Specify the Agent and user name in the command line, but do not specify authentication credentials. This is especially useful for verifying the validity of the credentials of a defined Run as User before you use the config server:runasuser::update command to update the user's authentication parameters.

  • Specify also the password in the command line or specify authentication details in a configuration file. This is especially useful for verifying the validity and connectivity of a user before you use the config server:runasuser::add command to add the user to the list of Run as Users.

CLI Syntax

Copy 
ctm config server:runasuser::test <server> <agent> <user> [password] [-f <configuration file>]

The following table describes the config server:runasuser::test command parameters.

Parameter

Description

server

Name of Control-M/Server.

agent

Name of host or alias of the Agent.

The All value is not supported when testing a Run as User.

If this Run as User is associated with all Agents, you can test it against any individual Agent. In this case, the password is required.

user

Name of user.

If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. For example, for a Windows domain account domainA\userB, specify domainA%5CuserB.

password

A password to test for the specified user.

You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence.

configuration file

Full path to a JSON file that contains authentication details of the Run as User.

For an example of the contents of a configuration file, see the description under the config server:runasuser::add command.

REST API Syntax

cURL:

  • Example for testing an existing user:

    Copy 
    server=controlm
    AuthHeader="x-api-key: $token"
    # AuthHeader="Authorization: Bearer $token"  #for a session token

    curl -H "$AuthHeader"
    -H "Content-Type: application/json" --data "{}"
    -X POST $endpoint/config/server/$server/runasuser/realAgent/user1/test

    To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

    For this test, a configuration file is not necessary, because authentication details are not required.

  • Example for testing a user that has not yet been added:

    Copy 
    server=controlm
    AuthHeader="x-api-key: $token"
    # AuthHeader="Authorization: Bearer $token"  #for a session token

    curl -H "$AuthHeader"
    -H "Content-Type: application/json" --data "@runasUserDefinition.json"
    -X POST "$endpoint/config/server/$server/runasuser/realAgent/user1/test"

    To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

    For this test, the REST API command specifies the Agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). The path to the configuration file is prefixed with an @ (at) character.

config server:runasusers::get

The config server:runasusers::get command enables you to get details about all Run as Users that match a specified search criteria. The response matches the user level of authorization.

CLI Syntax

Copy 
ctm config server:runasusers::get <server> [-s <query string>]

The following table describes the config server:runasusers::get command parameters.

Parameter

Description

server

Name of Control-M/Server.

query string

A string to search for, with the following format:
"field1=criteria1&field2=criteria2"

You can include the following fields in the query string:

  • agent

  • user

agent=agent1*& user=user1*

REST API Syntax

cURL:

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/server/$server/runasusers?agent=agent1&user=user1"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.