Manage Permissions

This article explains how to define a permissions and control access to different parts of the GoodData deployment.

By default only the adminUser starts off with the permissions necessary to view and modify your GoodData projects. To make your project accessible to other users, we recommend you group users into appropriate user groups and assign permissions to these groups that are appropriate for the use case those users will face.

Permissions concept

The overall concept is based on rule that an action controlled by a permission is granted to a user or user group with the required or greater permission only.

Each permission definition is a combination of three elementary items:

• The object that is related to the protected action(s)
• The assignee that is either a user or user-group
• The permission recognized by its name

Object

An object is an instance of:

• Organization
• Data Source
• Workspace

The object holds permission definitions and this is how the assignee and permission and object get related.

Assignee

An assignee used in the permission definition is a particular instance of a User or a UserGroup. It is assigned using its identifier and type.

Permission

A permission is recognized by its name within the permission definition. In the application it maps to a set of actions that are restricted and unavailable to non-privileged users. The action set is not limited to the object only, it is spread out through hierarchy of permissions on actions of related objects too. Refer to the articles describing permission definition for each type of object to see which permissions you can choose from.

Permissions Hierarchy

Permissions are organized into hierarchy and scopes. The scope is determined by object type the permission is defined. The top most permission MANAGE from the organization scope is valid in any place a permission check is applied. The hierarchy of scopes represents the hierarchy of the top most permission MANAGE from each scope.

graph RL
    data-source --> organization
    workspace-hierarchy --> organization
    workspace --> workspace-hierarchy

If there is path from permission on lower level to higher level, then the permission from higher level is valid on all places the lower permission is required. Permissions within the scope are also hierarchically organized.

Permissions Considerations

Entities Listing API

Entities protected by permissions from unwanted access are automatically filtered out when listing them. A user with a top permission MANAGE will always see all the entities, while other users will see the list with entities they have granted a read or higher permission.

Permissions vs Includes

In general the user must be granted a required permission to access a particular entity, if not, then the user is not allowed to finish desired operation.

On the other hand, if an entity requires something from an another entity which is restricted, then such entity could become unmaintainable for the client application, therefore the concept of side loads (a part of the JSON:API concept for the entity api, aka includes) allows returning all referenced entities no matter if the user has read access to that included entity. Such an included entity can’t be manipulated via side loads, just read. Please note this relaxed approach of the including mechanism is a subject of further development and may change in future release.

User cannot define a new relation or change existing one to point to an entity that the user has no access to. The list of includes will contain entities the user has or had an access, or they are required by an application logic (like a parent - child workspace relation).

As an example we can use listing of workspaces. The user is not granted access a parent workspace, the user cannot read its details, neither modify it, nor access it. But when accessing its (child) workspace via the entities api with include parents enabled, the user is able to see the parent’s workspace title, description etc. as it would have read access to the parent workspace entity.

Permissions API

Permissions can be retrieved and set via declarative API only. Permission for logged user can be retrieved via entities api.

Entity API

Payload of each object that contains permission definitions can be expanded by permissions valid for the logged user. When a URI parameter metaInclude=permissions is used, then a list of valid permissions will be put into the section meta for each resource object. For more details about meta section see JSON::API meta.

Example: Retrieve Permissions for the Logged User and the Organization

Make the following API call:

curl -H "Authorization: Bearer <your_bearer_token>" \
  <your_hostname>/api/v1/entities/organization?metaInclude=permissions

To receive something like this:

{
  "data": {
    "attributes": {},
    "id": "...",
    "meta": {
      "permissions": [
        "MANAGE"
      ]
    },
    "type": "organization"
  }
}

URI Mapping

To see where and what permissions are required is documented as a part of the OAPI document, see the API Referece. For each protected endpoint in the sub-section x-gdc-security-info you will find a list of required permissions.