Manage Permissions

This article explains how to define a permissions to control user 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 user groups and assign permissions to these groups that are appropriate for the use case those users will face.

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

Assigning Permissions

To give users specific permissions, you assign them specific permissions on the level of individual objects. Permissions definition takes the following form:

{
  "<object>" : {
    ...,
    "<permissions_definition>": [
      {
        "assignee": {
            "id": "<userName_or_userGroupName>",
            "type": "<user_or_userGroup>"
        },
        "name": "<permission_type>"
      }
    ]
  }
}

<object>

An object is an instance of one of the following API layouts:

  • organization layout accessible via /api/v1/layout/organization
  • dataSources layout accessible via /api/v1/layout/dataSources
  • workspaces layout accessible via /api/v1/layout/workspaces
  • dashboards layout accessible via /api/v1/layout/workspaces

The object holds a permissions definition and this is where the relationship between the object, permissions and its assignees is defined.

“assignee”

An assignee is a particular instance of a user or a user group. In the permissions definition the assignee is defined using its identifier and type.

“name”

A permission is recognized by its name within the permissions definition. In the application it maps to a set of actions that are restricted and unavailable to non-privileged users. The set of actions is not necessarily limited only to the specific object, it is spread out through the permissions hierarchy to actions of other objects as well.

Depending on the type of object, the permission name can be one or more of the following:

  • MANAGE
  • VIEW
  • ANALYZE
  • USE
  • SHARE
  • EDIT

Refer to articles nested under this article, these articles describe the types of permissions that are available for each type of object and what exactly the permissions allow the user to do.

<permissions_definition>

The type of permissions you want to assign to users. Usually this is just permissions, but in case of workspaces, you can also use the hierarchyPermissions definition. See Manage Workspace Permissions .

Example

In practice the permissions definition inside, for example, the data sources object, might look something like this:

{
    "dataSources": [
        {
        ...,            
        "permissions": [
            {
                "assignee": {
                    "id": "admins",
                    "type": "userGroup"
                },
                "name": "MANAGE"
            },
            {
                "assignee": {
                    "id": "john_smith",
                    "type": "user"
                },
                "name": "USE"
            }
        ],
        ...
        }
    ]
}

In the above example, there are two permissions defined:

  • Everyone who is part of the admins user group is allowed to view and alter data sources.
  • The user john_smith is only allowed to list data source identifiers.

Note that in the above example, the data sources object can also be viewed and altered by anyone who has the MANAGE permission assigned to them inside the organization object. This is because the organization object is above the data sources object in the permissions hierarchy.

Permissions Hierarchy

Permissions obey an object hierarchy. If a user is assigned a permission inside an object, the user will also get the same level of access to objects that are lower in the object hierarchy.

The object hierarchy for permissions is as follows:

graph BT
    id1[dataSources] --> organization
    id2["workspace"] --> organization
    id3["child workspace <br> (only if user is assigned a 'hierarchyPermissions' <br> in the parent workspace)"] --> id2

For example if a user has been assigned to MANAGE permission in the organization, the user also has MANAGE permission in all dataSources and workspace objects that are nested under the organization, even if the user has not been explicitly assigned to a MANAGE permission definition in each of the nested objects.

Automatic Entity Filtering

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 only see entities to which they have been assigned at least a read-level 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 the desired operation.

On the other hand, sometimes an entity requires data from an another entity which may be restricted. In such cases we make use of sideloads that allow returning all referenced entities no matter if the user has permission to read the sideloaded (aka included) entity. Included entities cannot be changed using sideloads, they can only be read. Please note that 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 to the parent workspace, the user cannot read its details, modify it, or access it. But when accessing the 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 $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X GET \
  $HOST_URL/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.