Use control groups for authorization

Vault Enterprise has support for Control Group Authorization. Control Groups add additional authorization factors to be required before satisfying a request.

When a Control Group is required for a request, a limited duration response wrapping token is returned to the user instead of the requested data. The accessor of the response wrapping token can be passed to the authorizers required by the control group policy. Once all authorizations are satisfied, the wrapping token can be used to unwrap and process the original request.

Control group factors

Control Groups can verify the following factors:

• Identity Groups - Require an authorizer to be in a specific set of identity groups.

Controlled capabilities

Control group factors can be configured to trigger the control group workflow on specific capabilities. This is done with the controlled_capabilities field. Not specifying the controlled_capabilities field will necessitate the factor to be checked for all operations to the specified policy path. The controlled_capabilities field can differ per factor, so that different factors can be required for different operations.

Finally, the capabilities in the controlled_capabilities stanza must be a subset of the capabilities specified in the policy itself. For example, a policy giving only read access to the path secret/foo cannot specify a control group factor with list as a controlled capability.

Please see the following section for examples using ACL policies.

Control groups in ACL policies

Control Group requirements on paths are specified as control_group along with other ACL parameters.

Sample ACL policies

path "secret/foo" {
    capabilities = ["read"]
    control_group = {
        factor "ops_manager" {
            identity {
                group_names = ["managers"]
                approvals = 1
            }
        }
    }
}

The above policy grants read access to secret/foo only after one member of the "managers" group authorizes the request.

path "secret/foo" {
    capabilities = ["create", "update"]
    control_group = {
        ttl = "4h"
        factor "tech leads" {
            identity {
                group_names = ["managers", "leads"]
                approvals = 2
            }
        }
        factor "super users" {
            identity {
                group_names = ["superusers"]
                approvals = 1
            }
        }
    }
}

The above policy grants create and update access to secret/foo only after two (2) members of the "managers" or "leads" group and one member of the "superusers" group authorizes the request. If an authorizer is a member of both the "managers" and "superusers" group, one authorization for both factors will be satisfied.

path "secret/foo" {
    capabilities = ["write","read"]
    control_group = {
        factor "admin" {
            controlled_capabilities = ["write"]
            identity {
                group_names = ["admin"]
                approvals = 1
            }
        }
    }
}

The above policy grants read access to secret/foo for anyone that has a vault token with this policy. It grants write access to secret/foo only after one member from the admin group authorizes the request.

path "kv/*" {
    capabilities = ["create", "update","delete","list","sudo"]
    control_group = {
        factor "admin" {
            controlled_capabilities = ["delete","list","sudo"]
            identity {
                group_names = ["admin"]
                approvals = 1
            }
        }
    }
}
path "kv/*" {
    capabilities = ["create"]
    control_group = {
        factor "superuser" {
            identity {
                group_names = ["superuser"]
                approvals = 2
            }
        }
    }
}

Because the second path stanza has a control group factor with no controlled_capabilities field, any token with this policy will be required to get two (2) approvals from the "superuser" group before executing any operation against kv/*. In addition, by virtue of the controlled_capabilities field in the first path stanza, delete,list, and sudo operations will require an additional approval from the "admin" group.

path "kv/*" {
    capabilities = ["read", "list", "create"]
    control_group = {
        controlled_capabilities = ["read"]
        factor "admin" {
            identity {
                group_names = ["admin"]
                approvals = 1
            }
        }
        factor "superuser" {
            controlled_capabilities = ["create"]
            identity {
                group_names = ["superuser"]
                approvals = 1
            }
        }
    }
}

In this case, read will require one admin approval and create will require one superuser approval and one admin approval. List will require no extra approvals from any of the control group factors, and a token with this policy will not be required to go through the control group workflow in order to execute a read operation against kv/*.

Control groups in Sentinel

Control Groups are also supported in Sentinel policies using the controlgroup import. See Sentinel Documentation for more details on available properties.

Sample Sentinel policy

import "time"
import "controlgroup"
 
control_group = func() {
    numAuthzs = 0
    for controlgroup.authorizations as authz {
        if "managers" in authz.groups.by_name {
            if time.load(authz.time).unix > time.now.unix - 3600 {
                numAuthzs = numAuthzs + 1
            }
        }
    }
    if numAuthzs >= 2 {
        return true
    }
    return false
}
 
main = rule {
    control_group()
}

The above policy will reject the request unless two members of the "managers" group have authorized the request. Additionally it verifies the authorizations happened in the last hour.

Tutorial

Refer to the Control Groups tutorial to learn how to implement dual controller authorization within your policies.

API

Control Groups can be managed over the HTTP API. Please see Control Groups API for more details.