Skip to main content
Pentaho Documentation

Use Pentaho Security on the DI Server

Overview

Explains how to set up Pentaho Security.

You must log into Spoon as an administrator (or be assigned to a role that has Administer Security permission) to manage users and roles for Pentaho Security. This section provides an overview of the out-of-box users and roles, along with the permissions that are included with each role. 

Before changing security settings, play it safe and back up these relevant files.
  • If you installed PDI using the wizard or custom methods, back up all Data Integration directories.
  • If you installed PDI using the manual method, back up the pentaho-di.war file and solutions.

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.

Default Users, Roles, and Permissions

Viewing default users and roles gives you an idea of how you can define your specific users and roles. To view the default users and roles, log into Spoon, click Tools > Repository > Explore and select the Security tab. Highlighting a user in the users list shows which roles are available for that user, as well as which role is currently defined for that user.

Out-of-Box Role Out-of-Box User Permissions
Administrator admin
  • Administer Security
  • Read Content
  • Execute 
  • Create content
Power User suzy
  • Read Content
  • Execute 
  • Create Content
Report Author tiffany
  • None configured by default
Business Analyst pat
  • None configured by default

Each operation permission gives a specific set of permissions for Pentaho tools and the DI Server.

Table 1. Operation Permissions Defined
Operation Permission 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.
Read Content
  • Gives the user the ability to view content in each perspective.
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 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.

 

Add Users

  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
    Note: The Users radio button is selected by default.
  3. Next to Available, click the round green plus button, Add. The Add User dialog box appears.
  4. Type the User Name and Password associated with your new user account in the appropriate fields.
    Note: An entry in the Description field is optional.
  5. If you have available roles that can be assigned to the new user, under Member, select a role and click OK. File:/ssSpoonAddUser.png

    The role you assigned to the user appears in the right pane under Assigned.

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

Change Passwords Using Spoon

  1. Launch Spoon as described in Start Spoon.
  2. Click on Tools > Repository > Explore.
  3. Click on Security.
  4. Select Users, Roles, or System Roles from the option button.
  5. Select the role for which you want to change the password and click the Edit icon.
  6. In the Password field, type the new password. Click OK.

Delete Users

You must be logged into the Pentaho Repository as an administrative user.
  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
  3. Select the user you want to delete from the list of available users.
  4. Next to Users, click Remove. A confirmation message appears.
  5. Click Yes to delete the user.

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 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, we recommend that you disable a user or role instead of deleting it. This prevents a user or role with an identical name from ever being created again. Use these alternatives rather than deleting the user or role.

IF THEN
You are dealing with a role Unassign all current members associated with the role
You are dealing with 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

You must be logged into the Pentaho Repository as an administrative user.

You can assign users to roles and roles to users when you add a new user or role. You can also assign users to roles as a separate task.

  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
  3. Click the Roles radio button. The list of available roles appear.
  4. Select the role to which you want to assign one or more users.
    Note: 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.
  5. Next to Members, click Add. The Add User to Role dialog box appears.
  6. Select the users you want assigned to the role and click Add. The users assigned to the role appear in the right pane.
  7. Click OK to save your entries and to exit the Add User to Role dialog box.
The specified users are assigned to the specified role.

Edit User Information

You must be logged into the Pentaho Repository as an administrative user.
  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
    Note: The Users radio button is selected by default.
  3. Select the user whose details you want to edit from the list of available users.
  4. Click Edit. The Edit User dialog box appears.
  5. Make the appropriate changes to the user information.
  6. Click OK to save changes and exit the Edit User dialog box.

Add Roles

You must be logged into the Pentaho Repository as an administrative user.
  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
  3. Click the Roles radio button. The list of available roles appear.
  4. Click Add. The Add Role dialog box appears.
  5. Enter the Role Name in the appropriate field.
    Note: An entry in the Description field is optional.
  6. 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 click the yellow arrow to move it from the left pane to the right pane. The user(s) assigned to your new role appear in the right pane.
  7. 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

You must be logged into the Pentaho Repository as an administrative user.
  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
  3. Click the Roles radio button. The list of available roles appear.
  4. Select the role you want to edit and click Edit. The Edit Role dialog box appears.
  5. Make the appropriate changes.
  6. Click OK to save your changes and exit the Edit Role dialog box.

Delete Roles

You must be logged into the Pentaho Repository as an administrative user.
  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
  3. Select the role you want to delete from the list of available roles.
  4. Click Remove. A confirmation message appears.
  5. Click Yes to delete the role.
The specified role is deleted.

Make Changes to the Administrator Role

The assigning of action-based permissions, (read, create, execute, and administrate), associated with the administrator role 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; the Administer Security permission controls user access to the Security tab.

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

These are the scenarios that require a configuration change not available through Spoon:

  • 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 DI Server.
  2. Open the repository.spring.xml file located at \pentaho\server\data-integration-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 DI Server.
The administrator role changes according to your requirements.

Assign User Permissions in the Repository using Spoon

You must be logged into the repository as an administrative user (or be assigned to a role that has Administer Security permission).

You can restrict what users see by assigning roles to users. For example, you can create administrative groups who are allowed to administer security and create new content.

To assign permissions in the repository, follow these instructions.

  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
  3. Click the Roles radio button. The list of available roles appear.
  4. Select the role to which you want to assign permissions.
  5. Enable the appropriate permissions and click Apply.
The permissions you enabled for the role take effect the next time the specified users log in.

Enable System Role Permissions

When users log into the Pentaho Repository, they are automatically assigned the Authenticated system role in addition to the role you assigned them.  Pentaho requires the Authenticated system role for users to log into the Pentaho Repository. This includes administrative users. By default, the Authenticated system role provides Read Content and Execute permissions to all users who are logged in. You can change these permissions as needed.

Note: Important! The Anonymous system role is not being used at this time.

Follow the steps below to change permissions for the Authenticated system role.

  1. In Spoon, go to Tools > Repository > Explore. The Repository Explorer opens.
  2. Click the Security tab.
  3. Click the System Roles radio button. The list of available system roles appear.
    Note: The Anonymous role is not functional.
  4. Select the Authenticated role from the list of available roles.
  5. Under Permissions, enable the appropriate permissions for this role.
  6. Click Apply to save your changes.
The specified permissions are enabled for the Authenticated system role.