Control Groups

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.

»Personas

The end-to-end scenario described in this tutorial involves three personas:

• admin with privileged permissions to create policies and identities
• processor with permission to approve secret access
• controller with limited permission to access 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.

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:

• Policies
• Identity - Entities & Groups

»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" ]
}
Copy

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

You are going to perform the following:

1. Implement a control group
2. Deploy the policies
3. Setup entities and a group
4. Verification
5. ACL Policies vs. Sentinel Policies

»Step 1: Implement a control group

Author a policy named read-gdpr-order.hcl.

Bob needs read permissions on EU_GDPR_data/data/orders/*.

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

Now, add control group to this policy:

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

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

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.

Now, write another policy for the acct_manager group named acct_manager.hcl.

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

»Step 2: Deploy the policies

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

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

$ vault policy write acct_manager acct_manager.hcl
Copy

»Step 3: Setup entities and a group

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, let's create a user, bob and an acct_manager group with ellen as a group member.

»Step 4: Verification

Now, let's see how the control group works.

»Step 5: 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()
}
Copy

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

»Help and Reference

• Vault Enterprise Control Group Support
• Policies
• Identity Groups
• Control Group API
• Sentinel Policies