Tutorial - Defining authorizations for Control-M roles and users

This tutorial guides you through the process of defining new roles and users for Control-M and controlling the authorizations that they have for Control-M resources. In this example, we will create a role that groups together Hadoop developers and we will assign users to this role.

Before you begin

Ensure that you have set up your environment, as described in Setting up the prerequisites.

Step 1 - Access the tutorial samples

Go to the directory where the tutorial sample is located:

cd automation-api-quickstart/control-m/102-on-boarding-new-application-group

Step 2 - Add a role for Hadoop developers

Let's take the role data file, hadoopRole.json, and use it to define a new role for Hadoop developers. The role data file specifies the authorizations that are granted to the role.

ctm config authorization:role::add hadoopRole.json

Step 3 - Add a Hadoop developer as a Control-M user

We will now use the user data file, hadoopUser.json, to define a new Control-M user and associate this user with the role that we defined in the previous step.

ctm config authorization:user::add hadoopUser.json

Step 4 - Examine the source code

Let's look at the source code in the JSON data files. By examining the contents of these files, you will learn about roles and users, how they are structured, and how to define them.

Role data file

We'll start with the role. The role data file defines a role and specifies collections of privileges and permissions for Control-M resources to grant to the role. For more information, see Role data for authorization configuration.

The sample role data file, hadoopRole.json, contains the following main objects:

The AllowedJobs and AllowedJobActions objects define the actions that can be performed on a specific set of jobs.

  "AllowedJobs": {
    "Included": [
      [
        [
          "Application",
          "like",
          "hadoop*"
        ],
        [
          "Host",
          "like",
          "hadoop*"
        ],
        [
          "JobName",
          "like",
          "hadoop*"
        ],
        [
          "Folder",
          "like",
          "hadoop*"
        ]
      ]
    ]
  },
  "AllowedJobActions": {
    "ViewProperties": true,
    "Documentation": true,
    "Log": true,
    "Statistics": true,
    "ViewOutputList": true,
    "ViewJcl": true,
    "Why": true,
    "Rerun": true,
    "SetToOk": true,
    "EditProperties": true
  },

The Privileges object defines access levels to various operations in Control-M.

  "Privileges": {
    "ClientAccess": {
      "SelfServiceAccess": "Full",
      "WorkloadChangeManagerAccess": "Full",
      "UtilitiesAccess": "Full",
      "ApplicationIntegratorAccess": "Full"
    },
    "Monitoring": {
      "Alert": "Full"
    },
    "Tools": {
      "Cli": "Full"
    }
  },

Several additional objects (Folders, Calendars, SiteStandard) define access to various Control-M resources.

  "Folders": [
    {
      "Privilege": "Full",
      "Folder": "hadoop*"
    }
  ],
  "Calendars": [
    {
      "Privilege": "Browse",
      "Name": "hadoop*"
    }
  ],
  "SiteStandard": [
    {
      "Privilege": "Browse",
      "Name": "hadoop_*"
    }
  ]

User data file

Now let's examine the user data file. The user data file associates a user with a role, and can be used to override specific privileges and permissions that are normally inherited from the role. For more information, see User data for authorization configuration.

The sample user data file, hadoopUser.json, contains only basic user definitions, and does not contain any overrides of role-level definitions.

{    
    "Name": "John",    
    "FullName": "John Doe",    
    "Description": "John Doe, developer for hadoop ",    
    "Authentication": {
        "ControlM": {      
            "Password": "John123",      
            "PasswordExpirationDays": 60                    
        }    
    },
    "Roles": ["hadoop_developers"]
}

This data file contains the following main objects:

The Authentication object defines the credentials and other logon settings for the user's connection with Control-M.
The Roles object associates the user with one or more role.

Step 5 - Modify the role

At any time, you can modify and update role definitions or user definitions by running an update command and submitting a new data file. In the following example we will modify role definitions.

First, obtain the current role definitions. You can obtain the current role definitions either from your source control, or by running a get command such as the following:

ctm config authorization:role::get hadoop_developers > c:\tmp\hadoop_developers.json

The current role definitions are saved to the hadoop_developers.json file.

You can now apply your changes to this file. Let's raise the role's level of privileges for its associated site standards:

Before:

  "SiteStandard": [
    {
      "Privilege": "Browse",
      "Name": "hadoop_*"
    }
  ]

After:

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

After saving our changes, we can now deploy the modified data file by running the update command:

ctm config authorization:role::update hadoop_developers c:\tmp\hadoop_developers.json

Step 6 - Assign the role to an LDAP group

If you have an LDAP group defined for your Hadoop developers, you can assign your new role for Hadoop developers to the LDAP group.

Use the following add command:

ctm config authorization:ldap:role::add hadoop_dev_group hadoop_developers

Step 7 - Change the user password

As an administrator who controls roles and users, you can set a new password for any user. Use a command such as the following:

ctm config user:password::adminUpdate John newPass

To provide the new password in a more secure manner, you can, alternatively, specify the password as a predefined secret or use the -p option to be prompted for the password after you enter the command.

Note: Developer-level users can update their own passwords using a different command, the session user:password::update command.

Where to go from here

To learn more about what you can do with the Control-M Automation API, read through the Code Reference and Automation API Services.
To start using the Control-M Automation API to define and run jobs, proceed to the next tutorial, Creating your first job flow.