[Docs] Production Guide for ACLs (#5385)
* New guide for ACLs * Fixing some formatting issues. * Update website/source/docs/guides/production-acls.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/production-acls.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/production-acls.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Resolving PR comments. * Closing the rest of the PR comments * Updates for persistence. * Updating commands. * Update website/source/docs/guides/production-acls.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/production-acls.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
This commit is contained in:
kaitlincarter-hc
GitHub
parent
157ca0df24
commit
ca463fb1d5
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1,462 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Securing Consul with ACLs"
|
||||
sidebar_current: "docs-guides-acl-production"
|
||||
description: |-
|
||||
This guide walks though securing your production Consul datacenter with ACLs.
|
||||
---
|
||||
|
||||
The [Bootstrapping the ACL System guide](/advanced/day-1-operations/acl-guide)
|
||||
walks you through how to set up ACLs on a single datacenter. Because it
|
||||
introduces the basic concepts and syntax we recommend completing it before
|
||||
starting this guide. This guide builds on the first guide with recommendations
|
||||
for production workloads on a single datacenter.
|
||||
|
||||
After [bootstrapping the ACL
|
||||
system](/advanced/day-1-operations/production-acls#bootstrap-the-acl-system),
|
||||
you will learn how to create tokens with minimum privileges for:
|
||||
|
||||
* [Servers and Clients](/advanced/day-1-operations/production-acls#apply-individual-tokens-to-agents)
|
||||
* [Services](/advanced/day-1-operations/production-acls#apply-individual-tokens-to-services)
|
||||
* [DNS](/advanced/day-1-operations/production-acls#token-for-dns)
|
||||
* [Consul KV](/advanced/day-1-operations/production-acls#consul-kv-tokens)
|
||||
* [Consul UI](/advanced/day-1-operations/production-acls#consul-ui-tokens)
|
||||
|
||||
~> **Important:** For best results, use this guide during the [initial
|
||||
deployment](/advanced/day-1-operations/deployment-guide) of a Consul (version
|
||||
1.4.3 or newer) datacenter. Specifically, you should have already installed all
|
||||
agents and configured initial service definitions, but you should not yet rely
|
||||
on Consul for any service discovery or service configuration operations.
|
||||
|
||||
## Bootstrap the ACL System
|
||||
|
||||
You will bootstrap the ACL system in two steps, enable ACLs and create the
|
||||
bootstrap token.
|
||||
|
||||
### Enable ACLs on the Agents
|
||||
|
||||
To enable ACLs, add the following [ACL
|
||||
parameters](https://www.consul.io/docs/agent/options.html#configuration-key-reference)
|
||||
to the agent's configuration file and then restart the Consul service. If you
|
||||
want to reduce Consul client restarts, you can enable the ACLs
|
||||
on them when you apply the token.
|
||||
|
||||
```
|
||||
# agent.hcl
|
||||
{
|
||||
acl = {
|
||||
enabled = true,
|
||||
default_policy = "deny",
|
||||
enable_token_persistence = true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
~> Note: Token persistence was introduced in Consul 1.4.3. In older versions
|
||||
of Consul, you cannot persist tokens when using the HTTP API.
|
||||
|
||||
In this example, you configured the default policy of "deny", which means you
|
||||
are in whitelist mode. You also enabled token persistence when using the HTTP
|
||||
API. With persistence enabled, tokens will be persisted to disk and
|
||||
reloaded when an agent restarts
|
||||
|
||||
~> Note: If you are bootstrapping ACLs on an existing datacenter, enable the
|
||||
ACLs on the agents first with `default_policy=allow`. Default policy allow will
|
||||
enable ACLs, but will allow all operations, allowing the cluster to function
|
||||
normally while you create the tokens and apply them. This will reduce downtime.
|
||||
You should update the configuration files on all the servers first and then
|
||||
initiate a rolling restart.
|
||||
|
||||
### Create the Initial Bootstrap Token
|
||||
|
||||
To create the initial bootstrap token, use the `acl bootstrap` command on one
|
||||
of the servers.
|
||||
|
||||
```sh
|
||||
$ consul acl bootstrap
|
||||
```
|
||||
|
||||
The output gives you important information about the token, including the
|
||||
associated policy `global-management` and `SecretID`.
|
||||
|
||||
~> Note: By default, Consul assigns the `global-management` policy to the
|
||||
bootstrap token, which has unrestricted privileges. It is important to have one
|
||||
token with unrestricted privileges in case of emergencies; however you should
|
||||
only give a small number of administrators access to it. The `SecretID` is a
|
||||
UUID that you will use to identify the token when using the Consul CLI or HTTP
|
||||
API.
|
||||
|
||||
While you are setting up the ACL system, set the `CONSUL_HTTP_TOKEN`
|
||||
environment variable to the bootstrap token on one server, for this guide
|
||||
the example is on server "consul-server-one". This gives you the necessary
|
||||
privileges to continue
|
||||
creating policies and tokens. Set the environment variable temporarily with
|
||||
`export`, so that it will not persist once you’ve closed the session.
|
||||
|
||||
```sh
|
||||
$ export CONSUL_HTTP_TOKEN=<your_token_here>
|
||||
```
|
||||
|
||||
Now, all of the following commands in this guide can
|
||||
be completed on the same server, in this
|
||||
case server "consul-server-one".
|
||||
|
||||
## Apply Individual Tokens to Agents
|
||||
|
||||
Adding tokens to agents is a three step process.
|
||||
|
||||
1. [Create the agent
|
||||
policy](/advanced/day-1-operations/production-acls/create-the-agent-policy).
|
||||
2. [Create the token with the newly created
|
||||
policy](/advanced/day-1-operations/production-acls/create-the-agent-token).
|
||||
3. [Add the token to the agent](/advanced/day-1-operations/production-acls/add-the-token-to-the-agent).
|
||||
|
||||
|
||||
### Create the Agent Policy
|
||||
|
||||
We recommend creating agent policies that have write privileges for node
|
||||
related actions including registering itself in the catalog, updating node
|
||||
level health checks, and having write access on its configuration file. The
|
||||
example below has unrestricted privileges for node related actions for
|
||||
"consul-server-one" only.
|
||||
|
||||
```
|
||||
# consul-server-one-policy.hcl
|
||||
node "consul-server-one" {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
When creating agent policies, review the [node rules](
|
||||
https://www.consul.io/docs/agent/acl-rules.html#node-rules). Now that
|
||||
you have
|
||||
specified the policy, you can initialize it using the Consul
|
||||
CLI. To create a programmatic process, you could also use
|
||||
the HTTP API.
|
||||
|
||||
```sh
|
||||
$ consul acl policy create -name consul-server-one -rules @consul-server-one-policy.hcl
|
||||
```
|
||||
|
||||
The command output will include the policy information.
|
||||
|
||||
Repeat this process for all servers and clients in the Consul datacenter. Each agent should have its own policy based on the
|
||||
node name, that grants write privileges to it.
|
||||
|
||||
### Create the Agent Token
|
||||
|
||||
After creating the per-agent policies, create individual tokens for all the
|
||||
agents. You will need to include the policy in the `consul acl token create`
|
||||
command.
|
||||
|
||||
```sh
|
||||
$ consul acl token create -description "consul-server-one agent token" -policy-name consul-server-one
|
||||
```
|
||||
|
||||
This command returns the token information, which should include a description
|
||||
and policy information.
|
||||
|
||||
Repeat this process for each agent. It is the responsibility of the operator to
|
||||
save tokens in a secure location; we recommend
|
||||
[Vault](https://www.vaultproject.io/).
|
||||
|
||||
### Add the Token to the Agent.
|
||||
|
||||
Finally, apply the tokens to the agents using the HTTP API.
|
||||
Start with the servers
|
||||
and ensure they are working correctly before applying the client tokens. Please
|
||||
review the Bootstrapping the ACL System [guide](/advanced/day-1-operations/acl-guide) for example of setting the token in the agent configuration
|
||||
file.
|
||||
|
||||
```sh
|
||||
$ consul acl set-agent-token -token "<your token here>" agent "<agent token here>"
|
||||
```
|
||||
|
||||
The data file must contain a valid token.
|
||||
|
||||
```
|
||||
# consul-server-one-token.json
|
||||
{
|
||||
"Token": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
||||
}
|
||||
```
|
||||
|
||||
At this point, every agent that has a token can once
|
||||
again read and write information to Consul, but only for node-related actions.
|
||||
Actions for individual services are not yet allowed.
|
||||
|
||||
~> Note: If you are bootstrapping ACLs on and existing datacenter, remember to
|
||||
update the default policy to `default_policy = deny` and initiate another
|
||||
rolling restart. After applying the token.
|
||||
|
||||
|
||||
## Apply Individual Tokens to the Services
|
||||
|
||||
The token creation and application process for services is similar to agents.
|
||||
Create a policy. Use that policy to create a token. Add the token to the
|
||||
service. Service tokens are necessary for
|
||||
agent anti-entropy, registering and de-registering the service, and
|
||||
registering and de-registering the service's checks.
|
||||
|
||||
Review the [service
|
||||
rules](https://www.consul.io/docs/agent/acl-rules.html#service-rules) before
|
||||
getting started.
|
||||
|
||||
Below is an example service definition that needs a token after bootstrapping
|
||||
the ACL system.
|
||||
|
||||
```json
|
||||
{
|
||||
"service": {
|
||||
"name": "dashboard",
|
||||
"port": 9002,
|
||||
"check": {
|
||||
"id": "dashboard-check",
|
||||
"http": "http://localhost:9002/health",
|
||||
"method": "GET",
|
||||
"interval": "1s",
|
||||
"timeout": "1s"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This service definition should be located in the [configuration
|
||||
directory](https://www.consul.io/docs/agent/options.html#_config_dir) on one of
|
||||
the clients.
|
||||
|
||||
First, create the policy that will grant write privileges to only the
|
||||
"dashboard" service. This means the "dashboard" service can register
|
||||
itself, update it's health checks, and write any of the fields in the [service
|
||||
definition](https://www.consul.io/docs/agent/services.html).
|
||||
|
||||
```sh
|
||||
# dashboard-policy.hcl
|
||||
service "dashboard" {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
Use the policy definition to initiate the policy.
|
||||
|
||||
```sh
|
||||
$ consul acl policy create -name "dashboard-service" -rules @dashboard-policy.hcl
|
||||
```
|
||||
|
||||
Next, create a token with the policy.
|
||||
|
||||
```sh
|
||||
$ consul acl token create -description "Token for Dashboard Service" -policy-name dashboard-service
|
||||
```
|
||||
|
||||
The command will return information about the token, which should include a
|
||||
description and policy information. As usual, save the token to a secure
|
||||
location.
|
||||
|
||||
|
||||
Finally, add the token to the service definition.
|
||||
|
||||
```
|
||||
{
|
||||
"service": {
|
||||
"name": "dashboard",
|
||||
"port": 9002,
|
||||
“token”: “57c5d69a-5f19-469b-0543-12a487eecc66”,
|
||||
"check": {
|
||||
"id": "dashboard-check",
|
||||
"http": "http://localhost:9002/health",
|
||||
"method": "GET",
|
||||
"interval": "1s",
|
||||
"timeout": "1s"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the service is running, you will need to restart it. Unlike with agent
|
||||
tokens, there is no HTTP API endpoint to apply the token directly to the
|
||||
service. If the service is registered with a configuration file, you must
|
||||
also set the token in the configuration file. However, if you register a
|
||||
service with the HTTP API, you can pass the token in the [header](https://www.consul.io/api/index.html#authentication) with
|
||||
`X-Consul-Token` and it will be used by the service.
|
||||
|
||||
If you are using a sidecar proxy, it can inherit the token from the service
|
||||
definition. Alternatively, you can create a separate token.
|
||||
|
||||
## Token for DNS
|
||||
|
||||
Depending on your use case, the token used for DNS may need policy rules for
|
||||
[nodes](https://www.consul.io/docs/agent/acl-rules.html#node-rules),
|
||||
[services](https://www.consul.io/docs/agent/acl-rules.html#service-rules), and
|
||||
[prepared queries](https://www.consul.io/docs/agent/acl-rules.html#prepared-query-rules).
|
||||
You should apply the token to the Consul agent serving DNS requests. When the
|
||||
DNS server makes a request to Consul, it will include the token in the request.
|
||||
Consul can either authorize or revoke the request, depending on the token's
|
||||
privileges. The token creation for DNS is the same three step process you used
|
||||
for agents and services, create a policy, create a token, apply the
|
||||
token.
|
||||
|
||||
Below is an example of a policy that provides read privileges for all services,
|
||||
nodes, and prepared queries.
|
||||
|
||||
```
|
||||
# dns-request-policy.hcl
|
||||
node_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
service_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
# only needed if using prepared queries
|
||||
query_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
First, create the policy.
|
||||
|
||||
```sh
|
||||
$ consul acl policy create -name "dns-requests" -rules @dns-request-policy.hcl
|
||||
```
|
||||
|
||||
Next, create the token.
|
||||
|
||||
```sh
|
||||
$ consul acl token create -description "Token for DNS Requests" -policy-name dns-requests
|
||||
```
|
||||
|
||||
Finally, apply the token to the Consul agent serving DNS request in default token ACL
|
||||
configuration parameter.
|
||||
|
||||
```sh
|
||||
$ consul acl set-agent-token -token "<your token here>" default "<dns token>"
|
||||
```
|
||||
|
||||
The data file must contain a valid token.
|
||||
|
||||
```
|
||||
# dns-token.json
|
||||
{
|
||||
"Token":"5467d69a-5f19-469b-0543-12a487eecc66"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Note, if you have multiple agents serving DNS requests you can use the same
|
||||
policy to create individual tokens for all of them if they are using the same rules.
|
||||
|
||||
|
||||
## Consul KV Tokens
|
||||
|
||||
The process of creating tokens for Consul KV follows the same three step
|
||||
process as nodes and services. First create a policy, then a token, and finally
|
||||
apply or use the token. However, unlike tokens for nodes and services Consul KV
|
||||
has many varied use cases.
|
||||
|
||||
- Services may need to access configuration data in the key-value store.
|
||||
- You may want to store distributed lock information for sessions.
|
||||
- Operators may need access to
|
||||
update configuration values in the key-value store. .
|
||||
|
||||
The [rules for
|
||||
KV](https://www.consul.io/docs/agent/acl-rules.html#key-value-rules) have four
|
||||
policy levels; `deny`, `write`, `read`, and `list`. Let's review several
|
||||
examples of `read` and `write`.
|
||||
|
||||
Depending on the use case, the token will be applied differently. For services
|
||||
you will add the token to the HTTP client. For operators use, the
|
||||
operator will use the token when issuing commands, either with the CLI or API.
|
||||
|
||||
### Recursive Reads
|
||||
|
||||
```
|
||||
key_prefix "redis/" {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, we are allowing any key with the prefix `redis/` to be
|
||||
read. If you issued the command `consul kv get -recurse redis/ -token=<your
|
||||
token> ` you would get a list of key/values for `redis/`.
|
||||
|
||||
This type of policy is good for allowing operators to recursively read
|
||||
configuration parameters stored in the KV. Similarly, a "write" policy with the
|
||||
same prefix would allow you to update any keys that begin with "redis/".
|
||||
|
||||
### Write Privileges for One Key
|
||||
|
||||
```
|
||||
key "dashboard-app" {
|
||||
policy = "write"
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, we are allowing read and write privileges to the
|
||||
dashboard-app key. This allows for `get`, `delete`, and `put` operations.
|
||||
|
||||
This type of token would allow an application to update and read a value in the
|
||||
KV store. It would also be useful for operators who need access to set specific
|
||||
keys.
|
||||
|
||||
### Read Privileges for One Key
|
||||
|
||||
```
|
||||
key "counting-app" {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, we are setting a read privileges for a single key,
|
||||
“counting-app”. This allows for only `get` operations.
|
||||
|
||||
This type of token allows an application to simply read from a key to get the
|
||||
value. This is useful for configuration parameter updates.
|
||||
|
||||
## Consul UI Token
|
||||
|
||||
Once you have bootstrapped the ACL system, access to the UI will be limited.
|
||||
The anonymous token grants UI access if no [default
|
||||
token](https://www.consul.io/docs/agent/options.html#acl_tokens_default) is set
|
||||
on the agents, and all operations will be denied, including viewing nodes and
|
||||
services.
|
||||
|
||||
You can re-enable UI features (with flexible levels of access) by creating and
|
||||
distributing tokens to operators. Once you have a token, you can use it in the
|
||||
UI by adding it to the "ACL" page:
|
||||
|
||||
|
||||
|
||||
After saving a new token, you will be able to see your tokens.
|
||||
|
||||
|
||||
|
||||
The browser stores tokens that you add to the UI. This allows you to distribute
|
||||
different levels of privileges to operators. Like other tokens, it's up to the
|
||||
operator to decide the per-token privileges.
|
||||
|
||||
Below is an example of policy that
|
||||
will allow the operator to have read access to the UI for services, nodes,
|
||||
key/values, and intentions. You need to have "acl = read" to view policies
|
||||
and tokens. Otherwise you will not be able to access the ACL section of the UI,
|
||||
not even to view the token you used to access the UI.
|
||||
|
||||
```
|
||||
# operator-ui.hcl
|
||||
service_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
key_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
node_prefix "" {
|
||||
policy = "read"
|
||||
}
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
In this guide you bootstrapped the ACL system for consul and applied tokens to agents and services. You assigned tokens for DNS, Consul KV, and the Consul UI.
|
||||
|
||||
To learn more about Consul’s security model read the [internals documentation](https://www.consul.io/docs/internals/security.html). You can find commands relating to ACLs in our [reference documentation](https://www.consul.io/docs/commands/acl.html).
|
||||
|
||||
|
||||
Loading…
Reference in New Issue