The permissions Service

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
Permissions

Boolean
optional

When set to true, the effective permissions are returned. By default, this argument is false and only assigned permissions are returned.

recipientType

String
optional

Either user or role. When not specified, the recipient type is the role.

recipientId

String
optional

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
optional

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 

<permissions>
  <permission>
    <mask>0</mask>
    <recipient>user:/anonymousUser</recipient>
  </permission>
  <permission>
    <mask>0</mask>
    <recipient>user:/organization_1/CaliforniaUser</recipient>
  </permission>
  ...
  <permission>
    <mask>2</mask>
    <recipient>role:/ROLE_USER</recipient>
    <uri>/public</uri>
  </permission>
</permissions>

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=
<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"
    }
]}

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"
    }
]}

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"
}

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=
<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:

{
  "uri": null,
  "recipient": null,
  "mask":"2"
}

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