diff --git a/website/content/docs/security/acl/acl-policies.mdx b/website/content/docs/security/acl/acl-policies.mdx index 7c5286e0bb..5a1b2f8d30 100644 --- a/website/content/docs/security/acl/acl-policies.mdx +++ b/website/content/docs/security/acl/acl-policies.mdx @@ -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. -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. diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index 23131776a3..3234c9cd0d 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -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. -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. @@ -68,8 +69,15 @@ acl = "write" 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. -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. -The `mesh` resource is also scoped to the admin partition rule, which grants `write` access to mesh-level resources in the partition: +In the following example, the policy grants `write` access to the `ex-namespace` +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. @@ -183,9 +191,9 @@ agent_prefix "bar" { 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 -the node with the _exact_ name `foo`, and denies all access to any node name that starts -with `bar`. +allow read-write access to the node with the _exact_ name `foo`, read-only access +to any node name by using the empty prefix, and denies all access to any node +name that starts with `bar`. 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 @@ -276,7 +284,12 @@ to any key name with the empty prefix rule, allow read-write access to the "foo" ### 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. @@ -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. 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. - 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 @@ -755,10 +768,10 @@ to use for registration events: tokens on the same agent. Examples of what this looks like are available for both [services](/docs/discovery/services) and [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 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. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with diff --git a/website/content/docs/security/acl/acl-tokens.mdx b/website/content/docs/security/acl/acl-tokens.mdx index 1267aafbf4..8c80be719d 100644 --- a/website/content/docs/security/acl/acl-tokens.mdx +++ b/website/content/docs/security/acl/acl-tokens.mdx @@ -120,7 +120,7 @@ You can export tokens to environment variables on the local machine, which enabl ### 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. @@ -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 | | `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated | -| `Partition` | 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` | 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` | 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 | | `Local` | Indicates whether the token should be replicated globally or local to the datacenter.
Set to `false` to replicate globally across all reachable datacenters.
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 | -| `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 | +| `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 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` | | `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 -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 @@ -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`: + + ```hcl node "mynode" { policy = "write" @@ -186,19 +188,10 @@ key_prefix "_rexec" { } ``` + + 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. - - ## Built-in Tokens 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 -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 `SecretID` attribute will be set to the value of the configuration entry. diff --git a/website/content/docs/security/acl/index.mdx b/website/content/docs/security/acl/index.mdx index 2b15986c80..acb519103a 100644 --- a/website/content/docs/security/acl/index.mdx +++ b/website/content/docs/security/acl/index.mdx @@ -69,7 +69,7 @@ Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional informat ## 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. @@ -80,9 +80,9 @@ Refer to the following topics for additional information about service identitie ## 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: