The Bootstrapping the ACL System 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, you will learn how to create tokens with minimum privileges for:

• Servers and Clients
• Services
• DNS
• Consul KV
• Consul UI

» 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 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
    } 
} 

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

» Create the Initial Bootstrap Token

To create the initial bootstrap token, use the acl bootstrap command on one of the servers.

$ consul acl bootstrap 

The output gives you important information about the token, including the associated policy global-management and SecretID.

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.

$ 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.
2. Create the token with the newly created policy.
3. 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. 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.

$ 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.

$ 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.

» 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 for example of setting the token in the agent configuration file.

$ 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.

» 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 before getting started.

Below is an example service definition that needs a token after bootstrapping the ACL system.

{ 
  "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 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.

# dashboard-policy.hcl
service "dashboard" { 
    policy = "write" 
} 

Use the policy definition to initiate the policy.

$ consul acl policy create -name "dashboard-service" -rules @dashboard-policy.hcl 

Next, create a token with the policy.

$ 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 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, services, and prepared queries. 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.

$ consul acl policy create -name "dns-requests" -rules @dns-request-policy.hcl 

Next, create the token.

$ 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.

$ 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 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 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. You can find commands relating to ACLs in our reference documentation.