Authorization Configuration

The config authorization service enables you to manage the authorizations of roles and users, as well organization groups and users (such as LDAP or IdP groups and users), limiting their access to various Control-M entities and actions.

You can configure authorizations with the following API commands:

• Role Configuration

• User Configuration

• Organization Group and Organization User Configuration

Role Configuration

The following API commands are available for the configuration of role authorizations:

• config authorization:role::add: Add a role.

• config authorization:role::get: Get role details.

• config authorization:role::update: Update role definitions.

• config authorization:role::delete: Delete a role.

• config authorization:roles::get: Get a list of roles.

• config authorization:role:associates: Get a list of users, organization users, and organization groups to which a role is associated.

config authorization:role::add

The config authorization:role::add command enables you to create a new role based on role settings that you define through a role data file.

CLI Syntax

ctm config authorization:role::add <roleFile>

where roleFile is the full path and name of a .json payload file that contains role definitions, as described in Role Definitions File.

If annotation is enabled for the Account 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

curl -H "x-api-key: $token" -F "[email protected]"
-X POST $endpoint/config/authorization/role

config authorization:role::get

The config authorization:role::get command enables you to get the details of an existing role, as defined in the role data file.

Only parameters that are set to non-default values are retrieved and displayed in the output.

For similar details for a user, calculated from all associated roles, see config authorization:user:effectiverights::get.

CLI Syntax

ctm config authorization:role::get <role>

where role is the name of the role.

REST API Syntax

roleName=myRole
curl -H "x-api-key: $token"
"$endpoint/config/authorization/role/$roleName"

config authorization:role::update

The config authorization:role::update command enables you to update the definitions of an existing role based on role settings that you define through a role data file.

CLI Syntax

ctm config authorization:role::update <role> <roleFile>

The following table describes the config authorization:role::update command parameters.

If annotation is enabled for the Account 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

roleName=myRole
curl -H "x-api-key: $token" -F "[email protected]"
-X POST "$endpoint/config/authorization/role/$roleName"

config authorization:role::delete

The config authorization:role::delete command enables you to delete an existing role and disassociates all users who were associated with the role.

CLI Syntax

ctm config authorization:role::delete <role>

where role is the name of the role.

If annotation is enabled for the Account 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

roleName=myRole
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/authorization/role/$roleName"

config authorization:roles::get

The config authorization:roles::get command enables you to get a list of names of configured roles.

CLI Syntax

ctm config authorization:roles::get [-s <search query>]

The optional -s switch can be used to filter for roles by role name or description (or both). The format for the query string is "field1=criteria1&field2=criteria2", according to the following guidelines:

REST API Syntax

roleName=Adm*
curl -H "x-api-key: $token" $endpoint/config/authorization/roles?role=$roleName

config authorization:role:associates

The config authorization:role:associates command enables you to get a list of all users, organization users, and organization groups to which a specific role is associated.

CLI Syntax

ctm config authorization:role:associates <role>

where role is the name of the role.

REST API Syntax

roleName=myRole
curl -H "x-api-key: $token" $endpoint/config/authorization/role/$roleName/associates

Response

[
{
   "type": "orguser",
   "name": "orgUser"
},
{
   "type": "ldapgroup",
   "name": "AdminGroup"
},
{
   "type": "user",
   "name": "Bob"
}
]

Role Definitions File

The following code sample shows the available objects that you can include within a payload JSON file that contains role definitions. Details about each of these objects and their properties are provided below.

{
    "Name": "AdminRole",
    "Description": "Administration role",
    "OrganizationGroups": ["idp1", "idp2"],
    "OrganizationUsers": ["usr1", "usr2"], 
    "AllowedJobs": {
        "Included": [
           [["Folder", "like", "a*"], ["JobName", "like", "c*,d*"]],
           [["Folder", "like", "b*"], ["JobName", "like", "e*,f*"}]
        ]
    },
    "AllowedJobActions": {
        "ViewProperties": true,
        "SetToOk": true,
        "Documentation": true,
        "Confirm": true,
        "Log": true
    },
    "Privileges": {
        "ClientAccess": {
           "ApplicationIntegratorAccess": "None"
           },
        "ConfigurationManager": {
           "Authorization": "Browse",
           "Configuration": "Full",
            "ControlmSecurity": "Full"
           }   
    },
    "Folders": [{
        "Privilege": "Full",
        "ControlmServer":  "*",
        "Folder": "ccc*",
        "Run": true
    }],
    "Calendars": [{
        "Privilege": "Full",
        "ControlmServer": "*",
        "Name": "bbb*"
    }],
    "RunasUsers": [{
        "ControlmServer": "*",
        "RunasUser": "aaa*",
        "Host": "bbb*"
    }],
    "SiteStandard": [{
        "Privilege": "Full",
        "Name": "*"
    }],
    "SiteCustomization": [{
        "Privilege": "Full",
        "Name": "*"
    }],
    "Services": [{
        "Privilege": "Full",
        "Name": "*",
        "AllowedActions":
            {"DrillDown": true}
    }],
    "Events": [{
        "Privilege": "Full",
        "ControlmServer": "*",
        "Name": "*"
    }],
    "Locks": [{
        "Privilege": "Full",
        "ControlmServer": "*",
        "Name": "*"
    }],
    "Pools": [{
        "Privilege": "Full",
        "ControlmServer": "*",
        "Name": "*"
    }],
    "Variables" : [ {
        "Privilege" : "Full",
        "Name" : "*"
    }],
    "AgentManagement": [
      {
        "ControlmServer": "*",
        "Agent": "agent3",
        "Privilege": "Browse"
      },
      {
        "ControlmServer": "*",
        "Agent": "agent4",
        "Privilege": "Update"
      }
    ],
    "PluginManagement": [
      {
        "ControlmServer": "*",
        "Agent": "agent3",
        "PluginType": "SAP",
        "Privilege": "Browse"
      },
      {
        "ControlmServer": "*",
        "Agent": "agent4",
        "PluginType": "DATABASE",
        "Privilege": "Update"
      }
    ],
    "ConnectionProfileManagement": [
      {
        "ControlmServer": "*",
        "Agent": "agent3",
        "PluginType": "SAP",
        "Name": "cpp3*",
        "Privilege": "Browse"
      },
      {
        "ControlmServer": "*",
        "Agent": "agent4",
        "PluginType": "HADOOP",
        "Name": "cpp4*",
        "Privilege": "Update"
      }
    ],
    "RunasDefinitionManagement": [
      {
        "ControlmServer": "*",
        "Privilege": "Browse"
      }
    ]
}

General Role Settings

The following table describes the general role properties for the role that you are define.

"Name": "AdminRole",
"Description": "Administration role",
"OrganizationGroups: ["idp1", "idp2"],
"OrganizationUsers": ["usr1", "usr2"],

AllowedJobs

Grants the role browse access to the output of jobs that you specify using include filters.

"AllowedJobs": {
    "Included": [
       [["Folder", "like", "a*"], ["JobName", "like", "c*,d*"]],
       [["Folder", "like", "b*"], ["JobName", "like", "e*,f*"}]
    ]
}

The Included object under AllowedJobs lists filters for jobs that the role is authorized to access.

In this list, you can include one or more filters. An implied OR logical operator connects between the various filters.

Each filter can include multiple conditions, with an implied AND logical operator connecting between the conditions. A condition is a pattern-matching expression that detects jobs according to a specific job property. A condition has the following format:

["jobProperty", "operator", "value"]

The following table provides guidelines for specifying the various elements within the filter condition.

AllowedJobActions

Authorizes the role to perform specific actions (browse actions, control actions, or update actions) on the jobs filtered through the AllowedJobs object and the folders specified through the Folders object.

"AllowedJobActions": {
    "ViewProperties": true,
    "SetToOk": true,
    "Documentation": true,
    "Confirm": true,
    "Log": true
}

Under the AllowedJobsActions object, you define which job actions the role is authorized to perform. Each action is set to either true (allowed) or false (not allowed). The default is false.

The following table lists all available job actions. For your convenience, the actions in this table are divided into categories — Browse actionsand Control actions.

Privileges

Grants the role access to various Helix Control-M components, utilities, and tools, and authorizes the role to perform actions through these tools based on the defined access levels.

"Privileges": {
    "ClientAccess": {
       "ApplicationIntegratorAccess": "Full"
       },
    "ConfigurationManager": {
       "Authorization": "Browse",
       "Configuration": "Full",
       "ControlmSecurity": "Full"
       }   
}

Under the Privileges object, various Helix Control-M features and capabilities are categorized and grouped together under the following next-level objects:

• ClientAccess

• ConfigurationManager

• Monitoring

The following table lists all the product features and capabilities in these categories, and provides details of the authorization levels that are available for each feature. The default authorization for all features is None.

* Configuration and ControlmSecurity must be set to the same authorization level. If these features are set to Full, all RBA settings (AgentManagement, PluginManagement, ConnectionProfileManagement, and RunasDefinitionManagement) are regarded as set to Full for all items of each type.

Folders

Grants the role access to specific folders, along with an authorization level for each folder. Also enables you to grant different authorizations per job within a specific folder based on Application or Sub Application criteria.

"Folders": [{
    "Privilege": "Full",
    "ControlmServer":  "*",
    "Folder": "ccc*",
    "Run": true
}]

The following table describes the Folders object properties.

For properties that support multiple values (ControlmServer, Folder, Application, and SubApplication), you can use , (commas) or wildcards (such as * or ?).

Calendars

Associates specific calendars in Control-M with the role, along with an authorization level for each calendar.

"Calendars": [{
    "Privilege": "Full",
    "ControlmServer": "*",
    "Name": "bbb*"
}]

The following table describes the Calendars object properties.

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?).

RunasUsers

Associates "run as" users with the role, for running jobs on an Agent.

"RunasUsers": [{
    "ControlmServer": "*",
    "RunasUser": "aaa*",
    "Host": "bbb*"
}]

The following table describes the RunasUsers object properties.

You must define at least one of these properties. Once one property is defined, the implied value for any other undefined property is "*".

For multiple values in any of these properties, you can use , and wildcards (such as * or ?).

You might also want to specify values to be excluded.

SiteStandard

Associates specific Site Standards with the role, along with an authorization level for each one.

Site Standards are collections of settings that are applied to folders and jobs to ensure that web users follow organization standards.

"SiteStandard": [{
    "Privilege": "Full",
    "Name": "*"
}]

The following table describes the SiteStandard object properties. All parameters are required.

SiteCustomization

Associates specific Site Customizations (also known as user views) with the role, along with an authorization level for each one.

Site Customizations are collections of settings that are applied to jobs to limit web users' access to job properties or to restrict the types of jobs that web users can create.

"SiteCustomization": [{
    "Privilege": "Full",
    "Name": "*"
}]

The following table describes the SiteCustomization object properties. All parameters are required.

Services

Grants the role authorization to view services and to perform job actions, order, hold, and release services.

A service is a group of jobs that are aggregated based on various job filtering criteria.

"Services": [{
    "Privilege": "Full",
    "Name": "*",
    "AllowedActions":
        {"DrillDown": true}
}]

The following table describes the Services object properties.

Events

Grants the role authorization to manage events, by associating specific events with the role and assigning an authorization level to each one.

"Events": [{
    "Privilege": "Full",
    "ControlmServer": "*",
    "Name": "*"
}]

The following table describes the Events object properties.

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?).

Locks

Grants the role authorization to manage locks (previously known as control resources or mutexes), by associating specific locks with the role and assigning an authorization level to each one.

"Locks": [{
    "Privilege": "Full",
    "ControlmServer": "*",
    "Name": "*"
}]

The following table describes the Locks object properties.

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?).

Pools

Grants the role authorization to manage pools (previously known as quantitative resources or semaphores), by associating specific pools with the role and assigning an authorization level to each one.

"Pools": [{
    "Privilege": "Full",
    "ControlmServer": "*",
    "Name": "*"
}]

The following table describes the Pools object properties.

For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?).

Variables

Associates specific variables with the role, along with an authorization level for each one.

Variables enable automatic assignment of dynamic environmental values to the execution parameters of jobs.

"Variables": [{
    "Privilege": "Full",
    "Name": "*"
}]

The following table describes the mandatory Variables object properties.

AgentManagement

Grants the role authorization to manage agents and perform administrative tasks on agents (such as connect an Agent to a Server or configure agent parameters).

This object is used in Role-Based Administration (RBA), enabling an administrator to grant non-administrator roles permission to perform certain administrative tasks.

"AgentManagement": [
  {
     "ControlmServer": "*",
     "Agent": "agent3",
     "Privilege": "Browse"
  },
  {
     "ControlmServer": "*",
     "Agent": "agent4",
     "Privilege": "Update"
  }
]

The following table describes the AgentManagement object properties for each specified Agent.

For properties that support multiple values (ControlmServer and Agent), you can use wildcards (such as * or ?).

PluginManagement

Grants the role authorization to manage Control-M plug-ins and perform administrative tasks on plug-ins (such as plug-in configuration).

This object is used in Role-Based Administration (RBA), enabling an administrator to grant non-administrator roles permission to perform certain administrative tasks.

"PluginManagement": [
  {
    "ControlmServer": "*",
    "Agent": "agent3",
    "PluginType": "SAP",
    "Privilege": "Browse"
  },
  {
    "ControlmServer": "*",
    "Agent": "agent4",
    "PluginType": "DATABASE",
    "Privilege": "Update"
  }
]

The following table describes the PluginManagement object properties for, each specified plug-in.

For properties that support multiple values (ControlmServer, Agent, and PluginType), you can use wildcards (such as * or ?).

ConnectionProfileManagement

Grants the role authorization to manage connection profiles and perform administrative tasks on connection profiles (such as create, update, or delete a connection profile).

This object is used in Role-Based Administration (RBA), enabling an administrator to grant non-administrator roles permission to perform certain administrative tasks.

"ConnectionProfileManagement": [
  {
    "ControlmServer": "*",
    "Agent": "agent3",
    "PluginType": "SAP",
    "Name": "cpp3*",
    "Privilege": "Browse"
  },
  {
    "ControlmServer": "*",
    "Agent": "agent4",
    "PluginType": "HADOOP",
    "Name": "cpp4*",
    "Privilege": "Update"
  }
]

The following table describes the ConnectionProfileManagement object properties for each specified connection profile.

For properties that support multiple values (ControlmServer, Agent, PluginType, and Name), you can use wildcards (such as * or ?).

RunasDefinitionManagement

Grants the role authorization to manage the configuration of "run as" users (that is, to perform administrative tasks such as create, update, or delete a "run as" user).

This object is used in Role-Based Administration (RBA), enabling an administrator to grant non-administrator roles permission to perform certain administrative tasks.

"RunasDefinitionManagement": [
  {
    "ControlmServer": "*",
    "Privilege": "Browse"
  }
]

The following table describes the RunasDefinitionManagement object properties for each authorization.

User Configuration

The following API commands are available for the configuration of user authorizations:

• config authorization:user::add: Adds a user.

• config authorization:user::get: Gets user details.

• config authorization:user::update: Updates user definitions.

• config authorization:user::delete: Deletes a user.

• config authorization:users::get: Get a list of users.

• config authorization:user:effectiverights::get: Gets details of effective authorizations for a user.

config authorization:user::add

The config authorization:user::add command enables you to create a new user based on user settings that you define through a user data file.

CLI Syntax

ctm config authorization:user::add <userFile>

where <userFile> is the full path and name of a .json payload file that contains user definitions, as described in User Definitions File.

If annotation is enabled for the Account 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

curl -H "x-api-key: $token" -F "[email protected]"
-X POST $endpoint/config/authorization/user

config authorization:user::get

The config authorization:user::get command enables you to get the details of an existing user (user name and associated roles), as defined in the user data file.

CLI Syntax

ctm config authorization:user::get <user>

where <user> defines the username.

REST API Syntax

userName=myUser
curl -H "x-api-key: $token" "$endpoint/config/authorization/user/$userName"

config authorization:user::update

The config authorization:user::update command enables you to update the definitions of an existing user based on user settings that you define through a user data file.

CLI Syntax

ctm config authorization:user::update <user> <userFile>

where <user> defines the username that you want to update, and <userFile> is the full path and name of a .json payload file that contains user definitions, as described in User Definitions File.

Note that you cannot update the username.

If annotation is enabled for the Account 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

userName=myuser
curl -H "x-api-key: $token" -F "[email protected]"
-X POST "$endpoint/config/authorization/user/$userName"

config authorization:user::delete

The config authorization:user::delete command enables you to delete an existing user and disassociates it from all roles with which it was associated.

CLI Syntax

ctm config authorization:user::delete <user>

where <user> defines the username.

If annotation is enabled for the Account 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

userName=myuser
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/authorization/user/$userName"

config authorization:users::get

The config authorization:users::get command enables you to get a list of names of configured users.

CLI Syntax

ctm config authorization:users::get [-s <search query>]

The optional -s switch can be used to filter for users by user name. The format for the query string is "name=userName".

Use * (asterisks) or ? (question marks) for wildcards. Use , (commas) to specify multiple usernames.

REST API Syntax

userName=emuser*
curl -H "x-api-key: $token" $endpoint/config/authorization/users?name=$userName

config authorization:user:effectiverights::get

The config authorization:user:effectiverights::get command enables you to get details regarding the authorizations and privileges that are in effect for the logged-in user. A user's effective rights are calculated based on the authorizations defined in the various roles that are associated with that user.

CLI Syntax

ctm config authorization:user:effectiverights::get

REST API Syntax

curl -H "x-api-key: $token"
"$endpoint/config/authorization/user/effectiverights"

User Definitions File

The following code sample shows the definitions of a Helix Control-M user in the payload JSON file:

{
   "Name": "[email protected]",
   "Roles": [
      "Admin",
      "TeamLeader"
   ]
}

The following table describes the User Definitions File objects or properties.

Organization Group and Organization User Configuration

The following API commands are available for the configuration of authorizations for organization groups and organization users:

• config authorization:organizationgroup:roles::get: Gets a list of roles associated with an organization group.

• config authorization:organizationgroups::get: Gets a list of all organization groups that are associated with any defined roles.

• config authorization:organizationuser:roles::get: Gets a list of roles associated with an organization user.

• config authorization:organizationusers::get: Gets a list of all organization users that are associated with any defined roles.

config authorization:organizationgroup:roles::get

The config authorization:organizationgroup:roles::get command enables you to get a list of roles that are associated with a specific organization group (such as an LDAP group or IdP group).

CLI Syntax

ctm config authorization:organizationgroup:roles::get <organizationGroup> [-s "role=<query pattern>"]

The following table describes the config authorization:organizationgroup:roles::get command parameters.

REST API Syntax

roleName=myRole
organizationGroup=myGroup
curl -H "x-api-key: $token" $endpoint/config/authorization/organizationgroup/$organizationGroup/roles?role=$roleName

config authorization:organizationgroups::get

The config authorization:organizationgroups::get command enables you to get a list of all organization groups (such as LDAP groups or IdP groups) that are associated with any of the defined roles.

CLI Syntax

ctm config authorization:organizationgroups::get

REST API Syntax

curl -H "x-api-key: $token" $endpoint/config/authorization/organizationgroups

config authorization:organizationuser:roles::get

The config authorization:organizationuser:roles::get command enables you to get a list of roles that are associated with a specific organization user (such as an LDAP user or IdP user).

CLI Syntax

ctm config authorization:organizationuser:roles::get <organizationUser> [-s "role=<query pattern>"]

The following table describes the config authorization:organizationuser:roles::get command parameters.

REST API Syntax

roleName=myRole
organizationUser=user5
curl -H "x-api-key: $token"
$endpoint/config/authorization/organizationgroup/$organizationUser/roles?role=$roleName

config authorization:organizationusers::get

The config authorization:organizationusers::get command enables you to get a list of all organization users (such as LDAP users or IdP users) that are associated with any of the defined roles.

CLI Syntax

ctm config authorization:organizationusers::get

REST API Syntax

curl -H "x-api-key: $token" $endpoint/config/authorization/organizationusers

config authorization:ldap:role::add (Deprecated)

The config authorization:ldap:role::add command enables you to add a role to an LDAP group (or SAML group), so that any user in the LDAP group will inherit the permissions and authorizations defined for the role.

CLI Syntax

ctm config authorization:ldap:role::add <ldapGroup> <role>

The following table describes the config authorization:ldap:role::add command parameters.

REST API Syntax

roleName=myRole
ldapGroup=myGroup
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"

config authorization:ldap:role::delete (Deprecated)

The config authorization:ldap:role::delete command enables you to delete a role from an LDAP group (or SAML group).

CLI Syntax

ctm config authorization:ldap:role::delete <ldapGroup> <role>

The following table describes the config authorization:ldap:role::delete command parameters.

REST API Syntax

roleName=myRole
ldapGroup=myGroup
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X DELETE "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"

config authorization:ldap:roles::get (Deprecated)

The config authorization:ldap:roles::get command enables you to get a list of roles that are associated with a specific LDAP group (or SAML group).

CLI Syntax

ctm config authorization:ldap:roles::get <ldapGroup> [-s "role=<query pattern>"]

The following table describes the config authorization:ldap:roles::get command parameters.

REST API Syntax

roleName=myRole
ldapGroup=myGroup
curl -H "x-api-key: $token" $endpoint/config/authorization/ldap/$ldapGroup/roles?role=$roleName