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.
- HCL
- JSON
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 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.
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 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.
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.
- HCL
- JSON
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.
- HCL
- JSON
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
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.
