Control groups

30min
|
Enterprise
Vault

Enterprise only

Control groups require a Vault Enterprise Plus license or HCP Vault Dedicated plus tier cluster.

Control groups add additional authorization factors to be required before processing requests to increase the governance, accountability, and security of your secrets. When a control group is required for a request, the requesting client receives the wrapping token in return. Only when all authorizations are satisfied, the wrapping token can be used to unwrap the requested secrets.

Challenge

In order to operate in EU, a company must abide by the General Data Protection Regulation (GDPR) as of May 2018. The regulation enforces two or more controllers jointly determine the purposes and means of processing (Chapter 4: Controller and Processor).

Consider the following scenarios:

Anytime an authorized user requests to read data at "EU_GDPR_data/data/orders/*", at least two people from the Security group must approve to ensure that the user has a valid business reason for requesting the data.
Anytime a database configuration is updated, it requires that one person from the DBA and one person from Security group must approve it.

Solution

Use Control groups in your policies to implement dual controller authorization required.

Prerequisites

To perform the tasks described in this tutorial, you need to have the following:

A Vault Enterprise environment or an HCP Vault Dedicated plus tier cluster.
jq installed to process the JSON output for readability.

This tutorial assumes that you have some hands-on experience with ACL policies as well as Identities. If you are not familiar, go through the following guides first:

Policy requirements

Since this tutorial demonstrates the creation of policies, log in with a highly privileged token such as root. Otherwise, required permissions to perform the steps in this tutorial are listed below.

Policy requirements

# Create and manage ACL policies
path "sys/policies/acl/*"
{
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

# To enable secrets engines
path "sys/mounts/*" {
  capabilities = [ "create", "read", "update", "delete" ]
}

# Setting up test data
path "EU_GDPR_data/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Manage userpass auth method
path "auth/userpass/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# List, create, update, and delete auth methods
path "sys/auth/*"
{
  capabilities = ["create", "read", "update", "delete"]
}

# Create and manage entities and groups
path "identity/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

Scenario introduction

The scenario in this tutorial is that a user, Bob Smith has read-only permission on the "EU_GDPR_data/data/orders/*" path; however, someone in the acct_manager group must approve it before he can actually read the data.

As a member of the acct_manager group, Ellen Wright can authorize Bob's request.

Personas:

admin with privileged permissions to create policies and identities
processor with limited permission to access secrets
controller with permission to approve secret access

Scenario workflow

You are going to perform the following:

If you want to implement control groups in Sentinel, read the ACL Policies vs. Sentinel Policies section.

Lab setup

Download the latest version of the Vault Enterprise binary.
Extract the Vault binary where x.x.x is the actual version number.
```
$ unzip vault_x.x.x+ent.zip
```
Open a terminal and export an environment variable for the Vault Enterprise license generated by the sign up process.
```
$ export VAULT_LICENSE=<actual-license-key>
```
From the directory you extracted the Vault Enterprise binary, start a Vault dev server with root as the root token.
```
$ ./vault server -dev -dev-root-token-id root
```
The Vault dev server defaults to running at 127.0.0.1:8200. The server is also initialized and unsealed.
Insecure operation
Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.
Open a new terminal and export an environment variable with the Vault server address.
```
$ export VAULT_ADDR=http://127.0.0.1:8200
```
Export an environment variable with the Vault token.
```
$ export VAULT_TOKEN=root
```

Verify the Vault server started successfully with the trial license.

$ vault read sys/license/status

WARNING! The following warnings were returned from Vault:

* time left on license is 703h42m22s

Key                   Value
---                   -----
autoloaded            map[expiration_time:2022-06-16T21:03:20Z features:...snip...]
autoloading_used      true
persisted_autoload    map[expiration_time:2022-06-16T21:03:20Z features:...snip...]

The Vault server is ready.

Note

You must use a HCP Vault Dedicated plus-tier cluster to complete this tutorial. Visit the Create a Vault Cluster on HCP tutorial for the steps to create a cluster.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copied address.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft
...snipped...

The Vault Dedicated server is ready.

Implement a control group

(Persona: admin)

Create a policy file named read-gdpr-order.hcl.

$ tee read-gdpr-order.hcl <<EOF
path "EU_GDPR_data/data/orders/*" {
  capabilities = [ "read" ]

  control_group = {
    factor "authorizer" {
      identity {
        group_names = [ "acct_manager" ]
        approvals = 1
      }
    }
  }
}
EOF

Examine the policy

The condition is that Bob can read the secrets at EU_GDPR_data/data/orders/* if someone from the acct_manager group approves.

read-gdpr-order.hcl

1 2 3 4 5 6 7 8 9 101112path "EU_GDPR_data/data/orders/*" {
  capabilities = [ "read" ]

  control_group = {
    factor "authorizer" {
      identity {
        group_names = [ "acct_manager" ]
        approvals = 1
      }
    }
  }
}

For the purpose of this tutorial, the number of approvals is set to 1 to keep it simple and easy to test. Any member of the identity group, acct_manager can approve the read request. Although this example has only one factor (authorizer), you can add as many factor blocks as you need.

Create another policy file named, acct_manager.hcl. This is the policy needed for the member of controller (acct_manager) to approve Bob's request.
```
$ tee acct_manager.hcl <<EOF
# To approve the request
path "sys/control-group/authorize" {
    capabilities = ["create", "update"]
}

# To check control group request status
path "sys/control-group/request" {
    capabilities = ["create", "update"]
}
EOF
```
The important thing here is that the authorizer must have create and update permission on the sys/control-group/authorize endpoint so that they can approve the request.

Deploy the policies

(Persona: admin)

Deploy the read-gdpr-order and acct_manager policies that you wrote.

Create a new policy named read-gdpr-order.

$ vault policy write read-gdpr-order read-gdpr-order.hcl

Success! Uploaded policy: read-gdpr-order

Create a new policy named acct_manager.

$ vault policy write acct_manager acct_manager.hcl

Success! Uploaded policy: acct_manager

Create an API request payload containing the read-gdpr-read policy.

$ tee payload-1.json <<EOF
{
  "policy": "path \"EU_GDPR_data/data/orders/*\" {\n  capabilities = [ \"read\" ]\n\n  control_group = {\n    factor \"authorizer\" {\n        identity {\n            group_names = [ \"acct_manager\" ]\n            approvals = 1\n        }\n    }\n  }\n}"
}
EOF

Create a new policy named read-gdpr-order.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request PUT \
       --data @payload-1.json \
       $VAULT_ADDR/v1/sys/policies/acl/read-gdpr-order

Construct API request payload containing acct_manager policy.

$ tee payload-2.json <<EOF
{
 "policy": "# To approve the request\npath \"sys/control-group/authorize\" {\n    capabilities = [\"create\", \"update\"]\n}\n\n# To check control group request status\npath \"sys/control-group/request\" {\n    capabilities = [\"create\", \"update\"]\n}"
}
EOF

Create a new policy named acct_manager.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
      --request PUT \
      --data @payload-2.json \
      $VAULT_ADDR/v1/sys/policies/acl/acct_manager

Create an API request payload containing the read-gdpr-read policy.

$ tee payload-1.json <<EOF
{
  "policy": "path \"EU_GDPR_data/data/orders/*\" {\n  capabilities = [ \"read\" ]\n\n  control_group = {\n    factor \"authorizer\" {\n        identity {\n            group_names = [ \"acct_manager\" ]\n            approvals = 1\n        }\n    }\n  }\n}"
}
EOF

Create a new policy named read-gdpr-order.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request PUT \
    --data @payload-1.json \
    $VAULT_ADDR/v1/sys/policies/acl/read-gdpr-order

Construct API request payload containing acct_manager policy.

$ tee payload-2.json <<EOF
{
 "policy": "# To approve the request\npath \"sys/control-group/authorize\" {\n    capabilities = [\"create\", \"update\"]\n}\n\n# To check control group request status\npath \"sys/control-group/request\" {\n    capabilities = [\"create\", \"update\"]\n}"
}
EOF

Create a new policy named acct_manager.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request PUT \
    --data @payload-2.json \
    $VAULT_ADDR/v1/sys/policies/acl/acct_manager

Open a web browser, navigate to the Vault UI and login.
Click the Policies menu, and then click Create ACL policy.
Toggle Upload file, and click Choose a file to select the read-gdpr-order.hcl file authored in the Implement a control group section. This loads the policy and sets the Name to read-gdpr-order.
Note
If you do not see the Upload file switch, drag the scroll bar under Policy to the right.
Click Create Policy.
Repeat the steps above to create a policy using the acct_manager.hcl file.
Click the Back to main navigation menu.

Setup entities and a group

(Persona: admin)

This step only demonstrates CLI commands and Web UI to create entities and groups. Refer to the Identity - Entities and Groups tutorial if you need the full details.

Now that you have policies created, create a user bob, and an acct_manager group with ellen as a group member.

Note

For the purpose of this tutorial, use the userpass auth method to create user bob and ellen so that the scenario can be easily tested.

Enable the userpass auth method.

$ vault auth enable userpass

Success! Enabled userpass auth method at: userpass/

Create a new user, bob with password, "training".

$ vault write auth/userpass/users/bob password="training"

Success! Data written to: auth/userpass/users/bob

Create a new user, ellen with password, "training".

$ vault write auth/userpass/users/ellen password="training"

Success! Data written to: auth/userpass/users/ellen

Retrieve the userpass mount accessor and save it in a file named accessor.txt.

$ vault auth list -format=json | jq -r '.["userpass/"].accessor' > accessor.txt

Create Bob Smith entity and save the identity ID in the entity_id_bob.txt.

$ vault write -format=json identity/entity name="Bob Smith" \
        policies="read-gdpr-order" \
        metadata=team="Processor" \
        | jq -r ".data.id" > entity_id_bob.txt

Add an entity alias for the Bob Smith entity.

$ vault write identity/entity-alias name="bob" \
      canonical_id=$(cat entity_id_bob.txt) \
      mount_accessor=$(cat accessor.txt)

Example output:

Key             Value
---             -----
canonical_id    e57d0eff-ca1d-d4d8-b7b7-2b3f842b811d
id              09bdc8af-9bb2-950d-ac63-cfb96fce4d77

Create Ellen Wright entity and save the identity ID in the entity_id_ellen.txt.

$ vault write -format=json identity/entity name="Ellen Wright" \
        policies="default" \
        metadata=team="Acct Controller" \
        | jq -r ".data.id" > entity_id_ellen.txt

Add an entity alias for the Ellen Wright entity.

$ vault write identity/entity-alias name="ellen" \
      canonical_id=$(cat entity_id_ellen.txt) \
      mount_accessor=$(cat accessor.txt)

Example output:

Key             Value
---             -----
canonical_id    78762f37-a651-229d-6db3-a25cbb71070f
id              94499a59-5890-9aef-3810-37ffdc6b7511

Create acct_manager group and add Ellen Wright entity as a member.

$ vault write identity/group name="acct_manager" \
      policies="acct_manager" \
      member_entity_ids=$(cat entity_id_ellen.txt)

Example output:

Key     Value
---     -----
id      898f0f44-e2c1-efcf-7a55-2c1c6c4bf1ae
name    acct_manager

Click the Access menu, and click Enable new method.
Select Username & Password and click Next.
Leave all default settings and click Enable Method.
Click < userpass to return to the main page.
Click Create user.
Enter bob in the Username field, and training in the Password field.
Click Save.
Click Create user again.
Enter ellen in the Username field, and training in the Password field.
Click Save.
Click the Entities menu and then click Create entity.
Enter the following data:
- Name: Bob Smith
- Policies: read-gdpr-order
- Metadata: key=team, vaule=Processor
Click Create.
Click Add alias.
Enter bob in the Name field and select userpass/ (userpass) from the Auth Backend drop-down list.
Click Create.
Click the Entities menu and then click Create entity.
Enter the following data:
- Name: Ellen Wright
- Policies: acct_manager
- Metadata: key=team, vaule=Acct Controller
Click Create.
Select Create alias.
Enter ellen in the Name field and select userpass/ (userpass) from the Auth Backend drop-down list.
Click Create.
Click Groups from the left navigation, and click Create group.
Enter acct_manager in the Name field, and enter acct_manager again in the Policies field.
In the Member Entity IDs field, select Ellen Wright and then click Create.
Click the Back to main navigation menu.

Test the control group

(Persona: admin)

Validate the control groups work by request a secret as Bob and approving the request as Ellen.

Enable the key/value secrets engine at EU_GDPR_data.

$ vault secrets enable -path=EU_GDPR_data -version=2 kv

Success! Enabled the kv secrets engine at: EU_GDPR_data/

Write some mock data.

$ vault kv put EU_GDPR_data/orders/acct1 \
        order_number="12345678" product_id="987654321"

Example output:

========= Secret Path =========
EU_GDPR_data/data/orders/acct1

======= Metadata =======
Key                Value
---                -----
created_time       2022-05-18T19:11:20.105114Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

(Persona: processor)

Unset the root Vault token.
```
$ unset VAULT_TOKEN
```

$ vault login -method=userpass username="bob" password="training"

Request to read "EU_GDPR_data/orders/acct1".

$ vault kv get EU_GDPR_data/orders/acct1

Example output:

Key                              Value
---                              -----
wrapping_token:                  hvs.AmhW6ULQ7Eoy6o5JMHr679Z0
wrapping_accessor:               Vbs3d5FGbeox1mjYOgLWvXsP
wrapping_token_ttl:              24h
wrapping_token_creation_time:    2021-07-21 19:42:35 -0700 PDT
wrapping_token_creation_path:    EU_GDPR_data/data/orders/acct1

The response includes wrapping_token and wrapping_accessor. Export their values as environment variables for use in later steps.

Note

Be sure to replace the example wrapping_token and wrapping_accessor values with your actual values.

Export the wrapping token value as WRAPPING_TOKEN.
```
$ export WRAPPING_TOKEN=<wrapping_token>
```

Export the wrapping token accessor as WRAPPING_ACCESSOR.

$ export WRAPPING_ACCESSOR=<wrapping_accessor>

Example:

$ export WRAPPING_TOKEN=hvs.AmhW6ULQ7Eoy6o5JMHr679Z0
$ export WRAPPING_ACCESSOR=Vbs3d5FGbeox1mjYOgLWvXsP

(Persona: controller)

A user who is a member of the acct_manager group can check and authorize Bob's request using the request and authorize commands.

$ vault login -method=userpass username="ellen" password="training"

Check the current status.

$ vault write sys/control-group/request accessor=$WRAPPING_ACCESSOR

Key               Value
---               -----
approved          false
authorizations    <nil>
request_entity    map[name:Bob Smith id:38700386-723d-3d65-43b7-4fb44d7e6c30]
request_path      EU_GDPR_data/orders/acct1

The approved status is currently false since it has not been approved.

Approve the request.

$ vault write sys/control-group/authorize accessor=$WRAPPING_ACCESSOR

Key         Value
---         -----
approved    true

Now, the approved status is true.

(Persona: processor)

Since the control group requires one approval from a member of acct_manager group, the condition has been met. Log back in as bob and unwrap the secret.

Log back in as bob using the userpass auth method.

$ vault login -method=userpass username="bob" password="training"

Unwrap the secrets by passing the $WRAPPING_TOKEN environment variable.

$ vault unwrap $WRAPPING_TOKEN

Key         Value
---         -----
data        map[order_number:12345678 product_id:987654321]
metadata    map[created_time:2021-03-24T16:25:20.405776245Z deletion_time: destroyed:false version:1]

(Persona: admin)

Create an API request payload to enable the KV v2 secrets engine.

$ tee payload.json <<EOF
{
  "type": "kv",
  "options": {
      "version": "2"
  }
}
EOF

Enable K/V v2 at EU_GDPR_data.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/EU_GDPR_data

Create an API request payload containing some mock data.

$ tee test_data.json <<EOF
{
  "data": {
    "order_number": "12345678",
    "product_id": "987654321"
  }
}
EOF

Write the mock data at EU_GDPR_data/data/orders/acct1.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @test_data.json \
   $VAULT_ADDR/v1/EU_GDPR_data/data/orders/acct1 | jq -r ".data"

Example output:

{
  "created_time": "2021-07-22T23:23:14.372042Z",
  "custom_metadata": null,
  "deletion_time": "",
  "destroyed": false,
  "version": 1
}

(Persona: processor)

Unset the VAULT_TOKEN environment variable.
```
$ unset VAULT_TOKEN
```

$ curl --request POST \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth.client_token" > bob_client_token.txt

Request to read secrets at EU_GDPR_data/data/orders/acct1.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
   $VAULT_ADDR/v1/EU_GDPR_data/data/orders/acct1 | jq -r ".wrap_info"

Example output:

{
  "token": "hvs.qPTj8ugkDkmTuF1yfDoYaIM4",
  "accessor": "CcPrwPp93Y3MM6YD9BBiowQy",
  "ttl": 86400,
  "creation_time": "2021-07-22T16:38:26-07:00",
  "creation_path": "EU_GDPR_data/data/orders/acct1"
}

The response includes token and accessor instead of the secret values.

Export the wrapping token value as WRAPPING_TOKEN.
```
$ export WRAPPING_TOKEN=<token>
```

Export the wrapping token accessor as WRAPPING_ACCESSOR.

$ export WRAPPING_ACCESSOR=<accessor>

Example:

$ export WRAPPING_TOKEN=hvs.qPTj8ugkDkmTuF1yfDoYaIM4
$ export WRAPPING_ACCESSOR=CcPrwPp93Y3MM6YD9BBiowQy

(Persona: controller)

A member of acct_manager must approve this request. Log in as ellen who is a member of acct_manager group and store the token.

$ curl --request POST --silent \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/ellen | jq -r ".auth.client_token" > ellen_client_token.txt

As a user, ellen, you can check the current status and then authorize bob's request using the sys/control-group/request endpoint.

$ curl --header "X-Vault-Token: $(cat ellen_client_token.txt)" \
   --request POST \
   --data '{"accessor": "'"$WRAPPING_ACCESSOR"'"}' \
   $VAULT_ADDR/v1/sys/control-group/request | jq -r ".data"

Example output:

{
  "approved": false,
  "authorizations": null,
  "request_entity": {
    "id": "e57d0eff-ca1d-d4d8-b7b7-2b3f842b811d",
    "name": "Bob Smith"
  },
  "request_path": "EU_GDPR_data/data/orders/acct1"
}

Authorize the request using sys/control-group/authorize endpoint.

$ curl --header "X-Vault-Token: $(cat ellen_client_token.txt)" \
     --request POST \
     --data '{"accessor": "'"$WRAPPING_ACCESSOR"'"}' \
     $VAULT_ADDR/v1/sys/control-group/authorize | jq -r ".data"

Example output:

{
  "approved": true
}

Now, the approved status is true.

(Persona: processor)

The bob user should be able to unwrap the secrets.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
   --request POST \
   --data '{"token": "'"$WRAPPING_TOKEN"'"}' \
   $VAULT_ADDR/v1/sys/wrapping/unwrap | jq -r ".data"

Example output:

{
  "order_number": "12345678",
  "product_id": "987654321"
}

(Persona: admin)

Create an API request payload to enable the KV v2 secrets engine.

$ tee payload.json <<EOF
{
  "type": "kv",
  "options": {
      "version": "2"
  }
}
EOF

Enable K/V v2 at EU_GDPR_data.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data @payload.json \
    $VAULT_ADDR/v1/sys/mounts/EU_GDPR_data

Create an API request payload containing some mock data.

$ tee test_data.json <<EOF
{
  "data": {
    "order_number": "12345678",
    "product_id": "987654321"
  }
}
EOF

Write the mock data at EU_GDPR_data/data/orders/acct1.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data @test_data.json \
    $VAULT_ADDR/v1/EU_GDPR_data/data/orders/acct1 | jq -r ".data"

Example output:

{
  "created_time": "2021-07-22T23:23:14.372042Z",
  "custom_metadata": null,
  "deletion_time": "",
  "destroyed": false,
  "version": 1
}

(Persona: processor)

Unset the VAULT_TOKEN environment variable.
```
$ unset VAULT_TOKEN
```

$ curl --request POST \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth.client_token" > bob_client_token.txt

Request to read secrets at EU_GDPR_data/data/orders/acct1.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    $VAULT_ADDR/v1/EU_GDPR_data/data/orders/acct1 | jq -r ".wrap_info"

Example output:

{
  "token": "hvs.qPTj8ugkDkmTuF1yfDoYaIM4",
  "accessor": "CcPrwPp93Y3MM6YD9BBiowQy",
  "ttl": 86400,
  "creation_time": "2021-07-22T16:38:26-07:00",
  "creation_path": "EU_GDPR_data/data/orders/acct1"
}

The response includes token and accessor instead of the secret values.

Export the wrapping token value as WRAPPING_TOKEN.
```
$ export WRAPPING_TOKEN=<token>
```

Export the wrapping token accessor as WRAPPING_ACCESSOR.

$ export WRAPPING_ACCESSOR=<accessor>

Example:

$ export WRAPPING_TOKEN=hvs.qPTj8ugkDkmTuF1yfDoYaIM4
$ export WRAPPING_ACCESSOR=CcPrwPp93Y3MM6YD9BBiowQy

(Persona: controller)

A member of acct_manager must approve this request. Log in as ellen who is a member of acct_manager group and store the token.

$ curl --request POST --silent \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/ellen | jq -r ".auth.client_token" > ellen_client_token.txt

As a user, ellen, you can check the current status and then authorize bob's request using the sys/control-group/request endpoint.

$ curl --header "X-Vault-Token: $(cat ellen_client_token.txt)" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"accessor": "'"$WRAPPING_ACCESSOR"'"}' \
   $VAULT_ADDR/v1/sys/control-group/request | jq -r ".data"

Example output:

{
  "approved": false,
  "authorizations": null,
  "request_entity": {
    "id": "e57d0eff-ca1d-d4d8-b7b7-2b3f842b811d",
    "name": "Bob Smith"
  },
  "request_path": "EU_GDPR_data/data/orders/acct1"
}

Authorize the request using sys/control-group/authorize endpoint.

$ curl --header "X-Vault-Token: $(cat ellen_client_token.txt)" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{"accessor": "'"$WRAPPING_ACCESSOR"'"}' \
     $VAULT_ADDR/v1/sys/control-group/authorize | jq -r ".data"

Example output:

{
  "approved": true
}

Now, the approved status is true.

(Persona: processor)

The bob user should be able to unwrap the secrets.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"token": "'"$WRAPPING_TOKEN"'"}' \
   $VAULT_ADDR/v1/sys/wrapping/unwrap | jq -r ".data"

Example output:

{
  "order_number": "12345678",
  "product_id": "987654321"
}

Click Secrets Engines and click Enable new engine.
Select KV from the list, and then click Next.
Enter EU_GDPR_data in the Path field.
Expand Method options and verify the Version is set to 2.
Click Enable Engine.
Note
If you receive the error Waiting for the primary to upgrade from non-versioned to versioned data, wait a moment and refresh the page.
Click Create secret.
Enter orders/acct1 in the Path for this secret field.
Under Secret data, enter order_number in the key field and set its value to 12345678.
Click Add, enter product_id in the new key field and set its value to 987654321.
Click Save.
Sign out of the Vault UI.

(Persona: processor)

From the Sign in to Vault page, select Username from the Method drop-down list.
Enter bob in the Username field and training in the Password field.
Click Sign in.
Under Secrets engines click EU_GDPR_data.
In the View secret textbox enter orders/acct1 and click View secret.
Copy the Accessor and token values. Save them in a text editor. You will need these values in the next step.
Sign out of the UI.

(Persona: controller)

Sign in with username ellen and password training.
Click the Access menu, and then Control Groups.
Enter the Accessor value you copied in the Accessor field and click Lookup.
Awaiting authorization message displays.
Click Authorize. The message changes to "Thanks! You have given authorization."
Sign out of the UI.

(Persona: processor)

Sign in with username bob and password training.
Click the Tools menu and then click Unwrap.
Enter the Control Group Token value you copied earlier in the Wrapping token field.

Click Unwrap data to read the secrets.

Example output:

{
  "data": {
    "order_number": "12345678",
    "product_id": "987654321"
  },
  "metadata": {
    "created_time": "2023-11-27T23:42:45.384562706Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  }
}

Define a control group for operations

Assume that Bob's token has read-paris and change-paris policies attached. The read-paris allows Bob to perform read and list operations against the paris-kv/* path.

read-paris.hcl

path "paris-kv/*" {
   capabilities = [ "read", "list" ]
}

The change-paris policy requires 1 approval from eng-managers group if Bob tries to perform create, update or delete operation against the paris-kv/* path.

change-paris.hcl

path "paris-kv/*" {
   capabilities = [ "create", "update", "delete" ]
   control_group = {
      factor "managers" {
         identity {
            group_names = [ "eng-managers" ]
            approvals = 1
         }
      }
   }
}

The intention was that Bob can read or list secrets at paris-kv/* without authorization. However, when both of those policies are applied, even the read and list operations will trigger the control groups. The read and list capabilities from the read-paris policy get aggregated into the change-paris capabilities list.

Controlled capabilities

To solve this, use controlled_capabilities in the policy to narrow the scope of control group to the operation level.

restrict-paris.hcl

path "paris-kv/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
   control_group = {
      factor "managers" {
         controlled_capabilities = [ "create", "update", "delete" ]
         identity {
            group_names = [ "acct_manager" ]
            approvals = 1
         }
      }
   }
}

Test controlled capabilities

Login with the admin persona's token.
Note
For Vault Enterprise, use root as the token value. For HCP Vault Dedicated, use the admin token from the HCP Portal.
```
$ vault login <actual-token>
```

Create a restrict-paris policy.

$ tee restrict-paris.hcl <<EOF
path "paris-kv/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
   control_group = {
      factor "managers" {
         controlled_capabilities = [ "create", "update", "delete" ]
         identity {
            group_names = [ "acct_manager" ]
            approvals = 1
         }
      }
   }
}
EOF

Deploy the restrict-paris policy.

$ vault policy write restrict-paris restrict-paris.hcl

Success! Uploaded policy: restrict-paris

Add the policy to Bob's entity.

$ vault write identity/entity/id/$(cat entity_id_bob.txt) \
        policies="read-gdpr-order,restrict-paris"

Example output:

Success! Data written to: identity/entity/id/84f39aab-8ae2-a647-6a9d-hiJKlmnop

Enable kv-v2 secrets engine at paris-kv.

$ vault secrets enable -path="paris-kv" kv-v2

Success! Enabled the kv-v2 secrets engine at: paris-kv/

Create some mock data at paris-kv.

$ vault kv put paris-kv/product name="Boundary" version="0.4.0"

==== Secret Path ====
paris-kv/data/product

======= Metadata =======
Key                Value
---                -----
created_time       2022-05-18T19:18:16.553795Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

$ vault login -method=userpass username="bob" password="training"

The returned token should have restrict-paris policy attached.

Example output:

Key                    Value
---                    -----
token                  hvs.vAUdsbhpSZv0CqsC5qAqdaQ3
token_accessor         VHuhVHCxzZlWh4qbXTHaPGak
token_duration         768h
token_renewable        true
token_policies         ["default"]
identity_policies      ["read-gdpr-order" "restrict-paris"]
policies               ["default" "read-gdpr-order" "restrict-paris"]
token_meta_username    bob

Read the secrets at paris-kv/product.

$ vault kv get paris-kv/product

==== Secret Path ====
paris-kv/data/product

======= Metadata =======
Key                Value
---                -----
created_time       2022-05-18T19:18:16.553795Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

===== Data =====
Key        Value
---        -----
name       Boundary
version    0.4.0

You should be able to read the secrets without triggering the control group.

Try to delete the secrets at paris-kv/product.

$ vault kv delete paris-kv/product

This time, Vault returns wrapping_token and wrapping_accessor.

Example output:

Key                              Value
---                              -----
wrapping_token:                  hvs.6myj2lXu7xg39CjrUFiLrwSV
wrapping_accessor:               X9AISHC5GSMGyDNpoYG3tw8s
wrapping_token_ttl:              24h
wrapping_token_creation_time:    2021-07-21 22:12:16 -0700 PDT
wrapping_token_creation_path:    paris-kv/data/releases

Set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=root
```

Create an API request payload containing the restrict-paris policy.

$ tee payload-restrict-paris.json <<EOF
{
  "policy":  "path \"paris-kv/*\" {\n   capabilities = [ \"create\", \"update\", \"delete\", \"read\", \"list\" ]\n   control_group = {\n      factor \"managers\" {\n        controlled_capabilities = [ \"create\", \"update\", \"delete\" ]\n        identity {\n            group_names = [ \"acct_manager\" ]\n            approvals = 1\n         }\n      }\n   }\n}\n"
}
EOF

Create a new policy named restrict-paris.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request PUT \
    --data @payload-restrict-paris.json \
    $VAULT_ADDR/v1/sys/policies/acl/restrict-paris

Add the policy to Bob's entity.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request PUT \
   --data '{"policies": ["read-gdpr-order", "restrict-paris"]}' \
   $VAULT_ADDR/v1/identity/entity/id/$(cat entity_id_bob.txt)

Create an API request payload to enable kv-v2 secrets engine at paris-kv.

$ tee payload-kv-paris.json <<EOF
{
  "type": "kv",
  "options": {
      "version": "2"
  }
}
EOF

Enable kv-v2 at paris-kv.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload-kv-paris.json \
   $VAULT_ADDR/v1/sys/mounts/paris-kv

Create an API request payload containing mock data.

$ tee paris-test_data.json <<EOF
{
  "data": {
    "name": "Boundary",
    "version": "0.4.0"
  }
}
EOF

Write the mock data at paris-kv/data/product.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @paris-test_data.json \
   $VAULT_ADDR/v1/paris-kv/data/product | jq -r

Unset the VAULT_TOKEN token environment variable.
```
$ unset VAULT_TOKEN
```

$ curl --request POST \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth.client_token" > bob_client_token.txt

Read the secrets at paris-kv/data/product.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
    $VAULT_ADDR/v1/paris-kv/data/product| jq -r ".data.data"

Example output:

{
  "name": "Boundary",
  "version": "0.4.0"
}

Vault returns the data.

Try to delete the secrets at paris-kv/data/product.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
   --request DELETE \
   $VAULT_ADDR/v1/paris-kv/data/product | jq -r ".wrap_info"

Example output:

This time, Vault returns wrapping_token and wrapping_accessor.

{
  "token": "hvs.yVR44tCDqunEJ1mt8zRcaaIw",
  "accessor": "hFkAUpFnOTT7guvUshMT3Szo",
  "ttl": 86400,
  "creation_time": "2021-07-22T12:25:59-07:00",
  "creation_path": "paris-kv/data/product"
}

Set the VAULT_TOKEN environment variable with the Vault token value from the HCP Portal.
```
$ export VAULT_TOKEN=<actual-vault-token>
```

Create an API request payload containing the restrict-paris policy.

$ tee payload-restrict-paris.json <<EOF
{
  "policy":  "path \"paris-kv/*\" {\n   capabilities = [ \"create\", \"update\", \"delete\", \"read\", \"list\" ]\n   control_group = {\n      factor \"managers\" {\n        controlled_capabilities = [ \"create\", \"update\", \"delete\" ]\n        identity {\n            group_names = [ \"acct_manager\" ]\n            approvals = 1\n         }\n      }\n   }\n}\n"
}
EOF

Create a new policy named restrict-paris.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request PUT \
    --data @payload-restrict-paris.json \
    $VAULT_ADDR/v1/sys/policies/acl/restrict-paris

Add the policy to Bob's entity.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request PUT \
    --data '{"policies": ["read-gdpr-order", "restrict-paris"]}' \
    $VAULT_ADDR/v1/identity/entity/id/$(cat entity_id_bob.txt)

Create an API request payload to enable kv-v2 secrets engine at paris-kv.

$ tee payload-kv-paris.json <<EOF
{
  "type": "kv",
  "options": {
      "version": "2"
  }
}
EOF

Enable kv-v2 at paris-kv.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data @payload-kv-paris.json \
    $VAULT_ADDR/v1/sys/mounts/paris-kv

Create an API request payload containing mock data.

$ tee paris-test_data.json <<EOF
{
  "data": {
    "name": "Boundary",
    "version": "0.4.0"
  }
}
EOF

Write the mock data at paris-kv/data/product.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data @paris-test_data.json \
    $VAULT_ADDR/v1/paris-kv/data/product | jq -r

Unset the VAULT_TOKEN token environment variable.
```
$ unset VAULT_TOKEN
```

$ curl --request POST \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --data '{"password": "training"}' \
    $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth.client_token" > bob_client_token.txt

Read the secrets at paris-kv/data/product.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    $VAULT_ADDR/v1/paris-kv/data/product| jq -r ".data.data"

Example output:

{
  "name": "Boundary",
  "version": "0.4.0"
}

Vault returns the data.

Try to delete the secrets at paris-kv/data/product.

$ curl --header "X-Vault-Token: $(cat bob_client_token.txt)" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request DELETE \
    $VAULT_ADDR/v1/paris-kv/data/product | jq -r ".wrap_info"

Example output:

This time, Vault returns wrapping_token and wrapping_accessor.

{
  "token": "hvs.yVR44tCDqunEJ1mt8zRcaaIw",
  "accessor": "hFkAUpFnOTT7guvUshMT3Szo",
  "ttl": 86400,
  "creation_time": "2021-07-22T12:25:59-07:00",
  "creation_path": "paris-kv/data/product"
}

Login as an admin persona (e.g. root or admin token).
Click the Policies menu, and then click Create ACL policy.
Enter restrict-paris in the Name field.

Enter the following in the Policy text field.

path "paris-kv/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
   control_group = {
      factor "managers" {
         controlled_capabilities = [ "create", "update", "delete" ]
         identity {
            group_names = [ "acct_manager" ]
            approvals = 1
         }
      }
   }
}

Click Create Policy.
Click Back to main navigation.
Click the Access menu, and then click Entities.
Click Bob Smith and then click Edit entity.
Under Policies, select and add the restrict-paris policy.
Click Save.
Click Back to main navigation.
Click Secrets Engines and then click Enable new engine.
Select KV from the list, and then click Next.
Enter paris-kv in the Path field.
Click Enable Engine to complete.
Click Create secret.
Enter product in the Path for this secret field.
Under Secret data, enter name in the key field and set its value to Boundary.
Click Add, enter version in the new key field and set its value to 0.4.0.
Click Save.
Sign out of the Vault UI.
From the Sign in to Vault page, select Username from the Method drop-down list.
Enter bob in the Username field and training in the Password field.
Click Sign in.
Click paris-kv under Secrets engines.
Click product. The secrets are displayed. You can click on the sensitive information toggle to show the entered secret values.
Click the Vault CLI shell icon (>_) to open a command shell, and execute the command to delete the secrets:
```
$ vault write -force paris-kv/delete/product
```
The output should display the Accessor and token values.

Optional: If you want to complete the rest of the workflow, repeat the steps you performed previously in the Test the control group section.

Login as ellen.
Authorize Bob's request using the wrapping accessor value.
Login as bob.
Unwrap the secrets using the wrapping token.

ACL policy vs. Sentinel policy

Although the read-gdpr-order.hcl was written as ACL policy, you can implement control groups in either ACL or Sentinel policies.

Using Sentinel, the same policy may look something like.

read-gdpr-order.sentinel

1 2 3 4 5 6 7 8 9 101112131415161718import "controlgroup"

control_group = func() {
  numAuthzs = 0
  for controlgroup.authorizations as authz {
      if "acct_manager" in authz.groups.by_name {
         numAuthzs = numAuthzs + 1
      }
  }
  if numAuthzs >= 1 {
      return true
  }
  return false
}

main = rule {
   control_group()
}

Deploy this policy as an Endpoint Governing Policy attached to "EU_GDPR_data/data/orders/*" path.

Tip

Refer to the Sentinel Properties documentation for the list of available properties associated with control groups. If you are new to Sentinel, go through the Sentinel Policies tutorial.

Help and Reference

Sentinel policy examples

Configurable password generation policies

This tutorial also appears in:

10 tutorials

Manage HCP Vault Dedicated
Manage your HCP Vault Dedicated clusters.
- Vault
28 tutorials

Vault Enterprise
Learn features that are only available to Vault Enterprise.
- Vault