Add capabilities to a role

Learn how to add capabilities to a role

In Vault, the ability of a user to execute a REST API operation or CLI command is determined by the capabilities associated with their role.

This guide shows how to define the capabilities for a role. It illustrates how to give a user their ability to create and view collections, using the CapCollectionsReader and CapCollectionsWriter capabilities, and create and view objects in a collection, using the CapDataReader and CapDataWriter capabilities.

Prerequisites

This guide uses the Dashboard user and the DashboardRole role created in Define users. To exercise the examples you also need an API token for the Dashboard user, the process for obtaining an API token is described in Regenerate user API key. You also need a copy of the IAM configuration file, the step to getting this file is described in Update the IAM configuration.

Walkthrough

You add capabilities to a role like this:

1. In the IAM configuration file, edit the section defining the role, such as [roles.DashboardRole], to add the list of capabilities like this:

   [roles.DashboardRole]
       capabilities = ["CapCollectionsReader", "CapCollectionsWriter", "CapDataReader", "CapDataWriter"]
       policies     = []

2. Apply the IAM configuration to Vault.

The role, DashboardRole, of the user, Dashboard, now has the required capabilities that allow it to create a new collection and delete a new collection. However, to successfully add objects and delete them from the collection, it is not sufficient to have the required capabilities CapDataReader and CapDataWriter.

This is because Vault implements policy management to control access to data in Vault and the role does not have any policies.

Demonstration

To demonstrate this, create a new collection called employees using the user Dashboard like this:

1. Create a file called employees.json containing this text to describe the employees collection:

   {
     "name": "employees",
     "type": "PERSONS",
     "properties": [
       {
         "description": "The email of the employee",
         "name": "email",
         "data_type_name": "EMAIL",
         "is_unique": false,
         "is_index": false,
         "is_encrypted": true,
         "is_nullable": false
       },
       {
         "description": "The age of the employee",
         "name": "age",
         "data_type_name": "INTEGER",
         "is_unique": false,
         "is_index": false,
         "is_encrypted": true,
         "is_nullable": false
       }
     ]
   }

   In this example, the employees collection has only two properties: email and age.

2. Using the CLI, create the collection passing in the collection definition and the API token of the user Dashboard:

   pvault collection add --collection-json @employees.json

3. This succeeds because the Dashboard user has the CapCollectionsWriter capability. You get a response similar to this:

   employees PERSONS (
     age INTEGER COMMENT 'The age of the employee',
     email EMAIL COMMENT 'The email of the employee'
   );

Now, attempt to add an object with the Dashboard user like this:

1. Create a file called object.json and add this text that describes a new object for the employees collection:

   {
     "email": "john@thecompany.com",
     "age": 45
   }

2. Using the CLI, try to add the new object passing in the object definition and the API token of the user Dashboard:

   pvault object add --collection employees --fields @object.json --authtoken APIKEY

3. This operation fails. You see a response similar to this:

   ERR Error code: PV1006, Status code: 403, Message: The operation is forbidden due to a policy access denial., Context: map[username:Dashboard]

To allow the user to add objects to the employees collection, you must define policies that enable that.