Manage roles programmatically

What are custom roles?

Custom roles allow the administrator to restrict access of users to certain resources. Roles follow a whitelisting approach, wherein everything that a user is allowed to do, needs to be explicitly defined.

Along with a name and description, a role contains, permissions and policies. Permissions are basic rules that define whether (or not) a user can access content types, settings, and entries. It can be specified if a user can read and/or manage those.

On the other hand, there are policies that are used to allow or deny access to resources in a very fine-grained fashion. For example, with policies it is possible to limit read access to only entries of a specific content type or write access to only certain parts of an entry (e.g. for a specific locale).

Create a role

Endpoint: [POST] /spaces/{{ spaceId }}/roles

Base URL: https://api.contentful.com

Description: This endpoint is used to create a custom role.

Response:

1
{
2
  "sys": {
3
    "type": "Role",
4
    "id": "0xvkNW6WdQ8JkWlWZ8BC4x",
5
    "version": 0,
6
    "createdAt": "2015-05-18T11:29:46.809Z",
7
    "createdBy": {
8
      "sys": {
9
        "type": "Link",
10
        "linkType": "User",
11
        "id": "7BslKh9TdKGOK41VmLDjFZ"
12
      }
13
    },
14
    "updatedAt": "2015-05-18T11:29:46.809Z",
15
    "updatedBy": {
16
      "sys": {
17
        "type": "Link",
18
        "linkType": "User",
19
        "id": "4FLrUHftHW3v2BLi9fzfjU"
20
      }
21
    }
22
  },
23
  "name": "Some role",
24
  "description": "Test role",
25
  "permissions": {
26
    "ContentModel": [
27
      "read"
28
    ],
29
    "Settings": "all",
30
    "ContentDelivery": "all",
31
    "Environments": "all",
32
    "EnvironmentAliases": "all",
33
    "Tags": "all"
34
  },
35
  "policies": [
36
    {
37
      "effect": "allow",
38
      "actions": [
39
        "read",
40
        "create",
41
        "update",
42
        "delete",
43
        "publish",
44
        "unpublish",
45
        "archive",
46
        "unarchive"
47
      ],
48
      "constraint": {
49
        "or": [
50
          {
51
            "equals": [
52
              {
53
                "doc": "sys.type"
54
              },
55
              "Entry"
56
            ]
57
          },
58
          {
59
            "equals": [
60
              { 
61
                "doc": "sys.type" 
62
              },
63
              "Asset"
64
            ]
65
          }
66
        ]
67
      }
68
    },
69
    {
70
      "effect": "allow",
71
      "actions": ["access"],
72
      "constraint": {
73
        "and": [
74
          {
75
            "equals": [
76
              { "doc": "sys.type" },
77
               "Environment"
78
              ],
79
          },
80
          {
81
            "equals": [
82
              { "doc": "sys.id" },
83
               "master"
84
              ],
85
          },
86
        ],
87
      },
88
    },
89
  ]
90
}

To enable all the permissions pertaining to a role, use the “all” keyword. It enables all possible values for the respective permission.

1
{
2
  "name": "Name of the role",
3
  "description": "Description of the role",
4
  "permissions": {
5
    "ContentDelivery": "all",
6
    "ContentModel": "all",
7
    "Settings": "all"
8
  },
9
  "policies": [
10
    {"effect": "allow", "actions": "all"}
11
  ]
12
}

Instead of “all”, it is possible to define an array of allowed actions, thereby providing partial access to the system.

1
{
2
  "name": "Name of the role",
3
  "description": "Description of the role",
4
  "permissions": {
5
    "ContentDelivery": [
6
      "read", // Allows reading of api keys
7
      "manage" // Allows creation/deletion of api keys
8
    ],
9
    "ContentModel": [
10
      "read", // Allows reading of content types. Note that you cannot read entries without reading content types.
11
      "manage" // Allows creation/manipulation/deletion of content types
12
    ],
13
    "Settings": [
14
      "manage" // Allows full access to the settings section in the web UI
15
    ]
16
  },
17
  "policies": [
18
    {"effect": "allow", "actions": "all"}
19
  ]
20
}

Accessible environments can also be set via policies. In order for them to take effect, the Environments permission must not be set to “all”. In cases where multiple roles are assigned to a user, this applies to each of the user’s roles. More details on this can be found under managing access to environments

1
{
2
  "name": "Name of the role",
3
  "description": "Description of the role",
4
  "permissions": {
5
    "ContentDelivery": "all",
6
    "ContentModel": "all",
7
    "Settings": "all",
8
    "Environments":"[]"
9
  },
10
  "policies": [
11
    {
12
      "effect": "allow",
13
      "actions": ["access"],
14
      "constraint": {
15
        "and": [
16
          {
17
            "equals": [
18
              { "doc": "sys.type" },
19
               "Environment"
20
              ],
21
          },
22
          {
23
            "equals": [
24
              { "doc": "sys.id" },
25
               "qa" // This will enable access to the qa environment
26
              ],
27
          },
28
        ],
29
      },
30
    },
31
  ]
32
}

Constraints

Constraints are fine-grained and content-focused access rules defined with the role’s policies. For example,

1
{
2
  "name": "Name of the role",
3
  "description": "Description of the role",
4
  "permissions": { "ContentDelivery": "all", "ContentModel": "all", "Settings": "all" },
5
  "policies": [
6
    {
7
      "effect": "allow", // With "allow" we are enabling a user to do certain things. With "deny" we take away what we previously allowed
8
      "actions": "all"   // The keyword "all" is an alias for ['read', 'create', 'update', 'delete', 'archive', 'unarchive', 'publish', 'unpublish'],
9
      "constraint": {
10
        // A constraint can be defined to restrict the effect and the actions to a subset of entities and assets
11
        <ConstraintKeyword>: <ConstraintValues>
12
      }
13
    }
14
  ]
15
}

A constraint is made of a keyword and the values that keyword requires. Some keywords accept constraints as values, allowing nested constraints. Supported keywords are equals, and, or, not, in, all, range, paths. You can specify nested constraints for and, or, not. The paths constraint specifies which content paths can be modified and is only used for the update action. The list operators in, all only work for content paths that contain lists. The following table show usage of the supported constraints:

{ “equals”: [{ “doc”: “sys.type” }, “Asset”] }

{ 
 “and”: [
   { “equals”: [{ “doc”: “sys.type” }, “Entry”] },
   { “equals”: [{ “doc”: “sys.contentType.sys.id” },
    “content-type-id”] } 
  ] 
}

{
 “and”:[
   { “equals”: [{ “doc”: “sys.type” }, “Entry”] },
   { “not”: { “equals”: [{ “doc”: “sys.contentType.sys.id” },
     “content-type-id”] } }
   ]
}

{
 “or”: [
  {“and”: [
   { “equals”: [{ “doc”: “sys.type” }, “Entry”] },
   { “not”: { “equals”: [{ “doc”: “sys.contentType.sys.id” },
    “content-type-id”] } }
   ]},
   { “equals”: [{ “doc”: “sys.type” }, “Asset”] }
 ]
}

{ “all”: [{ “doc”: “metadata.tags.sys.id” }, 
 [“tagA”, “tagB”] }

{ “in”: [{ “doc”: “metadata.tags.sys.id” }, 
 [“tagA”, “tagB”] }

{ range: [{ doc: ‘fields.total.en-US’ }, { gte: 2 }] }

{ range: [{ doc: ‘fields.pi.en-US’ }, { gt: 3, lt: 4 }] }

{ paths: [
 { doc: ‘fields.total.en-US’ },
 { doc: ‘metadata.%’ },
 { doc: ‘fields.%.de-DE’ },
 { doc: ‘fields.pi.%’ }
] }

Important notes about roles and constraints

• Whenever content is accessed or searched for, read policies must be satisfied. Policies with complex constraints could slow down access to content.

• There are no paths constraints for the create action so users that can create content can always create content with values for any path.

• If a content path is missing, the constraint will not be satisfied. If the constraint is nested, other constraints may still be satisfied. For instance, if one or constraint references a missing content path but the other or constraint is satisfied, then the entire or constraint is satisfied.

Important notes about combining roles

• Policies are global. Allow policies expand the set of possible actions a user can perform. Deny policies reduce that set. Each Allow policy has its set of actions reduced by every Deny policy. If the user is assigned multiple roles, the Deny policies from each role will reduce the Allow policy actions on all of the roles. This can lead to unexpected results depending on how the policies are constructed. If one role grants access to all actions with an Allow rule and denies access to half of those actions with a Deny rule, and another role grants access to all actions with an Allow rule and denies access to a different half of those actions with a Deny rule, then the combination of the two roles result in no access at all. Because the Deny rules are global and each denies a different half of all actions, they combine to deny everything. If instead one role had an Allow rule that granted access to half of all actions, and the other role granted access to a different half of all actions, then the combination of those two roles would lead to complete access.

• Since policies are global, environment-related access is combined in a similar way: if a user has multiple roles, all Allow and Deny policies are applied to all selected environments across roles. For example: if role A restricts environment A to a set of content policies A, and role B restricts environment B to a set of content policies B, a user with both roles A and B has access to environments A and B, and both of these environments have the content policies A and B applied. More details on this can be found under assigning multiple environment access options to a single user.

• Environment permissions override environment policies. For environment-related policies (aka selecting which environments a role has access to) to take effect, the Environments permission must not be set to “all”, as it overrides the respective environment-related policies. As a result of the permission being set to “true”, a user has CRUD access to all content in all environments, and all content-related policies are applied only in the master environment. More details on this can be found under managing access to environments.

Update a role

Endpoint: PUT /spaces/{{ spaceId }}/roles/{{ roleId }}

Base URL: https://api.contentful.com

Description: This endpoint is used to update an existing custom role. This endpoint can also be used to create a new role with a specific id.

Response:

1
{
2
  "sys":{
3
    "type":"Role",
4
    "id":"48x6PYyasXaAuN3kQgposV",
5
    "version":0,
6
    "space":{
7
      "sys":{
8
        "type":"Link",
9
        "linkType":"Space",
10
        "id":"296guvxfpn71"
11
      }
12
    },
13
    "createdBy":{...},
14
    "createdAt":"2013-07-04T13:06:57Z",
15
    "updatedBy":{...},
16
    "updatedAt":"2013-07-04T13:06:57Z"
17
  },
18
  "name":"Editor",
19
  "description":"Allows editing of all Entries",
20
  "policies":[
21
    {
22
      "effect":"allow",
23
      "actions":"all"
24
    }
25
  ],
26
  "permissions":{
27
    "ContentModel":[
28
      "read"
29
    ],
30
    "Settings":[],
31
    "ContentDelivery":[]
32
  }
33
}

It is possible to apply the constraints while updating a role.

Delete a role

Endpoint: PUT /spaces/{{ spaceId }}/roles/{{ roleId }}

Base URL: https://api.contentful.com

Description: This endpoint is used to delete an existing custom role. It is not possible to delete a role, if the user corresponding to this role does not have any other assigned roles.

Response: The server responds with a http code ‘204’ in case of successful deletion of the role. If the user is assigned only with the role that is to deleted, the server responds with a http code ‘412’.

Next steps

• The Content Management API reference guide for more technical details.