User permissions and user roles

The role in role-based access control (RBAC) refers to a system of user roles, which are assigned to user groups and the users in those groups. Those roles contain permissions, which define what a user with that role can or can't do within Puppet Enterprise (PE).

When users are added to PE, they don't have permission to do anything until they are associated with a user role, either by direct role assignment or by inheriting roles from group membership. When a user is assigned to a role (or inherits a role from a group), they receive all the permissions from that role. If a user is associated with multiple roles, the user is able to perform all actions described by all permissions received from all of their assigned roles.

There are five default user roles:
Administrators
Can manage users and permissions, create and modify node groups and other objects.
Administrators have all permissions assigned to them by default.
Operators
Can create and modify node groups and other objects.
Viewers
Can view, but can't modify, objects in the console.
Code Deployers
Can synchronize code from version control systems to Puppet Server.
Project Deployers
Can deploy projects and run project tasks and plans.

You can also create custom roles. For example, you might want to create a user role that grants users permission to view but not edit a specific subset of node groups. Or you might want to divide up administrative privileges so that one user role is able to reset passwords while another can edit roles and create users.

Structure of user permissions

User permissions are structured as a triple of type, permission, and object.

  • Types: Any thing that can be acted on in Puppet Enterprise (PE), such as node groups, users, or user roles.
  • Permissions: What you can do with each type, such as create, edit, or view.
  • Objects: Specific instances of types.
For example, here are two sets of permission triples for the Administrators user role:
Type Permission Object Description
Node groups View PE Master Gives permission to view the PE Master node group.
User roles Edit All Gives permission to edit all user roles.

When no object is specified, then the permission applies to all objects of the specified type. In those cases, the object is All. This is denoted by "*" in the RBAC API.

In both the console and the API, "*" is used to express a permission for which an object doesn’t make sense, such as when creating users.

Reference: User permissions and names

This reference describes the permissions granted to the five default Puppet Enterprise (PE) user roles, as well as the display name and system name for each type and permission.

Permissions vary by type. Permission scope can, sometimes, be refined by an object specification. For an explanation of these terms, refer to Structure of user permissions.

Each type and permission has a display name, which is the name you see in the PE console, and a system name, which is the name used in the RBAC API. The Permissions for default roles table uses display names. Refer to the Display names and system names table to find the corresponding system name for each display name.

Permissions for default roles

This table lists permissions granted to the default PE user roles, a description of what is allowed by each permission, any object specification or node group inheritance conditions, and which roles (if any) the permissions are assigned to by default.

Type Permission Definition Roles
Certificate request Accept and reject Accept and reject certificate signing requests.

Object must always be "*".
  • Administrators
  • Operators
Configuration View and edit View and edit configuration, such as the disclaimer message on the PE console login page. Administrators
Console View View the PE console.

Object must always be "*".
  • Administrators
  • Operators
  • Viewers
Directory service View, edit, and test View, edit, and test directory service settings.

Object must always be "*".

 Administrators
Job orchestrator Start, stop and view jobs Start and stop jobs and tasks, view jobs and job progress, view an inventory of nodes that are connected to the PCP broker.
  • Operators
  • Viewers
  • Project Deployers
Node groups Create, edit, and delete child groups Create new child groups, delete existing child groups, and modify every attribute of child groups except environment.

This permission is inherited by all descendents of the node group.
  • Administrators
  • Operators
Node groups Edit child group rules Edit the rules of descendents of a node group.

This does not grant the ability to edit the rules of the group in the object field, only children of that group.

This permission is inherited by all descendents of the node group.
  • Administrator
  • Operators
Node groups Edit classes, parameters, and variables Edit every attribute of a node group except its environment and rule.

This permission is inherited by all descendents of the node group.
  • Administrators
  • Operators
Node groups Edit configuration data Edit parameterized configuration data on a node group.

This permission is inherited by all descendents of the node group.
  • Administrators
  • Operators
Node groups Edit parameters and variables Edit the class parameters and variables of a node group's classes.

This permission is inherited by all descendents of the node group.
  • Administrators
  • Operators
Node groups Set environment Set the environment of a node group.

This permission is inherited by all descendents of the node group.
  • Administrators
  • Operators
Node groups View See all attributes of a node group, including the values of class parameters and variables.

This permission is inherited by all descendents of the node group.
  • Administrators
  • Operators
  • Viewers
Nodes Edit node data from PuppetDB Edit node data imported from PuppetDB.

Object must always be "*".

 Administrators
Nodes View node data from PuppetDB View node data imported from PuppetDB.

Object must always be "*".

 Administrators
Nodes View sensitive connection information in inventory service View sensitive parameters stored in the inventory service for a connection, such as user credentials.

Object must always be "*".

 Administrators
Nodes Add and delete connection information from inventory service Add new connections to the inventory service and delete existing connections. Administrators
Plans Run plans Run specific plans on all nodes. Administrators
Projects Deploy projects Not used.
  • Administrators
  • Project Deployers
Projects Run tasks and plans from projects Not used.
  • Administrators
  • Project Deployers
Puppet agent Run Puppet on agent nodes Trigger a Puppet run from the console or orchestrator.

Object must always be "*".
  • Administrators
  • Operators
Puppet environment Deploy code Deploy code to a specific PE environment.
  • Administrators
  • Operators
  • Code Deployers
Puppet Server Compile catalogs for remote nodes Compile a catalog for any node managed by this PE instance.

This permission is required to run impact analysis tasks in Continuous Delivery for Puppet Enterprise.

 Administrators
Scheduled jobs Delete another user's scheduled jobs Delete scheduled jobs created by the user instance specified in the permission.

This can be granted per user.

 Administrators
Tasks Run tasks Run specific tasks on all nodes, nodes in a selected node group, or nodes matching a PQL query.
Important: A task must be permitted to run on all nodes in order to run on nodes that are outside of the PuppetDB (over SSH or WinRM for example). As a result, users with such permissions can run tasks on any nodes they have the credentials to access.
 Administrators
User groups Delete Delete a user group.

This can be granted per group.

 Administrators
User groups Import Import groups from the directory service for use in RBAC.

Object must always be "*".

 Administrators
User roles Create Create new roles.

Object must always be "*".

 Administrators
User roles Edit Edit and delete a role.

Object must always be "*".

 Administrators
User roles Edit members Change which users and groups a role is assigned to.

This can be granted per role.

 Administrators
Users Create Create new local users.

Object must always be "*".

Tip: This permission is for local users. Remote users are "created" when that user authenticates for the first time with RBAC.
 Administrators
Users Edit Edit local user data (such as names or email addresses) and delete local or remote users from PE.

This can be granted per user.

 Administrators
Users Reset password Grant password reset tokens to users who have forgotten their passwords.

Granting a password reset token also reinstates a user who has been revoked.

This can be granted per user.

 Administrators
Users Revoke Revoke or disable a user, so the user can no longer authenticate and use the console, node classifier, or RBAC API.

This permission also includes the ability to revoke a user's authentication tokens.

This can be granted per user.

 Administrators

Display names and system names

Each type and permission has a display name and a system name. The display name is the name you see in the PE console. The system name is the name used with the RBAC API. This table provides the display name and system name for each type and corresponding permissions. Types are listed multiple times if there are multiple permissions associated with that type.

Type display name Type system name Permission display name Permission system name
Certificate requests cert_requests Accept and reject accept_reject
Configuration configuration View view
Configuration configuration Edit edit
Console console_page View view
Directory service directory_service View, edit, and test edit
Job orchestrator orchestrator Start, stop and view jobs view
Node groups node_groups Create, edit, and delete child groups modify_children
Node groups node_groups Edit child group rules edit_child_rules
Node groups node_groups Edit classes, parameters, and variables edit_classification
Node groups node_groups Edit configuration data edit_config_data
Node groups node_groups Edit parameters and variables edit_params_and_vars
Node groups node_groups Set environment set_environment
Node groups node_groups View view
Nodes nodes Edit node data from PuppetDB edit_data
Nodes nodes View node data from PuppetDB view_data
Nodes nodes View sensitive connection information in inventory service view_inventory_sensitive
Plans plans Run Plans run
Puppet agent puppet_agent Run Puppet on agent nodes run
Puppet environment environment Deploy code deploy_code
Puppet Server puppetserver Compile catalogs for remote nodes compile_catalogs
Tasks tasks Run Tasks run
User groups user_groups Import import
User roles user_roles Create create
User roles user_roles Edit edit
User roles user_roles Edit members edit_members
Users users Create create
Users users Edit edit
Users users Reset password reset_password
Users users Revoke disable

Working with node group permissions

Node groups in the node classifier are structured hierarchically; therefore, node group permissions are inherited. Users with specific permissions on a node group implicitly receive those permissions on any child groups below that node group in the hierarchy.

Two types of permissions affect a node group: those that affect a group itself, and those that affect the group's child groups. For example, giving a user the Set environment permission on a node group allows the user to set the environment for that node group and all of the node group's children. However, assigning Edit child group rules to a node group allows a user to edit the rules for any child group of a specified node group, but not for the node group itself. This allows some users to edit aspects of a parent node group, while other users can be given permissions to modify the group's children without being able to affect the parent group.

Due to the hierarchical nature of node groups, if a user is given a permission on the default node group (All nodes), this is functionally equivalent to giving them that permission on all objects of the node group type ("*").

Best practices for assigning permissions

Working with user permissions requires delicacy. You don't want to unintentionally escalate users' roles by granting them excessive permissions, but you also don't want to hamper them in their day-to-day duties. The following sections describe some strategies and requirements for setting permissions in Puppet Enterprise (PE).

Grant edit permissions to users with create permissions

Creating objects doesn't automatically grant the creator permission to view those objects. Therefore, users who have permission to create an object (such as roles) must also be given permission to edit the same object. Otherwise, they can't see the object they create. When you grant permission to create an object, we recommend that you also grant permission to edit all objects of the type that they have permission to create.

For example, to allow a user to create roles and also view/edit the roles they create, we recommend assigning these permission sets:
Type Permission Object
User roles Create A specific object or all objects of this type ("*")
User roles Edit All (or "*")
Tip: If you also want the role creator to be able to assign users to the role or view role membership, make sure you also grant the Edit members permission for all objects ("*").
As another example, to allow a user to create user records and also see the user records they create, we recommend the following:
Type Permission Object
Users Create A specific object or all objects of this type ("*")
Users Edit All (or "*")
Related information:

Least-privilege model: Avoid overly-permissive permissions

Operators, one of the default PE roles, have many of the same permissions as Administrators. However, we've intentionally limited this role's ability to edit user roles. This way, users with the Operators role can do many of the same things as Administrators, but they can't edit (or enhance) their own permissions.

Similarly, when you're editing permission or creating your own roles, avoid granting users more permissions than necessary. For example, if users have the roles:edit:* permission, this allows them to add the node_groups:view:* permission to the roles they belong to, and, subsequently, see all node groups. Take care that permissions you've granted don't have the potential to allow a user to view or change something you don't want them to view or change.

Grant edit directory service permissions sparingly

The directory service password is not redacted when a user requests directory service settings through the RBAC API. Make sure the directory_service:edit:* permission is only granted to users who are allowed see the directory service password and other settings.

Grant reset password permissions along with other password permissions

The users:reset_password:<INSTANCE> permission allows a user to issue a password reset token to a user who forgot their password. However, this permission also reinstates revoked users when the password reset token is used. Therefore, make sure the users you allow to reset passwords are also allowed to revoke and reinstate users. Otherwise, you might have unauthorized users reinstating revoked users.