Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท ACLs and Security

The Consul ACL System: Overview and Bootstrap

Understand the Consul ACL system: tokens, policies, roles, default policy, enabling ACLs on servers and clients, bootstrapping the first management token.

A fresh Consul cluster is open: anyone who can reach the HTTP API can read the catalog, write the key-value store and register services. That is fine on a laptop and unacceptable in production. The ACL (access control list) system closes it. Every request must carry a token, and the token's policies say what it may do.

The product cannot run on this site. Configuration and commands are shown read-only, and the runnable examples are stand-ins that model the rules.

The four building blocks

Concept What it is
Token A credential with an AccessorID (public ID used in listings) and a SecretID (the secret you send)
Policy A named set of rules, written in HCL, that grants permissions
Role A named bundle of policies (and identities) that you attach to tokens
Identity A template for common cases: a service identity or node identity generates the right policy for you

A token receives its permissions from the union of its policies, roles and identities. Rules only add permissions (apart from explicit deny), so combining policies never reduces access unless a rule says deny.

flowchart LR
  T["Token (SecretID)"] --> P1["Policy: kv-read"]
  T --> R["Role: web-team"]
  R --> P2["Policy: web-service"]
  R --> SI["Service identity: web"]
  T --> NI["Node identity: node-1"]

A token's effective permissions are everything granted by its policies, roles and identities.

Default policy

ACL behavior starts with the default policy:

  • allow (the default when ACLs are enabled without more settings): everything not denied is allowed. This is a denylist model, only useful during rollout.
  • deny: everything not allowed is refused. This is an allowlist model, the setting for production.

Starting from deny is safer because a forgotten rule fails closed.

Enabling ACLs

Enable them on servers first, then clients. A server configuration:

HCL
datacenter = "dc1"
server     = true
data_dir   = "/opt/consul"

acl {
  enabled                  = true
  default_policy           = "deny"
  enable_token_persistence = true
}

Restart the servers one at a time (a rolling restart, so the cluster keeps quorum). Client agents need the same acl block, but cannot do anything useful until they receive a token. The setting enable_token_persistence = true saves tokens set through the API so they survive restarts.

Turning on default_policy = "deny" before tokens exist locks you out, including the agents themselves. For a live cluster, a gentler path is to enable ACLs with default_policy = "allow", create tokens and roll them out, then flip to deny.

Bootstrapping

With ACLs on, there is no token yet, so Consul provides a one-time bootstrap that creates the first token, with the built-in global-management policy:

Terminal
consul acl bootstrap

The output shows an AccessorID and SecretID. Save the SecretID in a password manager or Vault immediately. It is the only management credential and cannot be recovered (you can only reset the bootstrap). Run the command a second time and it fails. If you truly lose it, Consul tells you which reset index to write to a file in the server data directory to allow bootstrapping again.

Then export it for your shell:

Terminal
export CONSUL_HTTP_TOKEN="<the SecretID>"
consul members

The CLI also accepts -token, -token-file, and HTTP clients send the secret in the X-Consul-Token header (or Authorization: Bearer).

The bootstrap token has unrestricted power. Use it to create narrower tokens for people, agents and services, then lock it away. Do not put it in application configuration.

Who needs a token?

  • Operators need tokens for the CLI and UI. The UI asks for a token on login.
  • Agents need an agent token (to register their node and update their own state) and optionally a default token for requests that arrive without one.
  • Services need a token to register themselves and sidecar proxies need one to read the catalog and certificates.
  • Anonymous requests use the built-in anonymous token, whose permissions you control. With default deny it can do nothing, except what you add, for instance DNS lookups of services, which have no way to send a token.
Python Stand-in: default policy decides unmatched requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With allow as the default, billing and secrets/ are wide open because nobody wrote a rule for them. With deny they are blocked. That is the argument for deny.

Tokens in practice

Terminal
consul acl token list
consul acl token read -id <AccessorID>
consul acl token delete -id <AccessorID>
consul acl policy list
consul acl role list

Tokens can have a ExpirationTime or ExpirationTTL for temporary access, and each token or policy can be limited to a set of datacenters. A local token exists only in one datacenter, while the default global tokens replicate from the primary datacenter to others (see WAN federation). Replication needs a token that can read ACLs in the primary datacenter.

Common mistakes

  • Enabling deny on clients before servers. Servers must hold the ACL data first.
  • Forgetting DNS. Without an anonymous-token rule allowing service and node reads, dig web.service.consul returns nothing.
  • Sharing one management token. Use one narrow token per application and per person for audit and revocation.
  • Leaking secrets in logs and shell history. Use -token-file or environment variables, never put a secret in a URL.
Python Stand-in: a token as the union of its policies

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which pair identifies a token?

    The AccessorID appears in listings and logs; the SecretID is what you send in requests and must be protected.
  2. 2. Why is default_policy = deny the production recommendation?

    An allowlist model means a missing rule results in refusal rather than accidental access.
  3. 3. What does consul acl bootstrap do?

    It creates the initial global-management token. A second run fails unless the bootstrap is reset.
  4. 4. A request arrives with no token. Which permissions apply?

    Tokenless requests use the anonymous token, which you configure (for instance to allow DNS lookups).
  5. 5. In which order should you enable ACLs on a running cluster?

    Servers store the ACL data and must be ready first; restart one at a time to keep quorum.

Summary

  • Tokens carry permissions from policies, roles and identities; rules add access, and deny rules override it.
  • Use default_policy = "deny" in production; enable on servers first, then clients.
  • consul acl bootstrap creates the single initial management token: store it safely and create narrower tokens.
  • The anonymous token controls tokenless requests such as DNS.

Next: ACL Rules and Policies