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 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. |
Copyright © Pentaho.com