Consul uses Access Control Lists (ACLs) to secure access to the UI, API, CLI, service communications, and agent communications. Review the following tutorials for securing gossip and RPC communication.
At the core, ACLs operate by grouping rules into policies, then associating one or more policies with a token. The diagram below illustrates this grouping process.
To complete this tutorial, you should have an operational Consul 1.4+ datacenter. You can use a local agent, Vagrant deployment, or Docker containers.
If you are setting up ACLs in Consul version 1.3 and older, review the legacy ACL documentation.
Bootstrapping the ACL system is a multi-step process, this tutorial will cover all the necessary steps.
- Enable ACLs on all the servers.
- Create the initial bootstrap token.
- Create the agent policy.
- Create the agent token.
- Apply the new token to the servers.
- Enable ACLs on the clients and apply the agent token
At the end of this tutorial, there are also several additional and optional steps.
»Enable ACLs on all Consul servers
The first step for bootstrapping the ACL system is to enable ACLs on the Consul servers in the agent configuration. In this example, you are configuring the default policy of "deny", which means the datacenter is in a mode to only allow explicitly named resources, and a down policy of "extend-cache", which means that the agents will ignore token TTLs during an outage.
Note: Consul will load all files in the configuration directory, for the following examples, you can add the configuration
as new files. You can also add them to an existing configuration file, however, you should ensure that the syntax is valid before applying
it to the agent. You can use consul validate to check configuration validity for
both JSON and HCL files.
Add the following HCL configuration, consul-acl.hcl, to the configuration directory on all the servers.
acl {
enabled = true
default_policy = "deny"
down_policy = "extend-cache"
}
The servers will need to be restarted to load the new configuration. Take care to restart the servers one at a time and ensure each server has joined and is operating correctly before restarting another.
If ACLs are enabled correctly, the leader's logs will contain the following warning and info messages.
[INFO] acl: Created the anonymous token
[INFO] consul: ACL bootstrap enabled
[INFO] agent: Synced node info
[WARN] agent: Coordinate update blocked by ACLs
[INFO] acl: initializing acls
[INFO] consul: Created ACL 'global-management' policy
If you do not receive the ACL bootstrap enabled, the anonymous token creation, and the global-management policy creation message in the logs, ACLs have not been properly enabled.
Note, now that you have enabled ACLs, you will need a token to complete any operation. You can't do anything else to the datacenter until you bootstrap and generate the first master token. For simplicity, you will use the master token created during the bootstrap for the remainder of the tutorial.
»Create the bootstrap token
Once ACLs have been enabled, you can bootstrap your first token, called the bootstrap token. The bootstrap token is a management token with unrestricted privileges. It will be shared with all the servers in the quorum, since it will be added to the state store.
$ consul acl bootstrap
AccessorID: edcaacda-b6d0-1954-5939-b5aceaca7c9a
SecretID: 4411f091-a4c9-48e6-0884-1fcb092da1c8
Description: Bootstrap Token (Global Management)
Local: false
Create Time: 2018-12-06 18:03:23.742699239 +0000 UTC
Policies:
00000000-0000-0000-0000-000000000001 - global-management
On the server where the bootstrap command was issued, the logs should contain the following log message.
[INFO] consul.acl: ACL bootstrap completed
[DEBUG] http: Request PUT /v1/acl/bootstrap (2.347965ms) from=127.0.0.1:40566
Since ACLs have been enabled, you will need to use a token to complete any additional operations. For example, even checking the member list will require a token.
$ consul members -token "4411f091-a4c9-48e6-0884-1fcb092da1c8"
Node Address Status Type Build Protocol DC Segment
fox 172.20.20.10:8301 alive server 1.4.0 2 kc <all>
bear 172.20.20.11:8301 alive server 1.4.0 2 kc <all>
wolf 172.20.20.12:8301 alive server 1.4.0 2 kc <all>
Note using the token on the command line with the -token flag is not
recommended, instead you can set it as an environment variable once.
$ export CONSUL_HTTP_TOKEN=4411f091-a4c9-48e6-0884-1fcb092da1c8
The bootstrap token can also be used in the server configuration file as
the master token.
Note, the bootstrap token can only be created once, bootstrapping will be disabled after the master token was created. Once the ACL system is bootstrapped, ACL tokens can be managed through the ACL API.
»Create an agent token policy
Before creating a new token, you will need to create its associated policy. A policy is a set of rules that can be used to specify granular privileges. To learn more about rules, read the ACL rule specification documentation.
First create a policy file, agent-policy.hcl, and add the HCL stanzas below. Note,
policy files should not be added to the Consul agent configuration directory.
# agent-policy.hcl contains the following:
node_prefix "" {
policy = "write"
}
service_prefix "" {
policy = "read"
}
This policy will allow all nodes to be registered and accessed and any service to be read. Note, this simple policy is not recommended in production. It is best practice to create separate node policies and tokens for each node in the datacenter with an exact-match node rule.
You only need to create one policy and can do this on any of the servers. If you have not set the
CONSUL_HTTP_TOKEN environment variable to the bootstrap token, refer to the previous step.
$ consul acl policy create -name "agent-token" -description "Agent Token Policy" -rules @agent-policy.hcl
ID: 5102b76c-6058-9fe7-82a4-315c353eb7f7
Name: agent-policy
Description: Agent Token Policy
Datacenters:
Rules:
node_prefix "" {
policy = "write"
}
service_prefix "" {
policy = "read"
}
The returned value is the newly-created policy that you can now use when creating our agent token.
»Create a Consul agent token
Using the newly created policy, you can create an agent token. Again you can complete this process on any of the servers.
For this tutorial, all agents will share the same token. Note, the SecretID is the token used to authenticate API and CLI commands.
$ consul acl token create -description "Agent Token" -policy-name "agent-token"
AccessorID: 499ab022-27f2-acb8-4e05-5a01fff3b1d1
SecretID: da666809-98ca-0e94-a99c-893c4bf5f9eb
Description: Agent Token
Local: false
Create Time: 2018-10-19 14:23:40.816899 -0400 EDT
Policies:
fcd68580-c566-2bd2-891f-336eadc02357 - agent-token
»Add the agent token to all Consul servers
Your final step for configuring the servers is to assign the token to all of the Consul servers via the configuration file and reload the Consul service one last time.
In the consul-acl.hcl configuration, add the agent token.
primary_datacenter = "dc1"
acl {
enabled = true
default_policy = "deny"
down_policy = "extend-cache"
tokens {
"agent" = "da666809-98ca-0e94-a99c-893c4bf5f9eb"
}
}
Note: In Consul version 1.4.2 and older any ACL updates in the agent configuration file will require a full restart of the Consul service.
At this point the coordinate warning should stop being written to the server's logs, however, you should be able to verify that the node information remains in sync.
2018/12/11 15:34:20 [DEBUG] agent: Node info in sync
It is important to ensure the servers are configured properly, before enable ACLs on the clients. This will reduce any duplicate work and troubleshooting, if there is a misconfiguration.
»Ensure the ACL system is configured properly
Before configuring the clients, check that the servers are healthy and have an assigned TaggedAddresses. You can use the consul catalog
command and ACL Troubleshooting tutorial to check for a TaggedAddresses.
Finally, if you encounter issues that are unresolvable, or misplace the bootstrap token, you can reset the ACL system by updating the index. Follow the reset procedure in the ACL Troubleshooting tutorial.
After resetting the ACL system you can start again at Step 2.
»Enable ACLs on Consul clients
Since ACL enforcement also occurs on the Consul clients, you need to also restart them with a configuration file that enables ACLs. You can use the same ACL agent token that you created for the servers. The same token can be used because you did not specify any node or service prefixes.
Create an agent configuration file, consul-acl.hcl on the clients in the configuration directory with the follow
options.
acl {
enabled = true
default_policy = "deny"
down_policy = "extend-cache"
tokens {
"agent" = "da666809-98ca-0e94-a99c-893c4bf5f9eb"
}
}
To ensure the agents are configured correctly, you can again use the /catalog endpoint.
»Additional ACL configuration
Now that the nodes have been configured to use ACLs, you can configure the CLI, UI, and nodes to use specific tokens. All of the following steps are optional examples. In your own environment you will likely need to create more fine grained policies.
»Configure the anonymous token (Optional)
The anonymous token is created during the bootstrap process, consul acl bootstrap. It is implicitly used if no token is supplied. In this section you will update the existing token with a newly created policy.
At this point ACLs are bootstrapped with ACL agent tokens configured, but there are no
other policies set up. Even basic operations like consul members will be restricted
by the ACL default policy of "deny":
$ consul members
You will not receive an error, since the ACL has filtered the list based on
privileges. Since you did not present a token, you are using the anonymous
token. This token, by default, does not provide access to any Consul objects.
If you supply the token you created above, you will receive a listing of
nodes. That token has write privileges to an empty node prefix, meaning it has
access to all nodes:
$ CONSUL_HTTP_TOKEN=4411f091-a4c9-48e6-0884-1fcb092da1c8 consul members
Node Address Status Type Build Protocol DC Segment
fox 172.20.20.10:8301 alive server 1.4.0 2 kc <all>
bear 172.20.20.11:8301 alive server 1.4.0 2 kc <all>
wolf 172.20.20.12:8301 alive server 1.4.0 2 kc <all>
It is common in many environments to allow listing of all nodes, even without a
token. The policies associated with the special anonymous token can be updated to
configure Consul's behavior when no token is supplied. The anonymous token is managed
like any other ACL token, except that anonymous is used for the ID. In this example,
you will give the anonymous token read privileges for all nodes:
$ consul acl policy create -name 'list-all-nodes' -rules 'node_prefix "" { policy = "read" }'
ID: e96d0a33-28b4-d0dd-9b3f-08301700ac72
Name: list-all-nodes
Description:
Datacenters:
Rules:
node_prefix "" { policy = "read" }
$ consul acl token update -id 00000000-0000-0000-0000-000000000002 -policy-name list-all-nodes -description "Anonymous Token - Can List Nodes"
Token updated successfully.
AccessorID: 00000000-0000-0000-0000-000000000002
SecretID: anonymous
Description: Anonymous Token - Can List Nodes
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Hash: ee4638968d9061647ac8c3c99e9d37bfdd2af4d1eaa07a7b5f80af0389460948
Create Index: 5
Modify Index: 38
Policies:
e96d0a33-28b4-d0dd-9b3f-08301700ac72 - list-all-nodes
The anonymous token is implicitly used if no token is supplied, so now you can run
consul members without supplying a token and you will receive the list of nodes:
$ consul members
Node Address Status Type Build Protocol DC Segment
fox 172.20.20.10:8301 alive server 1.4.0 2 kc <all>
bear 172.20.20.11:8301 alive server 1.4.0 2 kc <all>
wolf 172.20.20.12:8301 alive server 1.4.0 2 kc <all>
The anonymous token is also used for DNS lookups since there is no way to pass a token as part of a DNS request. Here's an example lookup for the "consul" service:
$ dig @127.0.0.1 -p 8600 consul.service.consul
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 9648
;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 0
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;consul.service.consul. IN A
;; AUTHORITY SECTION:
consul. 0 IN SOA ns.consul. postmaster.consul. 1499584110 3600 600 86400 0
Now you get an NXDOMAIN error because the anonymous token doesn't have access to the
"consul" service. Update the anonymous token's policy to allow for service reads of the "consul" service.
$ consul acl policy create -name 'service-consul-read' -rules 'service "consul" { policy = "read" }'
ID: 3c93f536-5748-2163-bb66-088d517273ba
Name: service-consul-read
Description:
Datacenters:
Rules:
service "consul" { policy = "read" }
$ consul acl token update -id 00000000-0000-0000-0000-000000000002 --merge-policies -description "Anonymous Token - Can List Nodes" -policy-name service-consul-read
Token updated successfully.
AccessorID: 00000000-0000-0000-0000-000000000002
SecretID: anonymous
Description: Anonymous Token - Can List Nodes
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Hash: 2c641c4f73158ef6d62f6467c68d751fccd4db9df99b235373e25934f9bbd939
Create Index: 5
Modify Index: 43
Policies:
e96d0a33-28b4-d0dd-9b3f-08301700ac72 - list-all-nodes
3c93f536-5748-2163-bb66-088d517273ba - service-consul-read
With that new policy in place, the DNS lookup will succeed:
$ dig @127.0.0.1 -p 8600 consul.service.consul
; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 46006
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; WARNING: recursion requested but not available
;; QUESTION SECTION:
;consul.service.consul. IN A
;; ANSWER SECTION:
consul.service.consul. 0 IN A 127.0.0.1
The next section shows an alternative to the anonymous token.
»Set agent-specific default tokens (optional)
An alternative to the anonymous token is the acl.tokens.default
configuration item. When a request is made to a particular Consul agent and no token is
supplied, the acl.tokens.default will be used for the token, instead of being left empty which would normally invoke the anonymous token.
This behaves very similarly to the anonymous token, but can be configured differently on each agent, if desired. For example, this allows more fine grained control of what DNS requests a given agent can service or can give the agent read access to some key-value store prefixes by default.
If using acl.tokens.default, then it's likely the anonymous token will have a more restrictive policy than shown in these examples.
»Create tokens for the UI (Optional)
If you utilize the Consul UI with a restrictive ACL policy, as above, the UI will not function fully using the anonymous ACL token. It is recommended that a UI-specific ACL token is used, which can be set in the UI during the web browser session to authenticate the interface.
First create the new policy.
$ consul acl policy create -name "ui-policy" \
-description "Necessary permissions for UI functionality" \
-rules 'key_prefix"" { policy = "write" } node_prefix "" { policy = "read" } service_prefix "" { policy = "read" }'
ID: 9cb99b2b-3c20-81d4-a7c0-9ffdc2fbf08a
Name: ui-policy
Description: Necessary permissions for UI functionality
Datacenters:
Rules:
key_prefix "" { policy = "write" } node_prefix "" { policy = "read" } service_prefix "" { policy = "read" }
With the new policy, create a token.
$ consul acl token create -description "UI Token" -policy-name "ui-policy"
AccessorID: 56e605cf-a6f9-5f9d-5c08-a0e1323cf016
SecretID: 117842b6-6208-446a-0d1e-daf93854857d
Description: UI Token
Local: false
Create Time: 2018-10-19 14:55:44.254063 -0400 EDT
Policies:
9cb99b2b-3c20-81d4-a7c0-9ffdc2fbf08a - ui-policy
The token can then be set on the "ACL" page of the UI.
Note, in this example, you have also given full write access to the KV through the UI.
»Next steps
The ACL API can be used to create tokens for applications specific to their intended use and to create more specific ACL agent tokens for each agent's expected role. Now that you have bootstrapped ACLs, learn more about ACL rules
»Notes on security
In this tutorial you configured a basic ACL environment with the ability to read all nodes
by default, but with limited access to discover only the "consul" service.
Consider reading the ACL System documentation for information about tokens, policies, and more.
If your environment has stricter security requirements, note the following and consider these additional recommendations.
In this tutorial you added the agent token to the configuration file. This means the tokens are now saved on disk. If this is a security concern, tokens can be added to agents using the Consul CLI. However, this process is more complicated and takes additional care. To learn how to set tokens on with the Consul CLI refer to the Securing Consul with ACLs tutorial
It is recommended that each client get an ACL agent token with only
nodewrite privileges for its own node name, andserviceread privileges for the service prefixes expected to be registered on that client.Anti-entropy syncing requires the ACL agent token to have
service:writeprivileges for all services that may be registered with the agent. You should provideservice:writefor each separate service via a separate token that is used when registering via the API, or provided along with the registration in the configuration file. Note thatservice:writeis the privilege required to assume the identity of a service and so Consul Connect service mesh intentions are only enforceable to the extent that each service instance is unable to gainservice:writeon any other service name. For more details consult the Connect security documentation.