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.
This feature requires Control-M/EM version 9.0.21 or higher.
You can configure authorizations with the following API commands:
The following videos demonstrate how to manage authorizations:
https://youtu.be/ooVUsgws570: Managing roles and authorizations.
https://youtu.be/gxZ9coj48M0: Creating users and assigning roles to users and LDAP groups.
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:role::rename: Rename 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
REST API Syntax
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -F "roleFile=@roleDefinition.json"
-X POST $endpoint/config/authorization/role
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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.
CLI Syntax
ctm config authorization:role::get <role>
where role is the name of the role.
REST API Syntax
cURL:
roleName=myRole
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader"
"$endpoint/config/authorization/role/$roleName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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.
Besides applying all settings that are explicitly defined in the role data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
Begin
-
Obtain ALL current role settings by running the config authorization:role::get command.
-
Use the output from the previous step to create your role data file, a .json file.
-
In the role data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all role settings, see Role Definitions File.
-
Proceed with running the Update command.
You cannot use this API command to change the name of an existing role. To rename an existing role, config authorization:role::rename.
CLI Syntax
ctm config authorization:role::update <role> <roleFile>
The following table describes the config authorization:role::update command parameters.
Parameter |
Description |
---|---|
role |
Name of the role that you want to update. |
roleFile |
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
REST API Syntax
cURL:
roleName=myRole
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -F "roleFile=@roleDefinition.json"
-X POST "$endpoint/config/authorization/role/$roleName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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
REST API Syntax
cURL:
roleName=myRole
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/config/authorization/role/$roleName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:role::rename
The config authorization:role::rename command enables you to rename an existing role.
CLI Syntax
ctm config authorization:role::rename <role> <newName>
The following table describes the config authorization:role::rename command parameters.
Parameter |
Description |
---|---|
role |
Current name of the role that you want to rename. |
newName |
New name for the role. |
If annotation is enabled for the Account 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:
roleName=myRole
newRoleName=myNewRole
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -d "{\"name\":\"$newRoleName\"}"
-X POST "$endpoint/config/authorization/role/$roleName/rename"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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:
Fields |
Criteria |
Examples |
---|---|---|
|
|
|
If you include multiple fields in the query, separate them with an &. |
REST API Syntax
cURL:
roleName=Adm*
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/config/authorization/roles?role=$roleName
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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
cURL:
roleName=myRole
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/config/authorization/role/$roleName/associates
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
Response
The following sample response shows 3 associations with a role: 1 organization user, 1 organization group (an LDAP group), and 1 Control-M user.
[
{
"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": [
[["FileName", "like", "a*"], ["JobType", "eq", "Job,Command"]],
[["FileName", "like", "b*"], ["JobType", "eq", "Job,Command"]]
],
"Excluded": [
[["FileName", "like", "c*"], ["JobType", "eq", "Job,Command"]],
[["FileName", "like", "d*"], ["JobType", "eq", "Job,Command"]]
]
},
"AllowedJobActions": {
"ViewProperties": true,
"SetToOk": true,
"Documentation": true,
"Confirm": true,
"Log": true
},
"Privileges": {
"ClientAccess": {
"ControlmWebClientAccess": "Full",
"ApplicationIntegratorAccess": "None"
},
"ConfigurationManager": {
"Authorization": "Browse",
"ControlmSecurity": "Update"
}
},
"Folders": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Library": "bbb*",
"Folder": "ccc*",
"Run": true,
"Jobs": {
"Privilege": "Full",
"Application": "aaa*",
"SubApplication": "bbb*"
}
}],
"Calendars": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "bbb*"
}],
"RunasUsers": [{
"ControlmServer": "aaa*",
"RunasUser": "aaa*",
"Host": "bbb*"
}],
"WorkloadPolicies": [{
"Privilege": "Full",
"Name": "*"
}],
"SiteStandard": [{
"Privilege": "Full",
"Name": "*"
}],
"SiteCustomization": [{
"Privilege": "Full",
"Name": "*"
}],
"Services": [{
"Privilege": "Full",
"Name": "*",
"AllowedActions":
{"DrillDown": true,
"Run": true,
"Hold": true,
"Resume": true,
"ViewOrderableService": true}
}],
"Events": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "*"
}],
"Locks": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "*"
}],
"Pools": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "*"
}],
"GlobalEvents": [{
"Privilege": "Full",
"Name": "*"
}],
"AgentManagement": [
{
"ControlmServer": "ctm3",
"Agent": "agent3",
"Privilege": "Browse"
},
{
"ControlmServer": "ctm4",
"Agent": "agent4",
"Privilege": "Update"
}
],
"PluginManagement": [
{
"ControlmServer": "ctm3",
"Agent": "agent3",
"PluginType": "SAP*",
"Privilege": "Browse"
},
{
"ControlmServer": "ctm4",
"Agent": "agent4",
"PluginType": "OEBS",
"Privilege": "Update"
}
],
"ConnectionProfileManagement": [
{
"ControlmServer": "ctm3",
"Agent": "agent3",
"PluginType": "SAP*",
"Name": "cpp3*",
"Privilege": "Browse"
},
{
"ControlmServer": "ctm4",
"Agent": "agent4",
"PluginType": "OEBS",
"Name": "cpp4*",
"Privilege": "Update"
}
],
"RunasDefinitionManagement": [
{
"ControlmServer": "br*",
"Privilege": "Browse"
},
{
"ControlmServer": "up*",
"Privilege": "Update"
}
]
}
General Role Settings
The following table describes the general role properties for the role that you are define.
Property |
Description |
---|---|
Name |
A unique name for the role (required property). |
Description |
An optional textual description of the role. |
OrganizationGroups |
A list of organization groups (such as LDAP groups or IdP groups) with which the role is associated. |
OrganizationUsers |
A list of organization users (such as LDAP users or IdP users) with which the role is associated. |
"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
"AllowedJobs": {
"Included": [
[["FileName", "like", "a*"], ["JobType", "eq", "Job,Command"]],
[["FileName", "like", "b*"], ["JobType", "eq", "job,command"}]
],
"Excluded": [
[["FileName", "like", "c*"], ["JobType", "eq", "Job,Command"]],
[["FileName", "like", "d*"], ["JobType", "eq", "Job,Command"}]
]
}
Under the AllowedJobs object, you define job authorizations:
-
The Included object lists filters for jobs that the role is authorized to access.
-
The Excluded object lists filters for jobs that the role is NOT authorized to access.
In
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.
Job Property |
Operator |
Value |
---|---|---|
The following properties are available:
|
Choose one of the following:
|
Specify a value appropriate for the property:
|
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 actions
Browse Actions |
Control Actions |
Update Actions |
---|---|---|
|
|
|
Privileges
Grants the role access to various Control-M components, utilities, and tools, and authorizes the role to perform actions through these tools based on the defined access levels.
"Privileges": {
"ClientAccess": {
"ControlmWebClientAccess": "Full",
"ApplicationIntegratorAccess": "None"
},
"ConfigurationManager": {
"Authorization": "Browse",
"ControlmSecurity": "Update"
}
}
Under the Privileges object, various Control-M features and capabilities are categorized and grouped together under the following next-level objects:
-
ClientAccess
-
ConfigurationManager
-
Monitoring
-
Planning
-
Tools
-
ViewpointManager
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.
Control-M Feature (Divided by Category) |
Description
|
Available Authorizations |
|||
---|---|---|---|---|---|
Full |
Update |
Browse |
None |
||
ClientAccess |
|||||
ControlmWebClientAccess |
Access Control-M Web Client |
Yes |
No |
No |
Yes |
SelfServiceAccess |
Access Control-M Self Service (Deprecated; replaced by ControlmWebClientAccess) |
Yes |
No |
No |
Yes |
WorkloadChangeManagerAccess |
Access Control-M Workload Change Manager (Deprecated; replaced by ControlmWebClientAccess) |
Yes |
No |
No |
Yes |
UtilitiesAccess |
Access Control-M/Server utilities, Control-M/EM API, and the Control-M Batch Impact Manager Web UI |
Yes |
No |
No |
Yes |
ApplicationIntegratorAccess |
Access Control-M Application Integrator |
Yes |
|
|
Yes |
AutomationAPIAccess |
Access Control-M Automation API |
Yes |
No |
No |
Yes |
ConfigurationManager |
|||||
Authorization |
Manage authorizations. |
Yes |
Yes |
Yes |
Yes |
ConfigurationManagerAccess |
Access Control-M Configuration Manager |
Yes |
No |
No |
Yes |
Configuration |
Manage configurations. |
Yes |
|
|
Yes |
Operation |
Manage operations. |
Yes |
Yes |
No |
Yes |
Database |
Perform database maintenance. |
Yes |
No |
Yes |
Yes |
ControlmSecurity |
Manage Control-M security. |
Yes |
|
|
Yes |
Monitoring |
|||||
Alert |
Manage alerts. |
Yes |
Yes |
Yes |
Yes |
ViewpointArchive |
Manage archived Viewpoints. |
Yes |
No |
No |
Yes |
Planning |
|||||
PeriodicalStatistics |
Manage periodical statistics. |
Yes |
No |
Yes |
Yes |
ForecastOrBatchImpactManagerConfig |
Configure Control-M/Forecast and Control-M Batch Impact Manager (SLA Management). |
Yes |
Yes |
Yes |
Yes |
PromotionRules |
Manage promotion rules. |
Yes |
No |
No |
Yes |
PromoteAction |
Manage promotion actions. |
Yes |
Yes |
No |
Yes |
Tools |
|||||
Cli |
Access command line tools. |
Yes |
No |
No |
Yes |
SlaManagementReports |
Generate
and view SLA Management reports |
Yes |
No |
No |
Yes |
Generate and view Control-M Reports. |
Yes |
No |
No |
Yes |
|
HistoryReports |
Generate and view History reports. (Deprecated; replaced by ControlMReports ) |
Yes |
Yes |
Yes |
Yes |
ViewpointManager |
|||||
Collections |
Manage Viewpoint collections. |
Yes |
Yes |
Yes |
Yes |
Hierarchies |
Manage Viewpoint hierarchies. |
Yes |
Yes |
Yes |
Yes |
Filters |
Manage Viewpoint filters. |
Yes |
Yes |
Yes |
Yes |
Viewpoints |
Manage Viewpoints. |
Yes |
Yes |
Yes |
Yes |
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": "aaa*",
"Library": "bbb*",
"Folder": "ccc*",
"Run": true,
"Jobs": {
"Privilege": "Full",
"Application": "aaa*",
"SubApplication": "bbb*"
}
}]
The following table describes the Folders object properties.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified folder (or folders) — Full, Update, or Browse. This property is required. |
ControlmServer |
Name of (one or more) Control-M/Server that processes jobs. This property is optional if you specify a value
for |
Library |
Name of the library that contains the job folder. This property is optional if you specify a value for ControlmServer and/or Folder (the previous and next properties). |
Folder |
Name of folder or folders. This property is optional if you specify a value
for ControlmServer |
Run |
Whether users associated with the role can run specific folders — true or false. This option is independent of the access levels that you set through Privileges. You can enable associated users to run folders on all access levels. This option also determines whether associated users can use the Run option in the Monitoring domain in Control-M. |
Jobs |
Level of authorization to assign to specific jobs within a folder based on the jobs' Application or SubApplication criteria. To specify authorizations on the job level, you must have Control-M Workload Change Manager installed. |
Privilege |
Level of authorization to assign to the specified job(s) in the folder— Full, Update, or Browse. This property is required when you specify authorizations on the job level. |
Application |
Name of an Application (logical grouping of jobs) that the job is associated with. If this property is not defined, privileges are granted to jobs associated with the specified Sub-Application(s) (next property) within all Applications. |
SubApplication |
Name of a Sub-application (logical sub-grouping of jobs within an Application) that the job is associated with. If this property is not defined, privileges are granted to jobs associated with all Sub-Applications within the specified Application(s) (previous property). |
For properties that support multiple values (ControlmServer,
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.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified calendar (or calendars) —Full, Update, or Browse. This property is required. |
ControlmServer |
Name of (one or more) Control-M/Server that processes jobs. If this property is not defined, privileges are granted for the specified calendar (next property) on all Control-M/Servers in the environment. |
Name |
Name of calendar or calendars. If this property is not defined, privileges are granted for all calendars on the specified Control-M/Server (previous property). |
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.
For a role's RunasUser definitions to take effect on jobs in a folder, the same role must be granted sufficient folder privileges — either Full or Update privileges must be granted to the relevant Folders.
"RunasUsers": [{
"ControlmServer": "*",
"RunasUser": "aaa*",
"Host": "bbb*"
}]
The following table describes the RunasUsers object properties.
Property |
Description |
---|---|
ControlmServer |
Name of (one or more) Control-M/Server that processes jobs. |
RunasUser |
Name of "run as" user(s) to be granted authorization to execute jobs. |
Host |
Name of an Agent computer, remote host computer, or host group where jobs are submitted. |
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.
To exclude user names root or Oracle, type the following:
"RunasUser": "!(root|Oracle)"
For more information, see Pattern matching strings.
WorkloadPolicies
Associates specific Workload Policies in Control-M with the role, along with an authorization level for each Workload Policy.
Workload policies are groups of jobs that you define for the purpose of balancing the workload and limiting resources used by jobs.
"WorkloadPolicies": [{
"Privilege": "Full",
"Name": "*"
}]
The following table describes the WorkloadPolicies object properties. All parameters are required.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified Workload Policy or Policies — Full, Update, or Browse. |
Name |
Name of Workload Policy (or Workload Policies). For multiple values, you can use commas (,) or wildcards (such as * or ?). See Pattern matching strings. If the Privilege property is set to Full, the Name property must be set to "*" (all Workload Policies). |
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.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified site standard(s) — Full, Update, or Browse. |
Name |
Name of site standard(s). For multiple values, you can use commas (,) or wildcards (such as * or ?).
|
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.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified site customization(s) — Full, Update, or Browse. |
Name |
Name of site customization(s). For multiple values, you can use commas (,) or wildcards (such as * or ?).
|
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,
"Run": true,
"Hold": true,
"Resume": true,
"ViewOrderableService": true
}
}]
The following table describes the Services object properties.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified service(s) — Full, Update, Browse, or None. This property is required. |
Name |
Name of service(s). For multiple values, you can use commas (,) or wildcards (such as * or ?).
This property is required. |
AllowedActions |
Actions that the role is authorized to perform on the service(s). Specify each action as a next-level property, and set it to a Boolean value — either true or false. If this property is not defined, all actions are set to a default of false. You can specify any of the following actions:
|
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.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified event(s) — Full, Update, or Browse. This property is required. |
ControlmServer |
Name of (one or more) Control-M/Server that processes jobs. If this property is not defined, privileges are granted for the specified event (next property) on all Control-M/Servers in the environment. |
Name |
Name of event(s). If this property is not defined, privileges are granted for all events on the specified Control-M/Server (previous property). |
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.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified lock (or locks) — Full, Update, or Browse. This property is required. |
ControlmServer |
Name of (one or more) Control-M/Server that processes jobs. If this property is not defined, privileges are granted for the specified lock (next property) on all Control-M/Servers in the environment. |
Name |
Name of lock or locks. If this property is not defined, privileges are granted for all locks on the specified Control-M/Server(previous property). |
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.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified pool (or pools — Full, Update, or Browse. This property is required. |
ControlmServer |
Name of (one or more) Control-M/Server that processes jobs. If this property is not defined, privileges are granted for the specified pool (next property) on all Control-M/Servers in the environment. |
Name |
Name of pool or pools. If this property is not defined, privileges are granted for all pools on the specified Control-M/Server (previous property). |
For properties that support multiple values (ControlmServer and Name), you can use commas (,) or wildcards (such as * or ?).
GlobalEvents
Grant the role authorization to manage global events, by associating specific global events with the role and assigning an authorization level to each one.
"GlobalEvents": [{
"Privilege": "Full",
"Name": "*"
}]
The following table describes the mandatory GlobalEvents object properties.
Property |
Description |
---|---|
Privilege |
Level of authorization to assign for the specified global event(s) — Full, Update, or Browse. |
Name |
Name of global event(s). For multiple values, you can use commas (,) or wildcards (such as * or ?). See Pattern matching strings. |
AgentManagement
Grants the role authorization to manage agents and perform administrative tasks on agents (such as connect an Agent to a Control-M/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": "ctm3",
"Agent": "agent3",
"Privilege": "Browse"
},
{
"ControlmServer": "ctm4",
"Agent": "agent4",
"Privilege": "Update"
}
]
The following table describes the AgentManagement object properties for each specified Agent.
Property |
Description |
---|---|
ControlmServer |
Name of a Control-M/Server that is associated with the Agent. |
Agent |
The tag associated with the Agent to which this role is granted access. |
Privilege |
Level of authorization to assign for the specified Agent — Full, Update, or Browse. |
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": "ctm3",
"Agent": "agent3",
"PluginType": "SAP*",
"Privilege": "Browse"
},
{
"ControlmServer": "ctm4",
"Agent": "agent4",
"PluginType": "OEBS",
"Privilege": "Update"
}
]
The following table describes the PluginManagement object properties for, each specified plug-in.
Property |
Description |
||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ControlmServer |
Name of a Control-M/Server that is associated with an Agent. |
||||||||||||||||||||||||||||||||||||||||||||||
Agent |
The tag associated with the Agent to which this role is granted access. |
||||||||||||||||||||||||||||||||||||||||||||||
PluginType |
The type of Control-M plug-inthat you have installed in your Control-M environment and to which this role is granted access:
For more information, see the list in |
||||||||||||||||||||||||||||||||||||||||||||||
Privilege |
Level of authorization to assign for the specified plug-in—Full, Update, or Browse. |
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": "ctm3",
"Agent": "agent3",
"PluginType": "SAP*",
"Name": "cpp3*",
"Privilege": "Browse"
},
{
"ControlmServer": "ctm4",
"Agent": "agent4",
"PluginType": "OEBS",
"Name": "cpp4*",
"Privilege": "Update"
}
]
The following table describes the ConnectionProfileManagement object properties for each specified connection profile.
Property |
Description |
---|---|
ControlmServer |
Name of a Control-M/Server that is associated with an Agent. For a centralized connection profile, specify a value of "*" (all Control-M/Servers). |
Agent |
The tag associated with the Agent to which this role is granted access. For a centralized connection profile, specify a value of "*" (all agents). |
PluginType |
The type of Control-M plug-in that you have installed in your Control-M environment and to which this role is granted access. For a list of values, see the corresponding property under PluginManagement. For more information, see the list in |
Name |
Name or name pattern of the connection profile. |
Privilege |
Level of authorization to assign for the specified connection profile — Full, Update, or Browse. |
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": "br*",
"Privilege": "Browse"
},
{
"ControlmServer": "up*",
"Privilege": "Update"
}
]
The following table describes the RunasDefinitionManagement object properties for each authorization.
Property |
Description |
---|---|
ControlmServer |
Name of a Control-M/Server. To specify a pattern, use an asterisk wildcard or any other supported character. |
Privilege |
Level of authorization to assign for configuration of "run as" users on this Control-M/Server — Full, Update, or Browse. |
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:user::simulate: Simulates the set of user authorizations.
-
config authorization:users::get: Get a list of users.
-
config authorization:user:role::add: Assigns a role to a user.
-
config authorization:user:role::delete: Removes a role from a user.
-
config user:password::adminUpdate: Changes a user password.
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
REST API Syntax
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -F "userFile=@userDefinition.json"
-X POST $endpoint/config/authorization/user
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:user::get
The config authorization:user::get command enables you to get the details of an existing user, as defined in the user data file.
-
Only parameters that are set to non-default values are retrieved and displayed in the output.
-
For security reasons, the user's password is returned as KEEP_EXISTING. When you use the output from this command to prepare a user data file (a .json file) for the config authorization:user::update command, you can keep this value in the user data file.
CLI Syntax
ctm config authorization:user::get <user>
where <user> defines the username.
REST API Syntax
cURL:
userName=myUser
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/config/authorization/user/$userName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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
REST API Syntax
cURL:
userName=myuser
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -F "userFile=@userDefinition.json"
-X POST "$endpoint/config/authorization/user/$userName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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
REST API Syntax
cURL:
userName=myuser
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/config/authorization/user/$userName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:user::simulate
The config authorization:user::simulate command enables you to simulate the final combination of authorizations for the user, based on a logical analysis of all authorizations inherited from the roles with which the user is associated.
The response begins with basic information about the user and a list of roles with which it is associated, and then continues with a list of the user's current authorizations, similar to the payload JSON file described in Role Definitions File.
CLI Syntax
ctm config authorization:user::simulate <user>
where <user> defines the username.
If annotation is enabled for the Account 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:
userName=myuser
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/config/authorization/user/$userName/simulate"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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, full name of user, or description (or any combination of these fields).
The query string format is "field1=criteria1&field2=criteria2".
The following table describes the guidelines for the fields and criteria in the query string.
Fields |
Criteria |
Examples |
---|---|---|
|
|
|
If you include multiple fields in the query, separate them with an & (ampersand). |
REST API Syntax
cURL:
userName=emuser*
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/config/authorization/users?name=$userName
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:user:role::add
The config authorization:user:role::add command enables you to assign a role to a user.
CLI Syntax
ctm config authorization:user:role::add <user> <role>
The following table describes the config authorization:user:role::add command parameters.
Parameter |
Description |
---|---|
user |
Name of user. |
role |
Name of role. |
REST API Syntax
cURL:
userName=myuser
roleName=myRole
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/config/authorization/user/$userName/role/$roleName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:user:role::delete
The config authorization:user:role::delete command enables you to remove a role from a user.
CLI Syntax
ctm config authorization:user:role::delete <user> <role>
The following table describes the config authorization:user:role::delete command parameters.
Parameter |
Description |
---|---|
user |
Name of user. |
role |
Name of role. |
REST API Syntax
cURL:
userName=myuser
roleName=myRole
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X DELETE "$endpoint/config/authorization/user/$userName/role/$roleName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config user:password::adminUpdate
The config user:password::adminUpdate command enables you to change the password for a user.
CLI Syntax
ctm config user:password::adminUpdate <user> [newPassword] [-p]
The following table describes the config user:password::adminUpdate command parameters.
Parameter |
Description |
---|---|
user |
Name of user whose password you want to change. |
newPassword |
(Optional) A new password for the user, either of the following:
|
The newPassword parameter is optional because you can, alternatively, use the -p (or -prompt) option through the CLI. With this option, you do not need to enter the password in the command. Instead, you are prompted for the password (twice) after you enter the command. Note that if you use both the newPassword parameter and the -p option, the password that you enter through the command prompt overrides the password that you specify in the command.
REST API Syntax
When using a REST API command, you must provide the password (or secret) in a payload .json file.
-
In the following cURL example, note that the path to the payload file is prefixed with an @ character:
CopyuserName=myuser
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-d "@c:\tmp\data.json" -X POST "$endpoint/config/user/$userName/password/adminUpdate"To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
-
Here is an example of the contents of a payload .json file, with the password specified as a predefined secret:
Copy{
"newPassword":"Secret:secretKey"
}
User Definitions File
The following code samples show the available objects and properties that you can include within a payload JSON file that contains user definitions.
The following example shows the definitions of a Control-M user:
{
"Name": "jdoe_1",
"Description": "John Doe's user specifications",
"FullName": "John Doe",
"Authentication": {
"ControlM": {
"Password": "string",
"PasswordExpirationDays": 0,
"ChangePasswordAtNextLogin": true,
"LockAccount": true,
"AccountLockedOnDate": "04/19/2023 11:42:35 AM"
}
},
"Roles": [
"Admin",
"TeamLeader"
]
}
The following example shows the definitions of an external user:
{
"Name": "jdoe_2",
"Description": "John Doe's user specifications",
"FullName": "John Doe",
"Authentication": {
"ExternalProvider": {
"LdapUserAndDomain": "CN[OU]@DC"
}
},
"Roles": [
"Admin",
"TeamLeader"
]
}
The following table describes the User Definitions File objects or properties.
Object or Property |
Description |
---|---|
Name |
Defines the username of the authorized user. |
Description |
Provides a description of the authorized user. |
FullName |
Defines the full name of the authorized user. |
Authentication |
Defines one of the following authentication methods for the authorized user:
|
Control-M |
Defines the authentication settings for a Control-M user authenticated via a password. |
Password |
Defines the password of the Control-M user. |
PasswordExpirationDays |
Determines the number of days that the password is valid until it expires. For a password that never expires, use a value of 0. Default: 0 (never expires) |
ChangePasswordAtNextLogin |
(Optional) Determines whether the user must change the password at the next login. Values: true | false Default: false |
LockAccount |
(Optional) Determines whether to prevent this user from logging into Control-M from a certain date and time. Values: true | false Default: false |
AccountLockedOnDate |
Defines the date and time to lock the account and prevent this user from logging into Control-M. Format: MM/dd/yyyy h:mm:ss aa |
ExternalProvider |
Defines a user authenticated through an external LDAP provider. |
LdapUserAndDomain |
Defines the LDAP user and domain for the LDAP server that authenticates the Control-M user. Format: CN[OU]@DC, where
|
Roles |
Lists the roles associated with the authorized user. |
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::simulate: Simulate authorizations for an organization user in organization groups.
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.
Parameter |
Description |
---|---|
organizationGroup |
Name of organizational group, such as an LDAP group or IdP group. |
query pattern |
(Optional) A pattern for filtering role names. The pattern contains a wildcard (* or ?). For multiple patterns in the same query, use , (commas). |
REST API Syntax
cURL:
roleName=myRole
organizationGroup=myGroup
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/config/authorization/organizationgroup/$organizationGroup/roles?role=$roleName
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/config/authorization/organizationgroups
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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.
Parameter |
Description |
---|---|
organizationUser |
Name of organizational user, such as an LDAP user or IdP user. |
query pattern |
(Optional) A pattern for filtering role names. The pattern contains a wildcard (* or ?). For multiple patterns in the same query, use , (commas). |
REST API Syntax
cURL:
roleName=myRole
organizationUser=user5
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader"
$endpoint/config/authorization/organizationgroup/$organizationUser/roles?role=$roleName
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/config/authorization/organizationusers
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:organizationgroup::simulate
The config authorization:organizationgroup::simulate command enables you to simulate the final combination of authorizations for the organization user in the organization groups, based on a logical analysis of all authorizations inherited from the roles with which the organization user and organization groups are associated.
The response begins with basic information about the user and a list of roles with which it is associated, and then continues with a list of the user's current authorizations, similar to the payload JSON file described in Role Definitions File. Additional details regarding the organization user and groups are provided at the end of the response.
CLI Syntax
ctm config authorization:organizationgroup::simulate <user>
where <user> defines the username.
If annotation is enabled for the Account 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:
orgUserName=myuser
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/config/authorization/organizationgroup/$orgUserName/simulate"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:ldap:role::add (Deprecated)
The config authorization:ldap:role::add command enables you to add a role to an LDAP group, so that any user in the LDAP group will inherit the permissions and authorizations defined for the role.
Deprecated as of version 9.0.21. Replaced by use of the OrganizationGroups property in the role data file, as described in Role Definitions File.
CLI Syntax
ctm config authorization:ldap:role::add <ldapGroup> <role>
The following table describes the config authorization:ldap:role::add command parameters.
Parameter |
Description |
---|---|
ldapGroup |
Name of LDAP group. |
role |
Name of role. |
REST API Syntax
cURL:
roleName=myRole
ldapGroup=myGroup
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
config authorization:ldap:role::delete (Deprecated)
The config authorization:ldap:role::delete command enables you to delete a role from an LDAP group.
Deprecated as of version 9.0.21. Replaced by use of the OrganizationGroups property in the role data file, as described in Role Definitions File.
CLI Syntax
ctm config authorization:ldap:role::delete <ldapGroup> <role>
The following table describes the config authorization:ldap:role::delete command parameters.
Parameter |
Description |
---|---|
ldapGroup |
Name of LDAP group. |
role |
Name of role. |
REST API Syntax
cURL:
roleName=myRole
ldapGroup=myGroup
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X DELETE "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.
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.
Deprecated as of version 9.0.21. Replaced by Authorization Configuration.
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.
Parameter |
Description |
---|---|
ldapGroup |
Name of LDAP group. |
query pattern |
(Optional) A pattern for filtering role names. The pattern contains a wildcard (* or ?). For multiple patterns in the same query, use , (commas). |
REST API Syntax
cURL:
roleName=myRole
ldapGroup=myGroup
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/config/authorization/ldap/$ldapGroup/roles?role=$roleName
To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.