The rest_v2/permissions service reads and sets permissions on resources in the repository.
This chapter includes the following sections:
| • | Permission Constants |
| • | Viewing Multiple Permissions |
| • | Viewing a Single Permission |
| • | Setting Multiple Permissions |
| • | Setting a Single Permission |
| • | Deleting Multiple Permissions |
| • | Deleting a Single Permission |
Permission Constants
In the permissions service, the syntax allows you to specify the resource, the recipient (user name or role name) and the permission value within the URL. This makes it simpler to set permissions because you don’t need to send a resource descriptor to describe the permissions. In order to set, modify, or delete permissions, you must use credentials or login with a user that has “administer” permissions on the target resource.
The permissions for each user and each role are indicated by the following values. These values are not a true mask; they should be treated as constants:
| • | No access: 0 |
| • | Administer: 1 |
| • | Read-only: 2 |
| • | Read-write: 6 |
| • | Read-delete: 18 |
| • | Read-write-delete: 30 |
| • | Execute-only: 32 |
Because a permission can apply to either a user or a role, the permissions service uses the concept of a recipient. A recipient specifies whether the permission applies to a user or a role, and gives the ID of the user or role, including any organization, for example:
role:/ROLE_ADMINISTRATOR (this is a root role and thus has no organization specified)
user:/organization_1/joeuser
Recipients are listed when viewing permissions, and they are also used to set a permission. A recipient can be specified in a URL parameter when allowed, but in this case, the slash (/) character must be encoded as %2F.
There are two qualities of a permission:
| • | The assigned permission is one that is set explicitly for a given resource and a given user or role. Not all permissions are assigned, in which case the permission is inherited from the parent folder. |
| • | The effective permission is the permission that is being enforced, whether it is assigned or inherited. |
| | There is one permission that is not defined: you cannot read or write the permission for ROLE_SUPERUSER on the root . |
Viewing Multiple Permissions
The GET method of the permissions service lists permissions on a given resource according to several arguments.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions/path/to/resource/?<arguments> | ||
| Argument | Type/Value | Description | |
| effective | Boolean | When set to true, the effective permissions are returned. By default, this argument is false and only assigned permissions are returned. | |
| recipientType | String | Either user or role. When not specified, the recipient type is the role. | |
| recipientId | String | Id of the user or role. In environments with multiple organizations, specify the organization as %2F<orgID>%2F<recipientID> (%2F is the / character). | |
| resolveAll | Boolean | When set to true, shows the effective permissions for all users and all roles. | |
| Options | |||
| accept: application/xml (default) accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The body describes the requested permissions for the resource. | 400 Bad Request – When the recipient type is invalid. 404 Not Found – When the specified resource URI is not found in the repository or the recipient ID cannot be resolved. | ||
For example, the following request shows all permission for a resource, similar to the permissions dialog in the user interface:
GET http://localhost:8080/jasperserver-pro/rest_v2/permissions/public?resolveAll=true
0 user:/anonymousUser 0 user:/organization_1/CaliforniaUser ... 2 role:/ROLE_USER /public [/code] |
Viewing a Single Permission
Specify the recipient in the URL to see a specific assigned permission. To view effective permissions, use the form above.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions/path/to/resource;recipient= | ||
| Argument | Type/Value | Description | |
| recipient | string required | The recipient format specifies user or role, the object ID, and the organization ID if necessary. The slash character must be encoded, for example: user:%2Forganization_1%2Fjoeuser | |
| Options | |||
| accept: application/xml (default) accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The body describes the requested permission. | 404 Not Found – When the specified resource URI or recipient is invalid, or when the recipient does not have any assigned permission (only inherited ). | ||
Setting Multiple Permissions
The POST method assigns any number of permissions to any number of resources specified in the body of the request. All permissions must be newly assigned, and the request will fail if a recipient already has an assigned (not inherited) permission. Use the PUT method to update assigned permissions.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions | ||
| Content-Type | Content | ||
| application/collection+json | A JSON object that describes a set of permissions, for example: { "permission" :[ { "uri":"/properties", "recipient":"role:/ROLE_USER", "mask":"1" }, { "uri":"/properties", "recipient":"role:/ROLE_ADMINISTRATOR", "mask":"32" }]}[/code] | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 201 Created – The request was successful. | 400 Bad Request – A permission is already assigned or the given permission mask is invalid. | ||
The PUT method modifies exiting permissions (already assigned).
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions/path/to/resource | ||
| Content-Type | Content | ||
| application/collection+json | A JSON object that describes a set of permissions. Because a single resource is specified in the URL, all permissions apply to the same resource, and the server ignores the uri field in the JSON object. { "permission" :[ { "uri":"/foo", "recipient":"role:/organization_1/ROLE_MANAGER", "mask":"30" }, { "uri":"/bar", "recipient":"user:/organization_1/joeuser", "mask":"32" }]}[/code] | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The request was successful. | 400 Bad Request – If a recipient or mask is invalid. 404 Not Found – If the resource in the URL is invalid. | ||
Setting a Single Permission
The POST method accepts a single permission descriptor.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions | ||
| Content-Type | Content | ||
| application/json | A JSON object that describes a single permission on a single resource, for example: { "uri":"/properties", "recipient":"role:/ROLE_USER", "mask":"1"}[/code] | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 201 Created – The request was successful. | 400 Bad Request – The permission is already assigned or the given mask is invalid. | ||
The PUT method accepts a resource and recipient in the URL.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions/path/to/resource;recipient= | ||
| Argument | Type/Value | Description | |
| recipient | string required | The recipient format specifies user or role, the organization if necessary, and the object ID. The slash characters must be encoded, for example: user:%2Forganization_1%2Fjoeuser | |
| Content-Type | Content | ||
| application/json | A JSON object that describes only the mask, for example: | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The request was successful, and the response body contains the single permission that was modified. | 400 Bad Request – If the mask is invalid. 404 Not Found – If the resource or the recipient in the URL is invalid. | ||
Deleting Multiple Permissions
The DELETE method removes all assigned permissions from the designated resource. After returning successfully, all effective permissions for the resource are inherited.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions/path/to/resource | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 204 No Content – The request was successful. | 404 Not Found – If the resource in the URL is invalid. | ||
Deleting a Single Permission
Specify a recipient in the URL of the DELETE method to remove only that permission.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions/path/to/resource;recipient= | ||
| Argument | Type/Value | Description | |
| recipient | string required | The recipient format specifies user or role, the organization if necessary, and the object ID. The slash characters must be encoded, for example: user:%2Forganization_1%2Fjoeuser | |
| Return Value on Success | Typical Return Values on Failure | ||
| 204 No Content – The request was successful. | 404 Not Found – If the resource or the recipient in the URL is invalid. | ||
Recommended Comments
There are no comments to display.