User data for authorization configuration
This page provides information for creating user data files, that is, payload JSON files that you can submit when you configure user authorizations.
The following code sample shows the available objects that you can include within such a file. The rest of this page provides details about each of these objects and their properties.
{
"Name": "emuser1",
"FullName": "John Doe",
"Description": "Control-M/EM user number 1",
"Authentication": {
"ExternalProvider": {
"LdapUserAndDomain": "user1@prod"
},
"ControlM": {
"Password": "keySecret",
"PasswordExpirationDays": 60,
"ChangePasswordAtNextLogin": true,
"LockAccount": true
}
},
"Roles": ["AdminGroup", "UpdateGroup"]
}
General user settings
The user file contains the following general properties for the user that you are defining:
Property | Description |
---|---|
Name | A unique name for the user account (required property) |
FullName | The full name of the user (optional) |
Description | An optional textual description of the user |
For example:
"Name": "emuser1",
"FullName": "John Doe",
"Description": "Control-M/EM user number 1",
Authentication definitions
The Authentication object defines the credentials and other logon settings for the user's connection with Control-M. You can define an external LDAP connection and/or a Control-M logon.
"Authentication": {
"ExternalProvider": {
"LdapUserAndDomain": "user1@prod"
},
"ControlM": {
"Password": "keySecret",
"PasswordExpirationDays": 60,
"ChangePasswordAtNextLogin": true,
"LockAccount": true
}
}
The following table describes the objects and properties under the Authentication object:
Object or Property | Description |
---|---|
ExternalProvider | An external connection: |
LdapUserAndDomain | The LDAP user and domain for the external connection |
ControlM | Internal Control-M logon details: |
Password | A password for the user, either plain text or a predefined secret Note that, for security reasons, the value for this property in the output from the config authorization:user::get command is set to KEEP_EXISTING. You can keep this value in the user data file that you submit when you update user authorizations. |
PasswordExpirationDays | (Optional) Number of days until the password expires The default is 0, that is, no expiration. |
ChangePasswordAtNextLogin | Use this setting to force the user to change his/her password at next login. Values: true | false Default: false |
LockAccount | Use this setting to temporarily lock a user account, disabling the user from performing actions in Control-M. Values: true | false Default: false |
Role associations
The Roles object enables you to assign roles (one or more) to the user.
For example:
"Roles": ["AdminGroup", "UpdateGroup"],
Authorization definitions
The Authorization object enables you to manage the user's authorizations to access various Control-M entities, objects, and actions. All next-level objects (under the Authorization object) can also be defined at the role level (as described in Role data for authorization configuration), to be inherited by all users associated with the role. Therefore, any entries that you include under the Authorization object are optional, and they serve the following purposes:
- To add authorizations to the individual user, beyond those inherited from the role.
- To override role-level authorizations — this is the case for entries under the Privileges object.
Note
BMC recommends managing authorizations at the role level, and not at the user level. Authorization management at the user level will be deprecated in version 9.0.21 of Control-M Automation API.
AllowedJobs
Grants the user browse access to the output of jobs that you specify using include/exclude filters.
"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 user is authorized to access. - The
Excluded
object lists filters for jobs that the user is NOT authorized to access.
In each of these lists, 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:
Job property | Operator | Value |
---|---|---|
The following properties are available:
| Choose one of the following:
| Specify a value appropriate for the property:
|
AllowedJobActions
Authorizes the user 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 user 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 three categories — Browse actions, Control actions, and Update actions.
Browse actions | Control actions | Update actions |
---|---|---|
|
|
|
Privileges
Grants the user access to various Control-M components, utilities, and tools, and authorizes the user to perform actions through these tools based on the defined access levels. By default, all privileges are inherited from the associated role, but you can set different privileges for an individual user to override the role-level privileges.
"Privileges": {
"ClientAccess": {
"WorkloadChangeManagerAccess": "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 Control-M 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 Default
, that is, inherited from the role.
Control-M feature (divided by category) | Description | Available authorizations | ||||
---|---|---|---|---|---|---|
Full | Update | Browse | None | Default | ||
ClientAccess | ||||||
SelfServiceAccess | Access Control-M Self Service | |||||
WorkloadChangeManagerAccess | Access Control-M Workload Change Manager | |||||
UtilitiesAccess | Access Control-M/Server utilities, Control-M/EM API, and the Control-M Batch Impact Manager Web UI | |||||
ApplicationIntegratorAccess | Access to Control-M Application Integrator | |||||
ConfigurationManager | ||||||
Authorization | Manage authorizations | |||||
ConfigurationManagerAccess | Access Control-M Configuration Manager | |||||
Configuration | Manage configurations | |||||
Operation | Manage operations | |||||
Database | Perform database maintenance | |||||
ControlmSecurity | Manage Control-M security | |||||
Monitoring | ||||||
Alert | Manage alerts | |||||
ViewpointArchive | Manage archived Viewpoints | |||||
Planning | ||||||
PeriodicalStatistics | Manage periodical statistics | |||||
ForecastOrBatchImpactManagerConfig | Configure Control-M/Forecast and Control-M Batch Impact Manager | |||||
PromotionRules | Manage promotion rules | |||||
PromoteAction | Manage promotion actions | |||||
Tools | ||||||
Cli | Access command line tools | |||||
BatchImpactManagerReport | Generate and view Control-M Batch Impact Manager reports | |||||
ForecastReport | Generate and view Control-M/Forecast reports | |||||
ViewpointManager | ||||||
Collections | Manage Viewpoint collections | |||||
Hierarchies | Manage Viewpoint hierarchies | |||||
Filters | Manage Viewpoint filters | |||||
Viewpoints | Manage Viewpoints |
Folders
Grants the user 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*",
"Order": true,
"Jobs": {
"Privilege": "Full",
"Application": "aaa*",
"SubApplication": "bbb*"
}
}]
The Folders object has the following 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 Note: This property is optional if you specify a value for Library and/or Folder (the next two properties). |
Library | Name of the library that contains the job folder Note: 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 Note: This property is optional if you specify a value for ControlmServer and/or Library (the previous two properties). |
Order | Whether the user is allowed to order the folder(s) and the jobs within it, either This setting is not dependent on the Privilege that you set for the user. |
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 Note: 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 Note: If this property is not defined, privileges are granted to jobs associated with all Sub-Applications within the specified Application(s) (previous property). |
Calendars
Associates specific calendars in Control-M with the user, along with an authorization level for each calendar.
"Calendars": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "bbb*"
}]
The Calendars object has the following 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 Note: 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 Note: 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 ?). For more information, see Pattern matching strings in the Control-M Online Help.
RunasUsers
Associates "run as" users with the user, for running jobs on a Control-M/Agent.
Note: For a user's RunasUser definitions to take effect on jobs in a folder, the same user must be granted sufficient folder privileges — either Full or Update privileges must be granted to the relevant folders.
"RunasUsers": [{
"ControlmServer": "aaa*",
"RunasUser": "aaa*",
"NodeIdOrGroup": "bbb*"
}]
The RunasUsers object has the following 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 a Control-M/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 commas (,) or wildcards (such as * or ?).
You might also want to specify values to be excluded. For example, to exclude user names root or Oracle, you can specify the following string:"RunasUser": "!(root|Oracle)"
For more information, see Pattern matching strings in the Control-M Online Help.
WorkloadPolicies
Associates specific Workload Policies in Control-M with the user, 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 WorkloadPolicies object has the following 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 in the Control-M Online Help. Note: 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 user, 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 SiteStandard object has the following 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 ?). See Pattern matching strings in the Control-M Online Help. |
SiteCustomization
Associates specific Site Customizations with the user, 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 SiteCustomization object has the following 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 ?). See Pattern matching strings in the Control-M Online Help. |
Services
Grants the user 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 Services object has the following 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 ?). See Pattern matching strings in the Control-M Online Help. This property is required. |
AllowedActions | Actions that the user is authorized to perform on the service(s) Specify each action as a next-level property, and set it to a Boolean value — either Note: If this property is not defined, all actions are set to a default of You can specify any of the following actions:
|
Events
Grants the user authorization to manage events, by associating specific events with the user and assigning an authorization level to each one.
"Events": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "*"
}]
The Events object has the following 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 Note: 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) Note: 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 ?). For more information, see Pattern matching strings in the Control-M Online Help.
Mutexes
Grants the user authorization to manage mutexes (also known as control resources), by associating specific mutexes with the user and assigning an authorization level to each one.
"Mutexes": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "*"
}]
The Mutexes object has the following properties:
Property | Description |
---|---|
Privilege | Level of authorization to assign for the specified mutex (or mutexes) — Full, Update, or Browse This property is required. |
ControlmServer | Name of (one or more) Control-M/Server that processes jobs Note: If this property is not defined, privileges are granted for the specified mutex (next property) on all Control-M/Servers in the environment. |
Name | Name of mutex or mutexes Note: If this property is not defined, privileges are granted for all mutexes 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 ?). For more information, see Pattern matching strings in the Control-M Online Help.
Semaphores
Grants the user authorization to manage semaphores (also known as quantitative resources), by associating specific semaphores with the user and assigning an authorization level to each one.
"Semaphores": [{
"Privilege": "Full",
"ControlmServer": "aaa*",
"Name": "*"
}]
The Semaphores object has the following properties:
Property | Description |
---|---|
Privilege | Level of authorization to assign for the specified semaphore (or semaphores) — Full, Update, or Browse This property is required. |
ControlmServer | Name of (one or more) Control-M/Server that processes jobs Note: If this property is not defined, privileges are granted for the specified semaphore (next property) on all Control-M/Servers in the environment. |
Name | Name of semaphore or semaphores Note: If this property is not defined, privileges are granted for all semaphores 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 ?). For more information, see Pattern matching strings in the Control-M Online Help.
GlobalEvents
Grant the user authorization to manage global events, by associating specific global events with the user and assigning an authorization level to each one.
"GlobalEvents": [{
"Privilege": "Full",
"Name": "*"
}]
The GlobalEvents object has the following properties. All parameters are required.
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 in the Control-M Online Help. |
Comments
Log in or register to comment.