Jump to content
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

    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.

    note-icon-ns_28x28.png.a0ef2213f0257c43e28c7e6a2a55b75a.png

    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

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


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...