Control Groups | Vault - HashiCorp Learn

Enterprise Only: Control Groups requires Vault Enterprise Plus license. To explore Vault Enterprise features, you can sign up for a free 30-day trial from here.

New Enhancement: A new parameter was introduced in Vault 1.8. If you are new to Control Groups, go through this tutorial end-to-end. To learn about the new parameter (controlled_capabilities) introduced in Vault 1.8, skip to the Define a control group for operations section.

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 a Vault Enterprise environment.

NOTE: To explore Vault Enterprise features, you can sign up for a free 30-day trial from here.

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.

# 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" ]
}

# Create and manage ACL policiespath "sys/policies/acl/*"{  capabilities = ["create", "read", "update", "delete", "list", "sudo"]}
# To enable secrets enginespath "sys/mounts/*" {  capabilities = [ "create", "read", "update", "delete" ]}
# Setting up test datapath "EU_GDPR_data/*"{  capabilities = ["create", "read", "update", "delete", "list"]}
# Manage userpass auth methodpath "auth/userpass/*"{  capabilities = ["create", "read", "update", "delete", "list"]}
# List, create, update, and delete auth methodspath "sys/auth/*"{  capabilities = ["create", "read", "update", "delete"]}
# Create and manage entities and groupspath "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:

Implement a control group
Deploy the policies
Setup entities and a group
Test the control group

If you want to implement Control Groups in Sentinel, read the ACL Policies vs. Sentinel Policies section.

»Step 1: 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

$ 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.

path "EU_GDPR_data/data/orders/*" {
  capabilities = [ "read" ]

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

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

$ tee acct_manager.hcl <<EOF# To approve the requestpath "sys/control-group/authorize" {    capabilities = ["create", "update"]}
# To check control group request statuspath "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.

»Step 2: 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

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

Create a new policy named acct_manager.

$ vault policy write acct_manager acct_manager.hcl

$ vault policy write acct_manager acct_manager.hcl

»Step 3: 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 you have policies, 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.

The following command uses jq tool to parse JSON output.

Enable the userpass auth method.

$ vault auth enable userpass
Success! Enabled userpass auth method at: userpass/

$ vault auth enable userpassSuccess! 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

$ 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

$ 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

$ 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

$ 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)

$ 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

Key             Value---             -----canonical_id    e57d0eff-ca1d-d4d8-b7b7-2b3f842b811did              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

$ 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)

$ 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

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

Finally, 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)

$ 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

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

»Step 4: Test the control group

(Persona: admin)

Now, see how the control group works.

First, 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/

$ vault secrets enable -path=EU_GDPR_data -version=2 kvSuccess! 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"

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

Example output:

Key              Value
---              -----
created_time     2021-07-22T02:15:02.221561Z
deletion_time    n/a
destroyed        false
version          1

Key              Value---              -----created_time     2021-07-22T02:15:02.221561Zdeletion_time    n/adestroyed        falseversion          1

(Persona: processor)

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

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

Request to read "EU_GDPR_data/orders/acct1".

$ vault kv get EU_GDPR_data/orders/acct1

$ vault kv get EU_GDPR_data/orders/acct1

Example output:

Key                              Value
---                              -----
wrapping_token:                  s.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

Key                              Value---                              -----wrapping_token:                  s.AmhW6ULQ7Eoy6o5JMHr679Z0wrapping_accessor:               Vbs3d5FGbeox1mjYOgLWvXsPwrapping_token_ttl:              24hwrapping_token_creation_time:    2021-07-21 19:42:35 -0700 PDTwrapping_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 WRAPPING_TOKEN=<wrapping_token>

Export the wrapping token accessor as WRAPPING_ACCESSOR.

$ export WRAPPING_ACCESSOR=<wrapping_accessor>

$ export WRAPPING_ACCESSOR=<wrapping_accessor>

Example:

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

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

(Persona: controller)

Now, a member of acct_manager must approve this request. Log in as ellen who is a member of acct_manager group.

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

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

As a user, ellen, you can check and authorize bob's request using the following commands.

To check the current status:

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

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

To approve the request:

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

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

Example:

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

$ vault write sys/control-group/request accessor=$WRAPPING_ACCESSORKey               Value---               -----approved          falseauthorizations    <nil>request_entity    map[name:Bob Smith id:38700386-723d-3d65-43b7-4fb44d7e6c30]request_path      EU_GDPR_data/orders/acct1

Approve the request.

$ vault write sys/control-group/authorize accessor=$WRAPPING_ACCESSOR
Key         Value
---         -----
approved    true

$ vault write sys/control-group/authorize accessor=$WRAPPING_ACCESSORKey         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.

Example:

Log back in as bob using the userpass auth method.

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

$ 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]

$ vault unwrap $WRAPPING_TOKENKey         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]

»Define a control group for operations

NOTE: This section describes the new parameter (controlled_capabilities) introduced in Vault 1.8.

Assuming 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.

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

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.

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

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 challenge, Vault 1.8 introduced controlled_capabilities. Now, you can narrow the scope of control group to the operation level.

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
         }
      }
   }
}

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

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

$ 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

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

Add the policy to Bob's entity.

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

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

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/

$ 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"
Key              Value
---              -----
created_time     2021-07-22T04:52:20.262502Z
deletion_time    n/a
destroyed        false
version          1

$ vault kv put paris-kv/product name="Boundary" version="0.4.0"Key              Value---              -----created_time     2021-07-22T04:52:20.262502Zdeletion_time    n/adestroyed        falseversion          1

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

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

The returned token should have restrict-paris policy attached.

Example:

Key                    Value
---                    -----
token                  s.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

Key                    Value---                    -----token                  s.vAUdsbhpSZv0CqsC5qAqdaQ3token_accessor         VHuhVHCxzZlWh4qbXTHaPGaktoken_duration         768htoken_renewable        truetoken_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 

====== Metadata ======
Key              Value
---              -----
created_time     2021-07-22T04:52:20.262502Z
deletion_time    n/a
destroyed        false
version          1

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

$ vault kv get paris-kv/product 
====== Metadata ======Key              Value---              -----created_time     2021-07-22T04:52:20.262502Zdeletion_time    n/adestroyed        falseversion          1
===== Data =====Key        Value---        -----name       Boundaryversion    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

$ vault kv delete paris-kv/product

This time, Vault returns wrapping_token and wrapping_accessor.

Example output:

Key                              Value
---                              -----
wrapping_token:                  s.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

Key                              Value---                              -----wrapping_token:                  s.6myj2lXu7xg39CjrUFiLrwSVwrapping_accessor:               X9AISHC5GSMGyDNpoYG3tw8swrapping_token_ttl:              24hwrapping_token_creation_time:    2021-07-21 22:12:16 -0700 PDTwrapping_token_creation_path:    paris-kv/data/releases

Optional: If you want to complete the rest of the workflow, repeat the steps you performed previously in Step 4.

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.

import "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()
}

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.

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.

Infrastructure

Security

Applications

Networking

cloud

»Challenge

»Solution

»Prerequisites

»Policy requirements

»Scenario Introduction

»Scenario workflow

»Step 1: Implement a control group

»Examine the policy

»Step 2: Deploy the policies

»Step 3: Setup entities and a group

»Step 4: Test the control group

»Define a control group for operations

»Controlled capabilities

»Test controlled capabilities

»ACL Policy vs. Sentinel Policy

»Help and Reference