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
CapCollectionsWriter capabilities, and create and view objects in a collection, using the
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.
You add capabilities to a role like this:
- In the IAM configuration file, edit the section defining the role, such as
[roles.DashboardRole], to add the list of capabilities like this:
capabilities = ["CapCollectionsReader", "CapCollectionsWriter", "CapDataReader", "CapDataWriter"]
policies = 
- Apply the IAM configuration to Vault.
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
This is because Vault implements policy management to control access to data in Vault and the role does not have any policies.
To demonstrate this, create a new collection called
employees using the user
Dashboard like this:
Create a file called
employees.jsoncontaining this text to describe the employees collection:
"description": "The email of the employee",
"description": "The age of the employee",
In this example, the
employeescollection has only two properties:
Using the CLI, create the collection passing in the collection definition and the API token of the user
pvault collection add --collection-json @employees.json
This succeeds because the
Dashboarduser has the
CapCollectionsWritercapability. 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:
Create a file called
object.jsonand add this text that describes a new object for the
Using the CLI, try to add the new object passing in the object definition and the API token of the user
pvault object add --collection employees --fields @object.json --authtoken APIKEY
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 violation., Context: map[username:Dashboard]
To allow the user to add objects to the employees collection, you must define policies that enable that.