From 1562cb97491a2f468eaad4b900fcf5daa512a713 Mon Sep 17 00:00:00 2001 From: John Landa Date: Fri, 6 Oct 2023 14:43:40 -0600 Subject: [PATCH] DNS token doc updates Review feedback Update website/content/commands/acl/set-agent-token.mdx Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com> Update dns token doc to link to policy templates --- .../content/commands/acl/set-agent-token.mdx | 29 +- .../docs/agent/config/config-files.mdx | 7 +- .../acl/tokens/create/create-a-dns-token.mdx | 292 +----------------- .../docs/security/acl/tokens/index.mdx | 3 + 4 files changed, 33 insertions(+), 298 deletions(-) diff --git a/website/content/commands/acl/set-agent-token.mdx b/website/content/commands/acl/set-agent-token.mdx index 7279349dbbd9..f5d3aa343854 100644 --- a/website/content/commands/acl/set-agent-token.mdx +++ b/website/content/commands/acl/set-agent-token.mdx @@ -32,21 +32,13 @@ Usage: `consul acl set-agent-token [options] token_type token_secret_id` The token types are: -- `default` - The default token is the token that the agent will use for - both internal agent operations and operations initiated by the HTTP - and DNS interfaces when no specific token is provided. If not set the - agent will use the anonymous token. - - `agent` - The token that the agent will use for internal agent operations. If not given then the default token is used for these operations. -- `recovery` - This sets the token that can be used to access the Agent APIs - in the event that the ACL datacenter cannot be reached. In Consul versions - prior to 1.11, this token type was called `agent_master`. - -- `replication` - This is the token that the agent will use for replication - operations. This token will need to be configured with read access to - whatever data is being replicated. +- `dns` - Specifies the token that agents use to request information needed to respond to DNS queries. + If the `dns` token is not set, the `default` token is used instead. + Because the `default` token allows unauthenticated HTTP API access to list nodes and services, it is + strongly recommended to use the `dns` token. DNS tokens should be [created using the templated policy](/consul/docs/security/acl/tokens/create/create-a-dns-token#create_a_dns_token) to ensure the token has the permissions needed to respond to all DNS queries. - `config_file_service_registration` - This is the token that the agent uses to register services and checks defined in config files. This token needs to be @@ -55,6 +47,19 @@ The token types are: contains a `token` field, then that token is used to register that service or check instead of the `config_file_service_registration` token. +- `replication` - This is the token that the agent will use for replication + operations. This token will need to be configured with read access to + whatever data is being replicated. + +- `recovery` - This sets the token that can be used to access the Agent APIs + in the event that the ACL datacenter cannot be reached. In Consul versions + prior to 1.11, this token type was called `agent_master`. + +- `default` - The default token is the token that the agent will use for + both internal agent operations and operations initiated by the HTTP + and DNS interfaces when no specific token is provided. If not set the + agent will use the anonymous token. + ### API Options @include 'http_api_options_client.mdx' diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index e1e0d05376b2..dfb446733300 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -957,7 +957,12 @@ Refer to the [formatting specification](https://golang.org/pkg/time/#ParseDurati additional policy rules or the `config_file_service_registration` token can be replaced using the [Set Agent Token](/consul/commands/acl/set-agent-token) CLI command. - - `replication` ((#acl_tokens_replication)) - The ACL token used to + - `dns` ((#acl_tokens_dns)) - Specifies the token that agents use to request information needed to respond to DNS queries. + If the `dns` token is not set, the `default` token is used instead. + Because the `default` token allows unauthenticated HTTP API access to list nodes and services, it is + strongly recommended to use the `dns` token. DNS tokens should be [created using the templated policy](/consul/docs/security/acl/tokens/create/create-a-dns-token#create_a_dns_token) to ensure the token has the permissions needed to respond to all DNS queries. + + - `replication` ((#acl_tokens_replication)) - Specifies the token used to authorize secondary datacenters with the primary datacenter for replication operations. This token is required for servers outside the [`primary_datacenter`](#primary_datacenter) when ACLs are enabled. This token may be provided later using the [agent token API](/consul/api-docs/agent#update-acl-tokens) on each server. This token must have at least "read" permissions on ACL data but if ACL token replication is enabled then it must have "write" permissions. This also enables service mesh data replication, for which the token will require both operator "write" and intention "read" permissions for replicating CA and Intention data. diff --git a/website/content/docs/security/acl/tokens/create/create-a-dns-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-dns-token.mdx index 4fde8bcf9e6f..d99838592d73 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-dns-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-dns-token.mdx @@ -29,304 +29,27 @@ The DNS token must be linked to policies that grant the following permissions: @include 'create-token-requirements.mdx' -## DNS token in Consul CE +## Create a DNS token -To create a token for DNS, you must define a policy, register the policy with Consul, and link the policy to a token. - -### Define a policy - -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. - -The following example policy is defined in a file. The policy grants the appropriate permissions to enable a Consul agent to respond to DNS queries. - - - -```hcl -node_prefix "" { - policy = "read" -} -service_prefix "" { - policy = "read" -} -query_prefix "" { - policy = "read" -} -``` - -```json -{ - "node_prefix": { - "": [{ - "policy": "read" - }] - }, - "query_prefix": { - "": [{ - "policy": "read" - }] - }, - "service_prefix": { - "": [{ - "policy": "read" - }] - } -} -``` - - - -### Register the policy with Consul - -After defining the policy, you can register the policy with Consul using the command line or API endpoint. - - - - - -Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. - -The following example registers a policy defined in `dns-access.hcl`. - -```shell-session -$ consul acl policy create \ - -name "dns-access" -rules @dns-access.hcl \ - -description "DNS Policy" -``` - - - - - -Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. - -The following example registers the policy defined in `dns-access.hcl`. You must embed policy rules in the `Rules` field of the request body. - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Name": "dns-access", - "Description": "DNS Policy", - "Rules": "node_prefix \"\" {\n policy = \"read\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nquery_prefix \"\" {\n policy = \"read\"\n}\n" -}' -``` - - - - - -### Link the policy to a token - -After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods). - - - - - -Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command. - -The following command creates the ACL token linked to the policy `dns-access`. +Run the `consul acl token create` CLI command and specify the `builtin/dns` templated policy to create a DNS token. ```shell-session -$ consul acl token create \ - -description "DNS token" \ - -policy-name "dns-access" +$ consul acl token create -name "dns-token" -templated-policy "builtin/dns" ``` - - - - -Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. - -The following example creates the ACL token linked to the policy `dns-access`. - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Policies": [ - { - "Name": "dns-access" - } - ] -}' -``` - - - - - -## DNS token in Consul Enterprise - -To create a token for DNS, you must define a policy, register the policy with Consul, and link the policy to a token. - -### Define a policy - -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. - -The following example policy is defined in a file. The policy grants the appropriate permissions to enable a Consul agent to respond to DNS queries for resources in any namespace in any partition. - - - -```hcl -partition "default" { - namespace "default" { - query_prefix "" { - policy = "read" - } - } -} -partition_prefix "" { - namespace_prefix "" { - node_prefix "" { - policy = "read" - } - service_prefix "" { - policy = "read" - } - } -} -``` - -```json -{ - "partition": { - "default": [{ - "namespace": { - "default": [{ - "query_prefix": { - "": [{ - "policy": "read" - }] - } - }] - } - }] - }, - "partition_prefix": { - "": [{ - "namespace_prefix": { - "": [{ - "node_prefix": { - "": [{ - "policy": "read" - }] - }, - "service_prefix": { - "": [{ - "policy": "read" - }] - } - }] - } - }] - } -} -``` - - - -### Register the policy with Consul - -After defining the policy, you can register the policy with Consul using the command line or API endpoint. - -You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. The example policy contains permissions for multiple namespaces in multiple partitions. You must create ACL policies that grant permissions for multiple namespaces in multiple partitions in the `default` namespace and the `default` partition. - - - - - - -Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. - -```shell-session -consul acl policy create -partition "default" -namespace "default" \ - -name dns-access -rules @dns-access.hcl \ - -description "DNS Policy" -``` - - - - - -Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. - -The following example registers the policy defined in `dns-access.hcl`. You must embed policy rules in the `Rules` field of the request body. - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Name": "dns-access", - "Description": "DNS Policy", - "Partition": "default", - "Namespace": "default", - "Rules": "partition_prefix \"\" {\n namespace_prefix \"\" {\n node_prefix \"\" {\n policy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n query_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n" -}' -``` - - - - - -### Link the policy to a token - -After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods). - - - - - -Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command. - -The following command creates the ACL token linked to the policy `dns-access`. - -```shell-session -$ consul acl token create -partition "default" -namespace "default" \ - -description "DNS token" \ - -policy-name "dns-access" -``` - - - - - -Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. - -The following example creates the ACL token linked to the policy `dns-access`. - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Policies": [ - { - "Name": "dns-access" - } - ], - "Partition": "default", - "Namespace": "default" -}' -``` - - - - - ## Apply the token Configure the Consul agent with the token by either specifying the token in the agent configuration file or by using the `consul set-agent-token` command. ### Apply the token in a file -Specify the token in the [`default`](/consul/docs/agent/config/config-files#acl_tokens_default) field of the agent configuration file so that the agent can present it and register into the catalog on startup. +Specify the token in the [`dns`](/consul/docs/agent/config/config-files#acl_tokens_dns) field of the agent configuration file so that the agent can present it and register into the catalog on startup. ```hcl acl = { enabled = true tokens = { - default = "" + dns = "" ... } ... @@ -335,9 +58,8 @@ acl = { ### Apply the token with a command -Set the `default` token using the [`acl.token.default`](/consul/docs/agent/config/config-files#acl_tokens_default) command. The following command configures a running Consul agent token with the specified token. +Set the `dns` token using the [`acl.token.dns`](/consul/docs/agent/config/config-files#acl_tokens_dns) command. The following command configures a running Consul agent token with the specified token. ```shell-session -$ consul set-agent-token default +$ consul set-agent-token dns ``` - diff --git a/website/content/docs/security/acl/tokens/index.mdx b/website/content/docs/security/acl/tokens/index.mdx index 0c57cbbe38f7..067ca702f905 100644 --- a/website/content/docs/security/acl/tokens/index.mdx +++ b/website/content/docs/security/acl/tokens/index.mdx @@ -156,6 +156,9 @@ system or accessing Consul under specific conditions. The following table descri | [`acl.tokens.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Used for internal agent operations. See [ACL Agent Token](#acl-agent-token) for details. | | [`acl.tokens.initial_management`](/consul/docs/agent/config/config-files#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Used to bootstrap the ACL system. See [Initial Management Token](#initial-management-token). | | [`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Specifies a default token to use for client requests if no token is supplied. This is commonly configured with read-only access to services to enable DNS service discovery on agents. | +| [`acl.tokens.replication`](/consul/docs/agent/config/config-files#acl_tokens_replication) | `OPTIONAL` | `N/A` | Used to authorize secondary datacenters with the primary datacenter for replication operations. | +| [`acl.tokens.config_file_service_registration`](/consul/docs/agent/config/config-files#acl_tokens_config_file_service_registration) | `OPTIONAL` | `OPTIONAL` | Used to register services and checks from service and check definitions specified in configuration files or fragments passed to the agent using the `-hcl` flag. | +| [`acl.tokens.dns`](/consul/docs/agent/config/config-files#acl_tokens_dns) | `OPTIONAL` | `OPTIONAL` | Used by the agent to answer DNS queries about services and nodes. | All reserved tokens except the `initial_management` token can be created or updated using the [/v1/agent/token API](/consul/api-docs/agent#update-acl-tokens).