status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Clarify purpose of example ACL rules and policies

This commit is contained in:
Blake Covarrubias 2022-05-08 23:25:01 -07:00
parent ab9c7d2dd4
commit 34b2f5daea
4 changed files with 39 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
website/content/docs/security/acl/acl-policies.mdx
View File

@ -453,7 +453,8 @@ service "consul-snapshot" {
If you are using [Vault](https://www.vaultproject.io/docs) to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/docs/dynamic-app-config/kv) and the [Vault storage documentation](https://www.vaultproject.io/docs/configuration/storage) for additional information. If you are using [Vault](https://www.vaultproject.io/docs) to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/docs/dynamic-app-config/kv) and the [Vault storage documentation](https://www.vaultproject.io/docs/configuration/storage) for additional information.
In the following example, Vault is registered as a service and provided access to Consul's KV store. In the following example, the ACL policy enables Vault to register as a service
and provides access to the `vault/` path in Consul's KV store.
<CodeTabs> <CodeTabs>

33
website/content/docs/security/acl/acl-rules.mdx
View File

@ -47,7 +47,8 @@ The `acl = "write"` rule is also required to create snapshots. This is because a
Rules for ACL resources do not use labels. Rules for ACL resources do not use labels.
In the following example, `write` access to the ACL API. The rule enables the operator to read or write ACLs, as well as discover the secret ID of any token. In the following example, the `acl` rule is configured with `write` access to the ACL API.
The rule enables the operator to read or write ACLs, as well as discover the secret ID of any token.
<CodeTabs heading="Example acl rule"> <CodeTabs heading="Example acl rule">
@ -68,8 +69,15 @@ acl = "write"
The `partition` and `partition_prefix` resource controls access to one or more admin partitions. The `partition` and `partition_prefix` resource controls access to one or more admin partitions.
You can include any number of namespace rules inside the admin partition. You can include any number of namespace rules inside the admin partition.
In the following example, the agent has write access to the `ex-namespace` namespace, as well as namespaces prefixed with `ex-` in the `example` partition. In the following example, the policy grants `write` access to the `ex-namespace`
The `mesh` resource is also scoped to the admin partition rule, which grants `write` access to mesh-level resources in the partition: namespace, as well as namespaces prefixed with `exns-` in the `example` partition.
The `mesh` resource is also scoped to the admin partition rule, which grants
`write` access to mesh-level resources in the `example` partition.
In addition, the policy grants `read` access to the `ex-namespace` namespace, as
well as namespaces prefixed with `exns-` in all partitions containing the
`example-` prefix. Read access is granted for `mesh` resource scoped within the
associated partition.
<CodeTabs heading="Example admin partition rules"> <CodeTabs heading="Example admin partition rules">
@ -183,9 +191,9 @@ agent_prefix "bar" {
</CodeTabs> </CodeTabs>
Agent rules are keyed by the node name they apply to. In the example above the rules Agent rules are keyed by the node name they apply to. In the example above the rules
allow read-only access to any node name by using the empty prefix, read-write access to allow read-write access to the node with the _exact_ name `foo`, read-only access
the node with the _exact_ name `foo`, and denies all access to any node name that starts to any node name by using the empty prefix, and denies all access to any node
with `bar`. name that starts with `bar`.
Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to
a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be
@ -276,7 +284,12 @@ to any key name with the empty prefix rule, allow read-write access to the "foo"
### List Policy for Keys ### List Policy for Keys
Enable the `list` policy disposition (Consul 1.0+) by setting the `acl.enable_key_list_policy` parameter to `true`. The disposition provides recursive access to `key` entries. Refer to the [KV API](/api-docs/kv#recurse) documentation for additional information. In the following example, `key` resources that start with `bar` are listed. Enable the `list` policy disposition (Consul 1.0+) by setting the
`acl.enable_key_list_policy` parameter to `true`. The disposition provides
recursive access to `key` entries. Refer to the [KV API](/api-docs/kv#recurse)
documentation for additional information.
In the following example, `key` resources that start with `bar` may be listed.
<CodeTabs heading="Example 'key' rules"> <CodeTabs heading="Example 'key' rules">
@ -563,7 +576,7 @@ These actions may required an ACL token to complete. Use the following methods t
* Provide an ACL token with `service` and `check` definitions at registration time. * Provide an ACL token with `service` and `check` definitions at registration time.
This allows for greater flexibility and enables the use of multiple tokens on the same agent. This allows for greater flexibility and enables the use of multiple tokens on the same agent.
Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples. Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples.
Tokens may also be passed to the [HTTP API](/api) for operations that require them. Tokens may also be passed to the [HTTP API](/api-docs) for operations that require them.
## Operator Rules ## Operator Rules
@ -755,10 +768,10 @@ to use for registration events:
tokens on the same agent. Examples of what this looks like are available for tokens on the same agent. Examples of what this looks like are available for
both [services](/docs/discovery/services) and both [services](/docs/discovery/services) and
[checks](/docs/discovery/checks). Tokens may also be passed to the [HTTP [checks](/docs/discovery/checks). Tokens may also be passed to the [HTTP
API](/api) for operations that require them. **Note:** all tokens API](/api-docs) for operations that require them. **Note:** all tokens
passed to an agent are persisted on local disk to allow recovery from passed to an agent are persisted on local disk to allow recovery from
restarts. See [`-data-dir` flag restarts. See [`-data-dir` flag
documentation](/docs/agent/config/config-files#acl_token) for notes on securing documentation](/docs/agent/config/cli-flags#_data_dir) for notes on securing
access. access.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with

28
website/content/docs/security/acl/acl-tokens.mdx
View File

@ -120,7 +120,7 @@ You can export tokens to environment variables on the local machine, which enabl
### API Requests ### API Requests
Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs/index#authentication) for details. Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs#authentication) for details.
The following example shows the header for a GET request to the `agent/members` endpoint. The following example shows the header for a GET request to the `agent/members` endpoint.
@ -137,12 +137,12 @@ Refer to the [API](/api-docs/acl/token) or [command line](/commands/acl/token) d
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- |
| `AccessorID` | Used for [audit logging](/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated | | `AccessorID` | Used for [audit logging](/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated |
| `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated | | `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated |
| `Partition` | <EnterpriseAlert inline/> Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. | `default` | | `Partition` | <EnterpriseAlert inline/> Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. | String | `default` |
| `Namespace` | <EnterpriseAlert inline/> Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/docs/enterprise/namespaces) for additional information. | String | `default` | | `Namespace` | <EnterpriseAlert inline/> Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/docs/enterprise/namespaces) for additional information. | String | `default` |
| `Description` | Human-readable description for documenting the purpose of the token. | String | none | | `Description` | Human-readable description for documenting the purpose of the token. | String | none |
| `Local` | Indicates whether the token should be replicated globally or local to the datacenter. <br/> Set to `false` to replicate globally across all reachable datacenters. <br/>Setting to `true` configures the token to functional in the local datacenter only. | Boolean | `false` | | `Local` | Indicates whether the token should be replicated globally or local to the datacenter. <br/> Set to `false` to replicate globally across all reachable datacenters. <br/>Setting to `true` configures the token to functional in the local datacenter only. | Boolean | `false` |
| `ServiceIdentities` | Specifies a list of nodes to apply to the token. See [Service Identities](/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none | | `ServiceIdentities` | Specifies a list of service identities to apply to the token. See [Service Identities](/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none |
| `NodeIdentities` | Specifies a list of nodes to apply to the token. See [Node Identities](/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none | | `NodeIdentities` | Specifies a list of node identities to apply to the token. See [Node Identities](/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none |
| `Legacy` | Indicates if the token was created using the the legacy ACL system. | Boolean | `false` | | `Legacy` | Indicates if the token was created using the the legacy ACL system. | Boolean | `false` |
| `Policies` | List of policies linked to the token, including the policy ID and name. | String | none | | `Policies` | List of policies linked to the token, including the policy ID and name. | String | none |
@ -162,7 +162,7 @@ All reserved tokens except the `initial_management` token can be created or upda
### Snapshot Tokens ### Snapshot Tokens
Snapshots are artifacts created with the [snapshot API](/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and require, and interacting with them requires a token with `write` privileges. Snapshots are artifacts created with the [snapshot API](/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and interacting with them requires a token with `acl:write` privileges.
### ACL Agent Token ### ACL Agent Token
@ -174,6 +174,8 @@ The [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) is a special toke
Here's an example policy sufficient to accomplish the above for a node called `mynode`: Here's an example policy sufficient to accomplish the above for a node called `mynode`:
<CodeBlockConfig heading="Example agent policy permitting internal operations">
```hcl ```hcl
node "mynode" { node "mynode" {
policy = "write" policy = "write"
@ -186,19 +188,10 @@ key_prefix "_rexec" {
} }
``` ```
</CodeBlockConfig>
The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted.
<!-- Consider removing this content now that we have versioned docs
In Consul 1.4 - 1.10, the following special tokens were known by different names:
| New Name (1.11+) | Old Name (1.4 - 1.10) |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) |
| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) |
-->
## Built-in Tokens ## Built-in Tokens
Consul includes a built-in anonymous token and initial management token. Both tokens are injected during when you bootstrap the cluster. Consul includes a built-in anonymous token and initial management token. Both tokens are injected during when you bootstrap the cluster.
@ -215,7 +208,8 @@ The description and policies may be updated, but the anonymous token cannot be d
### Initial Management Token ### Initial Management Token
Including an initial management token in the Consul configuration creates the token and links it with the built-in global management policy. Including an initial management token in the Consul configuration creates the
token and links it with the built-in [global management](/docs/security/acl/acl-policies#global-management) policy.
The bearer will have have unrestricted privileges to resources and APIs. The bearer will have have unrestricted privileges to resources and APIs.
The `SecretID` attribute will be set to the value of the configuration entry. The `SecretID` attribute will be set to the value of the configuration entry.

6
website/content/docs/security/acl/index.mdx
View File

@ -69,7 +69,7 @@ Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional informat
## Service Identities ## Service Identities
Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. They are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh.
Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service.
@ -80,9 +80,9 @@ Refer to the following topics for additional information about service identitie
## Node Identities ## Node Identities
Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent. Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each service. Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each node.
Refer to the following topics for additional information about node identities: Refer to the following topics for additional information about node identities: