Users and Roles for Pentaho Security

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 ChangePasswordUser 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.