Skip to main content
Version Pentaho
Hitachi Vantara Lumada and Pentaho Documentation

Manage Users and Roles in the PDI Client

  1. Last updated
  2. Save as PDF

This section provides an overview of the default assignments for users and roles, the permissions included, and the management of users and roles in the Pentaho Repository. You must login to the PDI client (also known as Spoon) as an administrator (or be assigned to a role that has Administer Security permission) to manage users and roles for Pentaho Security.

Here is how you can manage users:

Here is how you can manage roles:

Before changing security settings, play it safe and back up these relevant files:

  • If you installed PDI using the Pentaho Suite Installer or custom methods, back up all Data Integration directories.
  • If you installed PDI using the manual method, back up the pentaho.war file and solutions.

You can control users and roles in the Pentaho Repository with a point-and-click user interface. The users and roles radio buttons allow you to switch between user and role settings. You can add, delete, and edit users and roles from this page.

Sample Users, Default Roles, and Permissions

By viewing the sample users and default roles you can get ideas about ways to define actual users and specific roles. 

  1. Open Spoon and login to the repository.
  2. Click Tools > Repository > Explore and then select the Security tab.
  3. Select the User radio button then highlight a user to display the user's role and a description, if any.
  4. Select the Roles radio button then highlight a role in the Available list to display Permissions for the user's role, as defined by the checked boxes. These roles, added for your convenience, can be removed or altered based on your needs (see Table 1). Each default role and sample user comes with a standard set of permissions, which provides for a specific set of capabilities when using Pentaho tools and the Pentaho Server (see Table 2).
  5. Select the System Roles radio button then highlight a role in the Available list to display the Permissions for the user's system role. System Roles are built-in roles used to control default behaviors and permissions of the repository, handled implicitly or through system configuration, with automatic assignments.  

PDI_security_page2.png

Table 1. Default Pentaho Security Settings

Default Role Sample User Permissions
Administrator admin
  • Administer Security
  • Schedule Content
  • Read Content
  • Publish Content
  • Create Content
  • Execute
  • Manage Data Sources
Power User suzy
  • Schedule Content
  • Read Content
  • Publish Content
  • Create Content
  • Execute
Report Author tiffany
  • Schedule Content
  • Publish Content
Business Analyst pat
  • Publish Content
Table 2. Permissions Defined
Permissions Definition
Administer Security The default Administrator role automatically conveys all operation permissions to users assigned to that role, even if the check box next to it is cleared. This includes the Read and Create Content permissions, which are required for accessing the Administration perspective:
  • Allows access to and the ability to manage all content in each perspective.
  • Allows the ability to view and work with all user schedules in the Schedules perspective.
Schedule Content
  • Allows the user to schedule reports and content.
  • Gives the user the ability to view, edit, or delete their own schedules using the Schedules perspective.
Read Content
  • Gives the user the ability to view content in each perspective.
Publish Content
  • Allows the user to store reports or data models in the Pentaho Repository.
Create Content
  • Allows the user to create, import, delete, and save jobs and transformations to the repository.
  • Gives the user the ability to see the data sources that are used to create jobs and transformations.
  • When the user is also granted the Execute permission, users can export jobs and transformations, copy and paste, and save the file in a virtual file system (VFS).
Execute 
  • Allows the user to run, preview, debug, replay, verify, and schedule.  
  • When the user is also granted the Create permission, users can export jobs and transformations, copy and paste, and save the file in a VFS.
Manage Data Sources
  • Allows the user to create, edit, or delete new data sources.
  • Gives the user the ability to see a list of repository data sources.

Add Users

  1. With the Users radio button selected, click the plus (+) icon next to Available. The Add User dialog box appears.

  2. Enter the User Name and Password associated with your new user account in the appropriate fields. An entry in the Description field is optional. 

  3. If you have available roles that can be assigned to the new user, under Member, select a role and click OK. The role you assigned to the user appears in the right pane under Assigned. 

  4. Click OK to save your new user account and exit the Add User dialog box. The name of the user you added appears in the list of available users.

Change User Passwords

  1. With the Users radio button selected, highlight the user for whose password you want to change then click the Edit icon. The Edit User dialog box appears.
  2. In the Password field, type the new password. Click OK. The password is changed and the user is able to login with the new password.

When you login to the PDI client for the first time, it is a best practice to change the default administrator password.

Delete Users

We recommend that you disable a user or role instead of deleting it.

  1. With the Users radio button selected, highlight the user to be deleted in the Available list.
  2. Next to Available, click the X icon. A security message appears.
  3. Click Yes to remove the user. The specified user is deleted.

If a user or role is deleted in the Pentaho Repository, content that refers to the deleted user, either by way of owning the content or having an ACL that mentions the user or role, is left unchanged. This situation makes it possible to create a new user or role using an identical name. In this scenario, content ownership and access control entries referring to the deleted user or role now apply to the new user or role. To avoid this problem, disable a user or role to prevent the creation of a user or role with an identical name. Use these alternatives rather than deleting the user or role.

If... Then...
You are disabling a role Unassign all current members associated with the role.
You are disabling a user Reset the password to a password that is so cryptic that it is impossible to guess and is unknown to any users.

Assign Users to Roles

  1. Click the Roles radio button. The list of available roles appears.
  2. Select the role to which you are assigning users.

    If the role has users currently assigned to it, the names of the users appear in the table on the right under Members. You can assign or unassign any users to a role. You can select a single item or multiple items from the list of members. Click Remove to remove the user assignment.

  3. Next to Members, click the plus (+) icon. The Add User to Role dialog box appears.

  4. Select the users you want assigned to the role and click the right arrow (>). The users assigned to the role appear in the right pane.
  5. Click OK to save your entries and exit the Add User to Role dialog box. The specified users are assigned to the specified role.

Edit User Information

  1. With the Users radio button selected, highlight the user you want to edit in the Available list.
  2. Click the Edit icon. The Edit User dialog box appears.
  3. Make the appropriate changes to the user information.
  4. Click OK to save your changes and exit the Edit User dialog box.

Add Roles

  1. Click the Roles radio button. The list of available roles appear.
  2. Click the plus (+) icon next to Available. The Add Role dialog box appears.
  3. Enter the Role Name. An entry in the Description field is optional. 

  4. If you have users to assign to the new role, select them (using the <SHIFT> or <CTRL> keys) from the list of available users and then click the right arrow (>).  The user(s) assigned to your new role appear in the right pane.

  5. Click OK to save your entries and exit the Add Role dialog box. The specified role is created and is ready to be assigned to user accounts.

Edit Roles

  1. Click the Roles radio button. The list of available roles appear.
  2. Select the role you want to edit and click the Edit icon. The Edit Role dialog box appears.
  3. Make the appropriate changes.
  4. Click OK to save your changes and exit the Edit Role dialog box.

Delete Roles

  1. Click the Roles radio button. The list of available roles appears.
  2. Select the role you want to delete from the Available list.
  3. Click the X icon next to Available. A security message appears.
  4. Click Yes to remove the role. The specified role is deleted.

Make Changes to the Administrator Role

The assignment of action-based permissions associated with the administrator role (read, create, execute, and administrate) in the Pentaho Repository cannot be edited in the user interface. The administrator role is the only role that is assigned the Administer Security permission and controls user access to the Security tab. 

Deleting the administrator role will prevent all users from accessing the Security tab unless another role is assigned the administrator permission. 

These are the scenarios that require a configuration change that is unavailable through the PDI client:

  • You want to delete the administrator role
  • You want to unassign the administrator permission from the administrator role
  • You want to configure LDAP

Follow these instructions to change the administrator role:

  1. Shut down the Pentaho Server.
  2. Open the repository.spring.xml file located at \pentaho-server\pentaho-solutions\system\.
  3. Locate the element with an ID of immutableRoleBindingMap.
  4. Replace the entire node with the XML shown below. Make sure you change yourAdminRole to the role that will have Administrate permission. 
    <util:map id="immutableRoleBindingMap">
    <entry key="yourAdminRole">
      <util:list>
        <value>org.pentaho.di.reader</value>
        <value>org.pentaho.di.creator</value>
        <value>org.pentaho.di.securityAdministrator</value>
      </util:list>
    </entry>
</util:map>
  5. Restart the Pentaho Server. The administrator role changes according to your requirements.

Assign User Permissions in the Repository using the PDI Client

You can restrict what users see by assigning roles to users. For example, you can create administrative groups who are allowed permissions in the repository to administer security and create new content.
  1. Click the Roles radio button. The list of available roles appears.
  2. In the Available list, highlight the role to which you are assigning permissions . 
  3. In the Permission list, select the check boxes to enable (or deselect to disable) permissions and then click Apply. The permissions you enabled for the role take effect the next time the specified user(s) login.

Enable System Role Permissions

Pentaho requires the Authenticated system role for users, including administrative users, to login to the Pentaho Repository. Pentaho Repository users are automatically assigned the Authenticated system role, in addition to the role you assigned them, at login. By default, the Authenticated system role provides Read Content permission. You can change permissions as needed.

The Anonymous system role is non-functional and not being used at this time.

  1. Click the System Roles radio button. System roles appear in the Available list.
  2. Select the Authenticated role. 
  3. Under Permissions, select the check boxes to enable (or deselect to disable) permissions for this role.
  4. Click Apply to save your changes. The specified permissions are enabled for the Authenticated system role.