Skip to main content
Pentaho Documentation

Users and Roles for Pentaho Security

This group of REST APIs allows you to work with Pentaho Security users and roles in the Business Analytics platform. You will be able to create or delete users or roles, assign roles to users, list members or roles, assign permissions to roles, or change user passwords. 

Our REST APIs typically follow this pattern. Substitute each generic parameter with your custom parameter:

[server path]/[rest path]/[query parameter]

Users

The REST APIs listed in this section are used to manage Pentaho Security Users. 

Create a user

Creates a new user with a specified name and password. This request is encapsulated inside a user object that has userName and password values. The user is created without assigned roles, which must be assigned separately.

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

PUT

PUT pentaho/api/userroledao/createUser

Parameters

Name Description Type
user Object used to pass along a userName and password. query

Request Body

A user is an object the system uses to pass along a userName and password in this format: 

Luke
password
Element Media Types
user */*
application/xml
application/octet-stream

Response Body

Response object containing the status code of the operation.

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully created new user.
400 Provided data has invalid format.
403 Only users with administrative privileges can access this method.
412 Unable to create user.

Delete a user or users

Delete user(s) from the platform using a query parameter that takes a list of tab-separated user names.

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

PUT

PUT pentaho/api/userroledao/deleteUsers?userNames=user1%09user2%09

Parameters

Name Description Type
userNames (List of tab (\t) separated user names) query

Request Body

There is no specific request body for this operation. 

Response Body

Response object containing the status code of the operation.

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully deleted the list of users.
403 Only users with administrative privileges can access this method
500 Internal server error prevented the system from properly retrieving either the user or roles.

Change user password

Allows a user to change their password. The information is encapsulated in a ChangeUserPassword object that contains these fields: userName, newPassword, oldPassword. 

Available Methods

HTTP Verb Example Request

PUT

PUT pentaho/api/userroledao/user 

Parameters

Name Description type
ChangePasswordUser Encapsulates the fields required for a user to update their password. The object requires the name of the user whose password is being changed, the old password, and the new password. query

Request Body

Luke
newPassword
oldPassword
Element Media Types

ChangePasswordUser

*/*
application/xml
application/octet-stream

Response Body

Response object containing the status code of the operation.

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully changed password.
400 Provided data has invalid format.
403 Provided user name or password is incorrect.
412 An error occurred in the platform.

Get list of users

Returns the list of users in the platform's repository.

Available Methods

HTTP Verb Example Request

GET

GET pentaho/api/userroledao/users

Parameters

There are no specific parameters for this operation.

Request Body

There is no specific request body for this operation.  

Response Body

Response is a list of users in the platform.

Element Media Types
userList application/xml
application/json

Example Response:

<userlist>
<users>suzy</users>
<users>pat</users>
<users>tiffany</users>
<users>admin</users>
</userlist>

Status Codes

Code Description
200 Successfully returned the list of users.
500 An error occurred in the platform while trying to access the list of users.

Get roles for a user

Gets a list of roles for the given user. 

Available Methods

HTTP Verb Example Request

GET

GET pentaho/api/userroledao/userRoles?userName=suzy

Parameters

Name Description Type
userName The username to get the roles for. query

Request Body

There is no specific request body for this operation. 

Response Body

Response body is a list containing the roles for the given user. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><roleList><roles>Power User</roles></roleList>
Element Media Types
roleList application/xml
application/json

Status Codes

Code Description
200 Successfully retrieved the list of roles.
500 Invalid user parameter.

Assign a role to a user

Appends existing roles to an existing user passed to the system through query parameters.

If the user name exists but the role name is invalid, the call will return 200. This means that the call itself was successful and able to find the user, but added no new roles to it. This prevents the call from failing in the instance of a set of other valid roles, with a single invalid role among them. 

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

PUT

PUT pentaho/api/userroledao/assignRoleToUser?userName=admin&roleNames=power%20user%09cto%09

Parameters

Name Description Type
userName The username that the list of roles will be appended to query
roleNames Rolenames must be associated to existing roles in a tab (\t) separated list query

Request Body

There is no specific request body for this operation. 

Response Body

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully append the roles to the user.
403 Only users with administrative privileges can access this method.
500 Internal server error prevented the system from properly retrieving either the user or roles.

Remove a role from a user

Removes selected roles from an existing user passed to the system through query parameters.

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

PUT

PUT pentaho/api/userroledao/removeRoleFromUser?userName=admin&roleNames=Business%20User%09Power%20User%09

Parameters

Name Description Type
userName The username that the list of roles will be removed from. query
roleNames Rolenames must be associated to existing roles in a tab (\t) separated list. query

Request Body

There is no specific request body for this operation. 

Response Body

Response object containing the status code of the operation.

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully removed the roles from the user.
403 Only users with administrative privileges can access this method.
500 Internal server error prevented the system from properly retrieving either the user or roles.

Roles

The REST APIs listed in this section are used to manage Pentaho Security Roles. 

Create a role

Creates a new Role that does not have any permissions assigned to it. Permissions must be assigned after creating the role.

This endpoint is only available to users with administrative privileges.

Available Methods 

HTTP Verb Example Request

PUT

PUT pentaho/api/userroledao/createRole?roleName=rName

Parameters

Name Description Type
roleName Name of the new role to create in the system. query

Request Body

There is no specific request body for this operation. 

Response Body

Response containing the result of the operation.

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully created new role.
400 Provided data has invalid format.
403 Only users with administrative privileges can access this method.
412 Unable to create role objects.

Delete a role or roles

Delete a role or roles from the platform. 

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

PUT

PUT pentaho/api/userroledao/deleteRoles?roleNames=role1%09

Parameters

Name Description Type
roleNames List of tab (\t) separated role names, must be valid roles. query

Request Body

There is no specific request body for this operation. 

Response Body

Response containing the result of the operation.

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully deleted the list of roles.
403 Only users with administrative privileges can access this method.
500 The system was unable to delete the roles passed in.

Get a list of roles

Returns the list of roles in the platform's repository. 

Available Methods

HTTP Verb Example Request

GET

GET pentaho/api/userroledao/roles

Parameters

There are no specific parameters for this operation.

Request Body

There is no specific request body for this operation. 

Response Body

List of roles in the platform.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><roleList><roles>Administrator</roles><roles>Power User</roles><roles>Report Author</roles><roles>Business Analyst</roles></roleList>>
Element Media Types
roleList application/xml
application/json

Status Codes

Code Description
200 Successfully retrieved the list of roles.
500 The system was not able to return the list of roles.

List members of a role

Retrieves list of users for the selected role. The role must be a valid role in the system.

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

GET

GET pentaho/api/userroledao/roleMembers?roleName=Power%20User

Parameters

Name Description Type
roleName The role name to get the list of users associated with it. query

Request Body

There is no request body for this operation.

Response Body

List of users for the selected role.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><userList><users>suzy</users><users>admin</users></userList>
Element Media Types
userList application/xml
application/json

Status Codes

Code Description
200 Successfully retrieved the list of Users.
403 Only users with administrative privileges can access this method.
500 The system was not able to return the list of users.

Assign permissions to a role

Associate a particular role to a list of physical permissions available in the system. Setting the physical permissions to the roles is a way to add and delete permissions from the role. Any permissions the role had before that are not on this list will be deleted. Any permissions on this list that were not previously assigned will now be assigned.

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

PUT

PUT /pentaho/api/userroledao/roleAssignments
<systemRolesMap>
<assignments>
<roleName>Report Author</roleName>
<logicalRoles>org.pentaho.scheduler.manage</logicalRoles>
<logicalRoles>org.pentaho.repository.read</logicalRoles>
<logicalRoles>org.pentaho.security.publish</logicalRoles>
<logicalRoles>org.pentaho.repository.create</logicalRoles>
<logicalRoles>org.pentaho.repository.execute</logicalRoles>
</assignments>
</systemRolesMap>

Parameters

Name Description type
roleAssignments Built from the Request payload, an example of the role assignments exists in the example request. query

Request Body

Built from the Request payload, an example of the role assignments exists in the example request.

Element Media Types
logicalRoleAssignments application/xml
application/json

Response Body

Response code determining the success of the operation.

Element Media Types
(custom) */*
application/xml
application/octet-stream

Status Codes

Code Description
200 Successfully applied the logical role assignment.
403 Only users with administrative privileges can access this method.

List permissions for roles

Retrieves the list of roles in the platform and the mapping for operation permissions, along with a list of operation permissions. The logical role name mapping is determined by the locale. If the locale is empty, the system will use the default locale of "en".

This endpoint is only available to users with administrative privileges.

Available Methods

HTTP Verb Example Request

GET

GET pentaho/api/userroledao/logicalRoleMap?locale=en

Parameters

Name Description type
locale The locale parameter is optional and determines the localized role name for a physical permission in the system roles map. query

Request Body

There is no specific request body for this operation.

Response Body

A role mapping for the current system. Each assignment contains the immutable flag and roles for immutable assignments cannot be edited. This is useful for roles such as administrator, who should never lose the administrative privilege. Logical roles in the assignment are the physical permissions currently mapped to the role. The role name is the name of the role that can be assigned to users. The system roles map also includes a list of all physical permissions in the system along with their localized role name. The localized role name is based on the local passed into the call, defaulting to "en". These are the physical permissions that can be used to create roles.

Element Media Types
systemRolesMap application/xml
application/json

Example Response:

<systemRolesMap>
<assignments>
<immutable>false</immutable>
<logicalRoles>org.pentaho.scheduler.manage</logicalRoles>
<logicalRoles>org.pentaho.security.publish</logicalRoles>
<logicalRoles>org.pentaho.repository.create</logicalRoles>
<logicalRoles>org.pentaho.repository.execute</logicalRoles>
<roleName>Power User</roleName>
</assignments>
<assignments>
<immutable>true</immutable>
<logicalRoles>org.pentaho.repository.execute</logicalRoles>
<logicalRoles>
org.pentaho.platform.dataaccess.datasource.security.manage
</logicalRoles>
<logicalRoles>org.pentaho.repository.read</logicalRoles>
<logicalRoles>org.pentaho.repository.create</logicalRoles>
<logicalRoles>org.pentaho.scheduler.manage</logicalRoles>
<logicalRoles>org.pentaho.security.administerSecurity</logicalRoles>
<logicalRoles>org.pentaho.security.publish</logicalRoles>
<roleName>Administrator</roleName>
</assignments>
<localizedRoleNames>
<localizedName>Administer Security</localizedName>
<roleName>org.pentaho.security.administerSecurity</roleName>
</localizedRoleNames>
<localizedRoleNames>
<localizedName>Schedule Content</localizedName>
<roleName>org.pentaho.scheduler.manage</roleName>
</localizedRoleNames>
<localizedRoleNames>
<localizedName>Read Content</localizedName>
<roleName>org.pentaho.repository.read</roleName>
</localizedRoleNames>
<localizedRoleNames>
<localizedName>Publish Content</localizedName>
<roleName>org.pentaho.security.publish</roleName>
</localizedRoleNames>
<localizedRoleNames>
<localizedName>Create Content</localizedName>
<roleName>org.pentaho.repository.create</roleName>
</localizedRoleNames>
<localizedRoleNames>
<localizedName>Execute</localizedName>
<roleName>org.pentaho.repository.execute</roleName>
</localizedRoleNames>
<localizedRoleNames>
<localizedName>Manage Data Sources</localizedName>
<roleName>
org.pentaho.platform.dataaccess.datasource.security.manage
</roleName>
</localizedRoleNames>
</systemRolesMap>

Status Codes

Code Description
403 Only users with administrative privileges can access this method.