Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท ACLs and Security

Consul ACL Tokens, Roles and Identities

Create and manage Consul ACL tokens, group policies into roles, use service and node identities, set agent tokens and understand auth methods and token expiry.

Policies describe permissions; tokens are how clients use them. This lesson covers creating tokens, grouping policies into roles, using service and node identities that generate policies for you, configuring the tokens an agent needs and replacing long-lived secrets with auth methods.

The product cannot run on this site. Commands are shown read-only and the runnable examples are stand-in models.

Creating tokens

Terminal
consul acl token create \
  -description "web service" \
  -policy-name web-service \
  -expires-ttl 720h

The output lists the AccessorID, the SecretID, the policies and the expiration time. Useful options:

Option Effect
-policy-name / -policy-id Attach a policy (repeatable)
-role-name Attach a role (repeatable)
-service-identity NAME:dc1,dc2 Attach a service identity
-node-identity NAME:dc1 Attach a node identity
-expires-ttl 24h / -expiration-time Make the token temporary
-local Keep the token only in this datacenter

Management commands: consul acl token list, token read -id, token update -id, token clone -id and token delete -id. consul acl token read -self shows the token currently in use.

Prefer short expirations for people and automation, and rotate secrets by creating the new token, deploying it, then deleting the old one.

Roles

A role bundles policies so you can say "the web team" once:

Terminal
consul acl role create -name web-team \
  -policy-name web-service \
  -policy-name kv-read

consul acl token create -description "alice" -role-name web-team

Change the role's policy list later and every token that holds the role changes with it, with no token re-issue. This is the main reason to use roles for people and environments.

Service identities

Writing the "register my service and read the catalog" policy by hand for every service gets old. A service identity is a template: give it a service name and optional datacenters, and Consul creates the equivalent policy automatically.

Terminal
consul acl token create \
  -description "web" \
  -service-identity web

The generated rules give the token:

  • service "web" and service "web-sidecar-proxy" with write,
  • service_prefix "" with read and node_prefix "" with read, so the sidecar can discover upstreams.

That is exactly what a mesh service needs and nothing more. Roles can include service identities too.

Node identities

A node identity does the same for a node: -node-identity node-1:dc1 grants node "node-1" write and service_prefix "" read. It is meant for agents, so a client's token cannot register any other node.

Python Stand-in: expand a service identity into rules

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.

Tokens an agent needs

An agent uses several tokens, each for a different job:

HCL
acl {
  enabled        = true
  default_policy = "deny"

  tokens {
    agent   = "<agent token>"
    default = "<default token>"
  }
}
  • agent: used for the agent's own internal operations: anti-entropy sync of the node and its services, and so on. It needs a node identity (or node:write for its name and service_prefix read).
  • default: used when a request to this agent carries no token. Many teams leave it unset so unauthenticated calls fail.
  • replication: used by secondary datacenters to replicate ACLs from the primary.
  • config_file_service_registration: registers services defined in agent configuration files.

Rather than writing secrets in the file, set them at runtime without a restart:

Terminal
consul acl set-agent-token agent "<secret>"
consul acl set-agent-token default "<secret>"

With enable_token_persistence = true the values survive restarts.

Tokens for applications

Applications read their token from an environment variable or file and send it as a header:

Terminal
curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  http://127.0.0.1:8500/v1/catalog/services

A sidecar launched with consul connect envoy -sidecar-for web -token-file /etc/consul.d/web.token uses the file's secret. Restrict the file to the service account (mode 0600).

Auth methods and binding rules

Distributing static secrets does not scale. An auth method lets a workload log in with a credential it already has and receive a short-lived Consul token:

  • Kubernetes (service account JWT), JWT/OIDC (identity provider tokens), AWS IAM, Azure and others.
  • A binding rule maps attributes of the login (for example the Kubernetes service account name) to a service identity, node identity or role, so each pod gets a token for its own service automatically.
Terminal
consul login -method k8s -bearer-token-file /var/run/secrets/kubernetes.io/serviceaccount/token

Tokens from consul login expire, and consul logout revokes them. The auth method must be configured by an administrator beforehand and, in a multi-datacenter setup, in the primary datacenter.

Python Stand-in: binding rule maps a login to an identity

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.

Operating tokens safely

  • Give every token a description that says who or what uses it.
  • Review consul acl token list for tokens with no expiry.
  • Keep management tokens out of automation; use roles with narrow rights.
  • If a secret leaks, delete the token by its accessor and create a new one.
  • Tokens are replicated (global) or local; prefer -local for datacenter-specific workloads.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a role add compared with attaching policies directly to tokens?

    Roles centralize policy lists, so one change reaches all tokens holding the role.
  2. 2. What does -service-identity web grant?

    The template generates just the permissions a mesh service needs.
  3. 3. Which agent token is used for the agent's own sync with the servers?

    The agent token authenticates the agent's internal operations such as registering its node and services.
  4. 4. What is the advantage of an auth method with binding rules?

    Logins such as Kubernetes JWTs are exchanged for expiring tokens mapped to identities by binding rules.
  5. 5. How can you change an agent's token without restarting it?

    The set-agent-token command updates the running agent; persistence keeps it across restarts.

Summary

  • Create tokens with policies, roles or identities; give temporary credentials an expiry and a clear description.
  • Roles bundle policies; service and node identities generate the right rules for mesh services and agents.
  • Agents use agent, default and replication tokens, settable at runtime with consul acl set-agent-token.
  • Auth methods with binding rules replace static secrets with short-lived tokens.

Next: Gossip Encryption and TLS