Creating and Managing Users and User Roles
A newer version is available; see the version menu above for details.
User roles are sets of permissions you can apply to multiple users in Puppet Enterprise (PE). Role-based access control (RBAC) enables you to manage users — what they can create, edit, or view, and what they can’t — in an organized, high-level way that is vastly more efficient than managing user permissions on a per-user basis.
Note: Users must be assigned to roles before they can work in PE.
Note: You can’t assign permissions to single users, only to roles.
PE comes with three predefined roles: Administrators, Operators, and Viewers. These roles have been given a handful of permissions based on the function of the roles. You can also define your own custom roles.
This section describes how to create a new user, create a new user role, assign permissions to a user role, and add a user to a user role. You’ll also find out how to import a user group from an external directory and then assign the group to a user role.
Create a New User
These steps add a local user. To add a user from an external directory, see Working with Users and User Groups from an External Directory, below.
- In the console, click Access control, and then click Users.
- On the Users page, in the Full name field, type the user’s full name.
- In the Login field, type a username for the user.
- Click Add local user.
Give the User Access
When you create new local users, you need to send them a password reset token so that they can log in for the first time.
- Click the new local user in the Users list. The new user’s page opens.
- On the upper-right of the page, click Generate password reset. A Password reset link message box opens.
- Copy the link provided in the message and send it to the new user. Then you can close the message.
Create a New User Role
Users with the appropriate permissions, for example, Administrators, can define custom roles. Only users who are allowed all permissions should be given the permission to edit user roles; otherwise, the user will be capable of privilege escalation.
- In the console, click Access control and then click User Roles.
- For Name, type a name for the role, and then for Description, type a description for the role.
- Click Add role.
Assign Permissions to a User Role
Before you begin assigning permissions to a user role, make sure you have reviewed the information on RBAC permissions. In particular, see the section “What You Should Know About Assigning Permissions,” to learn some important considerations about how permissions work in PE.
- In the list of user roles, click a user role that you want to add permissions to.
- Click the Permissions tab.
- In the Type box, select the type of object you want to assign permissions for, such as Node groups.
- In the Permission box, select the permission you want to assign, such as View.
- In the Object box, select the specific object you want to assign the permission to. For example, if you are setting a permission to view the type, Node groups, select the specific node this user role will have permissions to view.
- Click Add permission, and then click the commit button.
Add a User to a User Role
When you add users to a role, the user gains the permissions that are applied to that role. As has been mentioned, a user can’t do anything in PE until they have been assigned to a role.
- In the list of user roles, click a user role that you want to add a user to.
- Click the Member users tab.
- In the User name field, from the drop-down list, select the user you want to add, click Add user, and then click the commit button.
Revoking a User’s Access
If you want to remove a user’s access to PE but not delete their account, you can revoke them. Revocation is also what happens when a user is locked out from too many incorrect password attempts.
To revoke a user:
In the left pane of the PE console, click Access control.
Click Users and click the user that you want to revoke.
Click Revoke user access.
To unrevoke a user, follow the steps above and click Reinstate user access.
Deleting a User
If you want to delete a user, you can use the RBAC API. This will remove all data about the user except for their activity data, which will continue to be stored in the database.
Working with User Groups and Users from an External Directory Service
You import existing external directory groups to PE explicitly, which means you add the group by name. After you’ve imported a group, you can assign it to a user role, and then begin assigning permissions to it.
Adding External Directory Users to PE
You don’t explicitly add remote users to PE. Instead, remote users must log in to PE, which creates a record of the user in PE. If the user belongs to an external directory group that has been imported into PE and then assigned to a role, the user will be assigned to that role and will gain the privileges of the role. Roles are additive: You can assign users to more than one role, and they will gain the privileges of all the roles to which they are assigned.
Import a User Group
On the Access control tab, click User Groups.
Note: User Groups is not available until you have established a connection with an external directory.
In the Login field, type the name of a group from your directory service, and then click Add group. The group is added to the User Groups list.
Click the name of the group you added.
A new page opens with tabs for User roles, Users, and Activity. Note that no user roles will be listed until you add this group to a role. No users will be listed until a user who belongs to this group logs into PE. The Activity tab lists any changes made to the group. If you have just imported a group, the date the group was added will be listed, as well as some other pertinent information.
Assign a User Group to a User Role
You can add user groups to existing roles, or you can create new roles, as described previously, and then add the group to the new role. Assign user groups to user roles as follows.
- Click User roles, and then click the role you want to add the user group to. Alternatively, you can create a new user role.
- Click Member groups, and then on the Group name drop-down list, select the user group you want to add to the user role.
- Click Add group, and then click the commit button.
Removing a Remote User’s Access
If you delete a remote user, remember that they can continue to log in to the console as long as their account exists in an external directory service that PE is configured to access.
If you delete a user from your external directory service but not from PE, the user can no longer log in, but any generated tokens or existing console sessions will continue to be valid until they expire. To invalidate the user’s tokens or sessions, revoke or delete the user’s account in PE. You must manually delete them from PE for their account record to disappear.
Managing Your User information
To view and update your user information, in the lower left corner of the PE console, click My account.
Troubleshooting Admin and User Access to the Console
For any number of reasons, you might need to either reset the admin password for PE console access, or the passwords of other users. The process is different in each case.
Reset the Admin Password
In RBAC, one of the built-in users is the admin, a superuser with all available read/write privileges. To reset the admin password for console access, you’ll need to run the
update-superuser-password.rb utility script as follows:
Log in to the console node as root.
Note: The script must be run from the command line of the server installed with the console component. In a split install, it cannot be run from the Puppet master.
The script file is not installed by default. You can find it in the PE installer tarball. On the PE download site, copy the Download Now link for your OS. In the command line, run
wget <YOUR COPIED PE TARBALL LINK>. If your OS doesn’t use
wget, run the equivalent command for your OS.
Note: When pasting the tarball link, you need to delete any characters after “.gz”.
Extract the script from the tarball.
Find the file path of the script in the tarball by running
tar -tzf <YOUR TARBALL FILE NAME> | grep superuser. Then, extract the script from the tarball by running
tar -xf <YOUR TARBALL FILE NAME> <FILE PATH OF SCRIPT>.
Copy the script to
Navigate to the folder where the tarball extracted. To copy the script to
cp update-superuser-password.rb /opt/puppetlabs/puppet/bin/update-superuser-password.rb.
Run the script.
Navigate to the
/opt/puppetlabs/puppet/bindirectory. To run the script and specify your new password, type:
q_puppet_enterpriseconsole_auth_password=<YOUR NEW PASSWORD> q_puppetagent_certname=$(puppet config print certname) /opt/puppetlabs/puppet/bin/ruby update-superuser-password.rb
Note: The script is not directly executable. It must be invoked using the version of Ruby shipped with PE, using
Note: The script uses a series of API calls authenticated with a whitelisted certificate.
Generate a User Password Reset Token
When users forget passwords or lock themselves out of the console by attempting to log in with incorrect credentials too many times, you need to generate a password reset token. You can do this from the console or by using API calls. To generate a password reset token from the console, see the steps in the section, Give the User Access. To learn more about using API calls to generate the token, see the RBAC service password APIs.