open-vault/website/content/docs/enterprise/control-groups.mdx

216 lines
6.4 KiB
Plaintext
Raw Normal View History

2017-11-14 11:13:11 +00:00
---
layout: docs
page_title: Vault Enterprise Control Groups
description: Vault Enterprise has support for Control Group Authorization.
2017-11-14 11:13:11 +00:00
---
2020-05-11 15:12:48 +00:00
# Vault Enterprise Control Groups
2017-11-14 11:13:11 +00:00
-> **Note**: This feature requires [Vault Enterprise](https://www.hashicorp.com/products/vault/)
with the Governance And Policy Module.
2017-11-14 11:13:11 +00:00
Vault Enterprise has support for Control Group Authorization. Control Groups
add additional authorization factors to be required before satisfying a request.
2017-11-14 11:13:11 +00:00
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
2018-03-20 18:54:10 +00:00
required by the control group policy. Once all authorizations are satisfied,
2017-11-14 11:13:11 +00:00
the wrapping token can be used to unwrap and process the original request.
## Control Group Factors
Control Groups can verify the following factors:
2017-11-14 11:13:11 +00:00
- `Identity Groups` - Require an authorizer to be in a specific set of identity
groups.
2017-11-14 11:13:11 +00:00
### 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` specifed 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 example ACL Policies.
2017-11-14 11:13:11 +00:00
## Control Groups In ACL Policies
Control Group requirements on paths are specified as `control_group` along
2017-11-14 11:13:11 +00:00
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
2017-11-14 11:13:11 +00:00
two member 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
2017-11-14 11:13:11 +00:00
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 2 approvals from the `superuser` group before executing
any operation against `kv/*`. In addition, by virtue of the `controlled_capablities` 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/*`.
2017-11-14 11:13:11 +00:00
## Control Groups in Sentinel
Control Groups are also supported in Sentinel policies using the `controlgroup`
import. See [Sentinel Documentation](/docs/enterprise/sentinel) for more
2017-11-14 11:13:11 +00:00
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.
## Learn
Refer to the [Control Groups](https://learn.hashicorp.com/vault/identity-access-management/iam-control-groups)
guide for a step-by-step tutorial.
## API
2017-11-14 11:13:11 +00:00
Control Groups can be managed over the HTTP API. Please see
[Control Groups API](/api/system/control-group) for more details.