Vault Control Groups: Approval-Gated Access for Ops (Practical Guide & Exam Prep)

Control Groups (Control Group Authorization) is a Vault Enterprise feature that, for a designated path, releases a response (the secret) only after a predefined approver group meets a threshold (e.g., N approvals). Approvers cannot view the secret itself — they can only perform the approval action.

This article focuses on stable concepts grounded in the official documentation: the flow, definition via ACL policy, CLI/API operations, design patterns, troubleshooting, and Ops-track exam essentials. Specific API field names and UI labels may vary by version, so always confirm against the current official docs before implementing.

Control Groups Overview and Prerequisites

Control Groups act as an "approval gate" where Vault blocks access until the required approvals are collected, rather than granting it immediately. Approvals integrate with Vault Identity groups and are configured in per-path ACL policies. You can define multiple "factors," each with its own required approval count (e.g., 1 from security + 2 from team leads).

The approval request is represented as a single-use wrapping token. Approvers act on this token, and once the required count is met across all factors, the requester can unwrap to retrieve the original response. Approval and unwrap events are recorded in the audit log.

• Enterprise-only feature (not in OSS)
• Approvers do not see the secret body (approval only)
• Controlled by Identity groups and ACL policy (per path)
• Each factor has its own approval count; all factors must be satisfied
• Approval requests have a TTL (expiration invalidates them)

Request Lifecycle (Request → Approve → Unwrap)

When the requester reads a path covered by Control Groups, Vault does not return the secret immediately. Instead, it returns a notice that approval is required along with a single-use, TTL-bound wrapping token. The requester shares this token with approvers over a secure channel.

Approvers use their own Vault tokens (whose privileges come from group membership) to perform the approval operation against the wrapping token. Once all factor thresholds are met, the requester can unwrap the token and receive the original response (the secret). If the token expires or is revoked, the unwrap fails and the request must be re-issued.

• Wrapping tokens are single-use; they are invalidated if approvals do not arrive before expiration
• The audit log records who approved which token
• Approvals are counted per user (multiple approvals from the same user do not count)
• Retries are treated as new requests (a fresh token is issued each time)

Control Groups approval flow (conceptual diagram)

Requester (Client)             Approver                       Vault
      |                               |                         |
1)    |--- read request ------------->|                         |
      |                               |----> evaluate --------->|
      |<-- approval required + wrap --|                         |
      |         [token=T, TTL=t]      |                         |
2)    |--(share T via secure channel)>|                         |
3)    |                               |--- authorize(id=T) ---->|
      |                               |<-- accepted (1/N) ------|
      |                               |--- authorize(id=T) ---->|
      |                               |<-- accepted (N/N) ------|
4)    |--- unwrap(T) ------------------------------------------>|
      |<-- secret body ----------------------------------------|
      |                               |                         |
(On expiration/revocation the unwrap fails and the request must be re-issued)

Defining via ACL Policy (control_group block)

Control Groups are defined per path inside an ACL policy as a "control_group" block. You can declare multiple "factor" entries, each with its own "identity" condition (group name or ID) and required "approvals" count. The response is released only once every factor is satisfied.

On the approver side, the policy does not need read permission on the target path — what matters is permission to call the authorize API and correct resolution of Identity group membership. Misconfigured group mapping (OIDC/LDAP) or broken entity binding is a classic root cause of failed approvals.

• All factors are required (split designs if you want OR semantics)
• Approvers do not see the secret body (only the authorize API)
• Approval counts deduplicate by entity
• Paths must match exactly (mind /data/ on versioned KV)

ACL policy example (2 factors: 2 team leads + 1 security)

# policy.hcl
path "secret/data/payroll" {
  capabilities = ["read"]
  control_group = {
    factor "team-leads" {
      identity {
        group_names = ["team-leads"]
        approvals   = 2
      }
    }
    factor "secops" {
      identity {
        group_names = ["secops"]
        approvals   = 1
      }
    }
  }
}

# Register the policy (Enterprise)
vault write sys/policies/acl payroll-cg [email protected]

# Assign the required policy/group to the requester and each approver
# (Confirm that Identity groups are pre-created and external IdP mappings are in place)

Operational Procedure (Request, Approve, Unwrap)

Requester: read the target path normally. If it falls under Control Groups, Vault does not return the body immediately but instead returns a notice that approval is required plus the "approval target token" (wrapping token). The requester shares this token with approvers via a secure channel (an internal approval tool, secure chat, etc.).

Approver: call the authorize API with their own Vault token. Once the required approval count is met, the requester can unwrap the same wrapping token and finally obtain the body. Approvals and unwraps are traceable in the audit log. Exact API request body and response shapes can differ by version — follow the current official documentation.

• Approvals are evaluated at the time of each approval (unwrap becomes possible the moment the threshold is met)
• Wrapping tokens are single-use and time-bound; once expired, re-request
• The approver's policy needs permission for the "authorize"-family endpoints
• Operable from UI/CLI/API alike (align with your organization's approval workflow)

Minimal CLI/API example (conceptual)

# 1) Requester: read (if covered by CG, a notice that approval is required comes back)
vault read secret/data/payroll
# Follow the prompt and note the wrapping token (e.g., s.wrap_xxx)

# 2) Approver: authorize the wrapping token (run with the approver's own Vault token)
# Example endpoint (confirm body key names against your version)
vault write sys/control-group/authorize id=<wrapping-token>

# 3) Requester: once the threshold is met, unwrap the wrapping token
vault unwrap <wrapping-token>
# → the original response (the secret body) is displayed

Design Patterns and Operational Caveats

Approval factor design: define the minimum approval count appropriate for the business risk. Split cross-segment approvals (e.g., engineering + security) into separate factors to enforce mutual oversight. For high-frequency access, avoid over-approval — narrow the target paths and apply Control Groups only to the highest-risk areas.

TTL and expiration strategy: if the approval TTL is too short, daily operations stall; if too long, risk grows. Set it based on your business approval SLA and write down the re-request procedure for expirations. Define a separate break-glass procedure (a temporary emergency bypass) and make audit and post-mortem review mandatory.

Audit and observability: enable an audit device and pipe authorize/unwrap events to your SIEM. Confirm you can trace who approved which token when, and the reasons for expirations or failures.

• Apply only to high-risk areas to keep approval volume manageable
• Run break-glass with a scoped token + short TTL + strong audit
• Group-name-based references are fragile to renames — consider stable IDs
• Document the expiration/re-request runbook and brief the on-call rotation

Ops Exam Prep: Key Points and Pitfalls

Frequently asked points: Control Groups is an Enterprise feature; approvers do not see the body; defined via ACL control_group; all factors are required; approvals are performed against a single-use wrapping token; the body is disclosed only after unwrap; events appear in the audit log.

Easy-to-confuse concepts: Response Wrapping is "secure transport," not "approval." Sentinel and similar governance policies are guardrails, not workflow approvals. MFA / two-step authentication is a separate concept as well.

Pitfalls: wrong path notation (e.g., /data/ vs /metadata/ on KV v2), unresolved Identity groups, approval TTL too short and expiring, approvers missing authorize capabilities, approvals failing to reach the active node via replicas.

• Can you state clearly that it is Enterprise-only?
• Can you explain that "approvers do not see the body"?
• Do you understand the role of the ACL control_group block?
• Can you articulate the difference from Response Wrapping?

Check Your Understanding

Frequently Asked Questions