From 3b74497040edc30b06489c0709e9024508a12e39 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 10 Jan 2022 17:07:38 -0500 Subject: [PATCH] docs: move the ACL 'Authorization' section This section was actually about authentication (not authorization). We already have sections in our api and cli docs. This commit removes the section and replaces it with a short paragraph in the Tokens section which links to the existing docs. --- website/content/api-docs/index.mdx | 8 +++++-- website/content/commands/index.mdx | 9 ++++++++ .../content/docs/security/acl/acl-system.mdx | 21 +++++-------------- 3 files changed, 20 insertions(+), 18 deletions(-) diff --git a/website/content/api-docs/index.mdx b/website/content/api-docs/index.mdx index d57d86b18a..2a7a6f10bf 100644 --- a/website/content/api-docs/index.mdx +++ b/website/content/api-docs/index.mdx @@ -18,7 +18,11 @@ requests using the `X-Consul-Token` header or with the Bearer scheme in the authorization header. This reduces the probability of the token accidentally getting logged or exposed. When using authentication, -clients should communicate via TLS. If you don’t provide a token in the request, then the agent default token will be used. +clients should communicate via TLS. + +If no token is provided for an HTTP request then Consul will use the default ACL token +if it has been configured. If no default ACL token was configured then the anonymous +token will be used. Below is an example using `curl` with `X-Consul-Token`. @@ -28,7 +32,7 @@ $ curl \ http://127.0.0.1:8500/v1/agent/members ``` -Below is an example using `curl` with Bearer scheme. +Below is an example using `curl` with a [RFC6750](https://tools.ietf.org/html/rfc6750) Bearer token. ```shell-session $ curl \ diff --git a/website/content/commands/index.mdx b/website/content/commands/index.mdx index 2ecd76563b..aae260c4b6 100644 --- a/website/content/commands/index.mdx +++ b/website/content/commands/index.mdx @@ -91,6 +91,15 @@ Command Options Joins a server to another server in the WAN pool. ``` +## Authentication + +When the [ACL system is enabled](/docs/agent/options#acl_enabled) the Consul CLI will +require an [ACL token](/docs/security/acl/acl-system#tokens) to perform API requests. + +The ACL token can be provided directly on the command line using the `-token` command line flag, +from a file using the `-token-file` command line flag, or from the +[`CONSUL_HTTP_TOKEN`](#consul_http_token_file) environment variable. + ## Autocompletion The `consul` command features opt-in subcommand autocompletion that you can diff --git a/website/content/docs/security/acl/acl-system.mdx b/website/content/docs/security/acl/acl-system.mdx index 0c13da0151..6392451b2e 100644 --- a/website/content/docs/security/acl/acl-system.mdx +++ b/website/content/docs/security/acl/acl-system.mdx @@ -46,6 +46,11 @@ Tokens can be created directly from the [CLI](/commands/acl/token) or [API](/api [Auth Methods](/docs/security/acl/auth-methods) can be used to dynamically create tokens from a trusted external system. +Consul HTTP API requests accept a token from an [HTTP Header](/api-docs/index#authentication), +and CLI requests accept a token from +[`-token` command line flag](/commands#authentication) or +[`CONSUL_HTTP_TOKEN_FILE` environment variable](/commands#consul_http_token_file). + ## Policies @@ -293,22 +298,6 @@ injected. token is created with the Secret ID set to the value of the configuration entry. In Consul 1.4 - 1.10, this was called the `master` token. It was renamed to `initial_management` token in Consul 1.11. -#### Authorization - -The token Secret ID is passed along with each RPC request to the servers. Consul's -[HTTP endpoints](/api) can accept tokens via the `token` -query string parameter, the `X-Consul-Token` request header, or an -[RFC6750](https://tools.ietf.org/html/rfc6750) authorization bearer token. Consul's -[CLI commands](/docs/commands) can accept tokens via the -`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. The CLI -commands can also accept token values stored in files with the `token-file` -argument, or the `CONSUL_HTTP_TOKEN_FILE` environment variable. - -If no token is provided for an HTTP request then Consul will use the default ACL token -if it has been configured. If no default ACL token was configured then the anonymous -token will be used. - - #### ACL Agent Recovery Token Since the [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it