Bootstrap and Explore Consul's Access Control System
Warning
This guide is intended for use only in development environments because it grants overly-permissive access suitable for getting started. For production guidance, refer instead to the Secure Consul with Access Control Lists guide.
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 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.
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.
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 bootstrap token. For simplicity, you will use the bootstrap token created during the ACL bootstrap for the remainder of the tutorial.
Create the initial management 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.
On the server where the bootstrap
command was issued, the logs should contain
the following log message.
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.
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.
The bootstrap token can also be used in the server configuration file as
the initial_management
token.
Note, the bootstrap token can only be created once, bootstrapping will be disabled after the bootstrap 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.
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.
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.
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.
Add the agent token to the configuration file.
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.
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 on the clients in the configuration directory with the follow options.
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":
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:
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:
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:
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:
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.
With that new policy in place, the DNS lookup will succeed:
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.
With the new policy, create a token.
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
node
write privileges for its own node name, andservice
read privileges for the service prefixes expected to be registered on that client.Anti-entropy syncing requires the ACL agent token to have
service:write
privileges for all services that may be registered with the agent. You should provideservice:write
for 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:write
is the privilege required to assume the identity of a service and so Consul service mesh intentions are only enforceable to the extent that each service instance is unable to gainservice:write
on any other service name. For more details consult the Connect security documentation.