Server Security Configuration

The following API commands enable you to configure Control-M/Server security for Run as Users and groups. You can authorize which Run as Users or groups can run a certain job and which actions they are authorized to perform, such as add a folder, edit a job or force a job:

• config server:security:group::add

• config server:security:group::delete

• config server:security:group::update

• config server:security:user::add

• config server:security:user::delete

• config server:security:user::update

• config server:security:entities::get

• config server:security:attributes::get

• config server:security:attributes::update

config server:security:group::add

The config server:security:group::add command enables you to define security authorizations for a group of Run as Users.

CLI Syntax

ctm config server:security:group::add <server> -f <configuration file>

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

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

REST API Syntax

server=IN01
curl -X POST -H "x-api-key: $token" -H "Content-Type: application/json" \
--data "@c:\tmp\ConfigFile.json" \
"$endpoint/config/server/$server/security/group"

config server:security:group::delete

The config server:security:group::delete command enables you to delete a defined group with all its defined security authorizations.

CLI Syntax

ctm config server:security:group::delete <server> <groupname>

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

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

REST API Syntax

server=IN01
group=firstGroup
curl -X DELETE -H "x-api-key: $token" \
"$endpoint/config/server/$server/security/group/$group"

config server:security:group::update

The config server:security:group::update command enables you to update the basic settings of a group, including the group name and description.

CLI Syntax

ctm config server:security:group::update <server> <groupname> -f <configuration file>

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

{ 
   "name": "Group1", 
   "description": "updated group desc"  
}

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

REST API Syntax

server=IN01
group=firstGroup
curl -X POST -H "x-api-key: $token" -H "Content-Type: application/json" \
--data "@c:\tmp\ConfigFile.json" \
"$endpoint/config/server/$server/security/group/$group"

config server:security:user::add

The config server:security:user::add command enables you to define security authorizations for a Run as User.

CLI Syntax

ctm config server:security:user::add <server> -f <configuration file>

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

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

REST API Syntax

server=IN01
curl -X POST -H "x-api-key: $token" -H "Content-Type: application/json" \
--data "@c:\tmp\ConfigFile.json" \
"$endpoint/config/server/$server/security/user"

config server:security:user::delete

The config server:security:user::delete command enables you to delete a defined Run as User with all its defined security authorizations.

CLI Syntax

ctm config server:security:user::delete <server> <username>

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

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

REST API Syntax

server=IN01
user=user123
curl -X DELETE -H "x-api-key: $token" \
"$endpoint/config/server/$server/security/user/$user"

config server:security:user::update

The config server:security:user::update command enables you to update the basic settings of a user, including the username, description, and group association.

CLI Syntax

ctm config server:security:user::update <server> <username> -f <configuration file>

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

{ 
   "name": "user1", 
   "description": "new desc",  
   "group": "updated_group"
}

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

REST API Syntax

server=IN01
user=user123
curl -X POST -H "x-api-key: $token" -H "Content-Type: application/json" \
--data "@c:\tmp\ConfigFile.json" \
"$endpoint/config/server/$server/security/user/$user"

config server:security:entities::get

The config server:security:entities::get command enables you to get a current list of groups and users that were assigned security authorizations.

CLI Syntax

ctm config server:security:entities::get <server>

where server is the name of a Control-M/Server.

REST API Syntax

server=IN01
curl -H "x-api-key: $token" "$endpoint/config/server/$server/security/entities"

config server:security:attributes::get

The config server:security:attributes::get command enables you to get the list of attributes defined for a group or user.

You can use the response from this command as the starting point for a configuration file that you submit when you use the config server:security:attributes::update command to update a group or user.

CLI Syntax

ctm config server:security:attributes::get <server> <entity name> 

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

REST API Syntax

server=IN01
group=group6
curl -H "x-api-key: $token" "$endpoint/config/server/$server/security/attributes/$group"

config server:security:attributes::update

The config server:security:attributes::update command enables you to update the security attributes of a group or user.

CLI Syntax

ctm config server:security:attributes::update <server> <entity name> -f <configuration file>

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

REST API Syntax

server=IN01
user=user123
curl -X POST -H "x-api-key: $token" -H "Content-Type: application/json" \
--data "@c:\tmp\ConfigFile.json" \
"$endpoint/config/server/$server/security/attributes/$user"

Security Configuration Files

The following code sample shows the available objects that you can include within a JSON-format security configuration file, which contains definitions of group or user security authorizations. Details about each of these objects and their properties are provided below.

{"user":
  { 
    "name": "newUser1" , 
    "description": "user descr1" ,  
    "group": "some_group1" 
  },
  "securityAttributes": {
    "TableSecAttrs" : {
      "CtmSecTableSecAttrCollection" : [ {
        "Name" : "Folder1",
        "Delete" : "N",
        "Read" : "Y",
        "Update" : "D",
        "Order" : "Y"
      }, {
        "Name" : "Folder2",
        "Delete" : "N",
        "Read" : "N",
        "Update" : "D",
        "Order" : "N"
      } ]
    },
    "ActiveSecAttrs" : {
      "CtmSecActiveSecAttrCollection" : [ {
        "Owner" : "emuser",
        "NodeGroup" : "host",
        "Order" : "D",
        "Force" : "N",
        "Rerun" : "N",
        "Hold" : "N",
        "Confirm" : "N",
        "Delete" : "N",
        "Why" : "Y",
        "Sysout" : "Y",
        "Log" : "Y",
        "Statistics" : "Y",
        "ZoomAndSave" : "Y",
        "KillJob" : "Y"
      }, {
        "Owner" : "user2",
        "NodeGroup" : "bbbbb",
        "Order" : "N",
        "Force" : "N",
        "Rerun" : "N",
        "Hold" : "N",
        "Confirm" : "N",
        "Delete" : "N",
        "Why" : "N",
        "Sysout" : "N",
        "Log" : "Y",
        "Statistics" : "D",
        "ZoomAndSave" : "Y",
        "KillJob" : "D"
      } ]
    },
    "EntitySecAttrs" : {
      "Calendar" : {
        "Add" : "D",
        "Delete" : "Y",
        "Update" : "Y"
      },
      "Condition" : {
        "Add" : "N",
        "Delete" : "D",
        "Update" : "Y"
      },
      "Log" : {
        "Add" : "D",
        "Delete" : "N",
        "Update" : "Y"
      },
      "ControlResource" : {
        "Add" : "D",
        "Delete" : "N",
        "Update" : "D"
      },
      "QuantitativeResource" : {
        "Add" : "Y",
        "Delete" : "D",
        "Update" : "Y"
      }
    }
  }
}

Basic Group or User Definitions

Basic entity definitions are required in the configuration file when you add a new group or user (using the config server:security:group::add or config server:security:user::add command, respectively).

Basic definitions contain one of the following objects:

• A group object with the name and description attributes, as in the following example:

  Copy

  {"group":
    {
      "name": "newGroup1" ,
      "description": "group descr1"
    },

• A user object, with the name, description, and group attributes, as in the following example. The group attribute associates the user with a group, so that the user can inherit group authorizations. If you do not assign a user to a group, the user is created as a root user.

  Copy

  { "user":
    { 
      "name": "newUser1" , 
      "description": "user descr1" ,  
      "group": "some_group1" 
    },

Folder Security Attributes

The first category of security attributes under the securityAttributes object defines folder permissions for the group or user.

Folder security attributes appear under the TableSecAttrs (Table Security Attributes) object, within the CtmSecTableSecAttrCollection array of folders, as in the following example:

  "securityAttributes": {
    "TableSecAttrs" : {
      "CtmSecTableSecAttrCollection" : [ {
        "Name" : "Folder1",
        "Delete" : "N",
        "Read" : "Y",
        "Update" : "D",
        "Order" : "Y"
      }, {
        "Name" : "Folder2",
        "Delete" : "N",
        "Read" : "N",
        "Update" : "D",
        "Order" : "N"
      } ]
    },

Permissions to delete, read, update, and run (order) a folder can have the following values:

• N: No

• Y: Yes

• D: Inherit the default

Monitoring Domain Security Attributes

Security attributes for the Monitoring domain and Active Jobs Database appear under the ActiveSecAttrs object, within the CtmSecActiveSecAttrCollection array, as in the following example:

    "ActiveSecAttrs" : {
      "CtmSecActiveSecAttrCollection" : [ {
        "Owner" : "emuser",
        "NodeGroup" : "host",
        "Order" : "D",
        "Force" : "N",
        "Rerun" : "N",
        "Hold" : "N",
        "Confirm" : "N",
        "Delete" : "N",
        "Why" : "Y",
        "Sysout" : "Y",
        "Log" : "Y",
        "Statistics" : "Y",
        "ZoomAndSave" : "Y",
        "KillJob" : "Y"
      }, {
        "Owner" : "user2",
        "NodeGroup" : "bbbbb",
        "Order" : "N",
        "Force" : "N",
        "Rerun" : "N",
        "Hold" : "N",
        "Confirm" : "N",
        "Delete" : "N",
        "Why" : "N",
        "Sysout" : "N",
        "Log" : "Y",
        "Statistics" : "D",
        "ZoomAndSave" : "Y",
        "KillJob" : "D"
      } ]
    },

Each item in this array is identified by an Owner (Run as User) and NodeGroup (Host). For each item in the array, you can set permissions of Y (Yes), N (No), or D (Inherited Default) for the following monitoring actions:

• Order: Run a job

• Force: Force a job to start executing

• Rerun: Run a job that has already run

• Hold: Stop job processing

• Confirm: Grant user confirmation to a waiting job

• Delete: Delete a held job

• Why: Obtain Waiting Info

• Sysout: Obtain the job output

• Log: Obtain the Activity Log

• Statistics: Obtain job statistics

• ZoomAndSave: Edit job definitions

• KillJob: Terminate a job

For more information about these actions, see Job Management.

Job Planning Security Attributes

Security attributes for the various entities that are involved in job workflow planning appear under the EntitySecAttrs object, as in the following example:

    "EntitySecAttrs" : {
      "Calendar" : {
        "Add" : "D",
        "Delete" : "Y",
        "Update" : "Y"
      },
      "Condition" : {
        "Add" : "N",
        "Delete" : "D",
        "Update" : "Y"
      },
      "Log" : {
        "Add" : "D",
        "Delete" : "N",
        "Update" : "Y"
      },
      "ControlResource" : {
        "Add" : "D",
        "Delete" : "N",
        "Update" : "D"
      },
      "QuantitativeResource" : {
        "Add" : "Y",
        "Delete" : "D",
        "Update" : "Y"
      }
    }

You can set Add, Delete, and Update permissions of Y (Yes), N (No), or D (Inherited Default) for the following types of job-related entities:

• Calendar

• Condition (event)

• Log

• ControlResource (lock resource)

• QuantitativeResource (resource pool)