consul/website/source/docs/acl/acl-system.html.md

layout	page_title	sidebar_current	description
docs	ACL System	docs-acl-system	Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL system is a Capability-based system that relies on tokens which can have fine grained rules applied to them. It is very similar to AWS IAM in many ways.

-> 1.4.0 and later: This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is here

ACL System

Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL is Capability-based, relying on tokens which are associated with policies to determine which fine grained rules can be applied. Consul's capability based ACL system is very similar to the design of AWS IAM.

To learn how to setup the ACL system on an existing Consul datacenter, use the Bootstrapping The ACL System guide.

ACL System Overview

The ACL system is designed to be easy to use and fast to enforce while providing administrative insight. At the highest level, there are two major components to the ACL system:

• ACL Policies - Policies allow the grouping of a set of rules into a logical unit that can be reused and linked with many tokens.

• ACL Tokens - Requests to Consul are authorized by using bearer token. Each ACL token has a public Accessor ID which is used to name a token, and a Secret ID which is used as the bearer token used to make requests to Consul.

For many scenarios policies and tokens are sufficient, but more advanced setups may benefit from additional components in the ACL system:

• ACL Roles - Roles allow for the grouping of a set of policies and service identities into a reusable higher-level entity that can be applied to many tokens. (Added in Consul 1.5.0)

• ACL Service Identities - Service identities are a policy template for expressing a link to a policy suitable for use in Consul Connect. At authorization time this acts like an additional policy was attached, the contents of which are described further below. These are directly attached to tokens and roles and are not independently configured. (Added in Consul 1.5.0)

• ACL Auth Methods and Binding Rules - To learn more about these topics, see the dedicated auth methods documentation page.

ACL tokens, policies, roles, auth methods, and binding rules are managed by Consul operators via Consul's ACL API, ACL CLI, or systems like HashiCorp's Vault.

If the ACL system becomes inoperable, you can follow the reset procedure at any time.

ACL Policies

An ACL policy is a named set of rules and is composed of the following elements:

• ID - The policy's auto-generated public identifier.
• Name - A unique meaningful name for the policy.
• Description - A human readable description of the policy. (Optional)
• Rules - Set of rules granting or denying permissions. See the Rule Specification documentation for more details.
• Datacenters - A list of datacenters the policy is valid within.
• Namespace - Enterprise Only - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)

-> Consul Enterprise Namespacing - Rules defined in a policy in any namespace other than default will be restricted to being able to grant a subset of the overall privileges and only affecting that single namespace.

Builtin Policies

• Global Management - Grants unrestricted privileges to any token that uses it. When created it will be named global-management and will be assigned the reserved ID of 00000000-0000-0000-0000-000000000001. This policy can be renamed but modification of anything else including the rule set and datacenter scoping will be prevented by Consul.

• Namespace Management - Enterprise Only - Every namespace created will have a policy injected with the name namespace-management. This policy gets injected with a randomized UUID and may be managed like any other user-defined policy within the Namespace. (Added in Consul Enterprise 1.7.0)

ACL Service Identities

-> Added in Consul 1.5.0

An ACL service identity is an ACL policy template for expressing a link to a policy suitable for use in Consul Connect. They are usable on both tokens and roles and are composed of the following elements:

• Service Name - The name of the service.
• Datacenters - A list of datacenters the effective policy is valid within. (Optional)

Services participating in the service mesh will need privileges to both be discovered and to discover other healthy service instances. Suitable policies tend to all look nearly identical so a service identity is a policy template to aid in avoiding boilerplate policy creation.

During the authorization process, the configured service identity is automatically applied as a policy with the following preconfigured ACL rules:

// Allow the service and its sidecar proxy to register into the catalog.
service "<Service Name>" {
	policy = "write"
}
service "<Service Name>-sidecar-proxy" {
	policy = "write"
}

// Allow for any potential upstreams to be resolved.
service_prefix "" {
	policy = "read"
}
node_prefix "" {
	policy = "read"
}

The API documentation for roles has some examples of using a service identity.

-> Consul Enterprise Namespacing - Service Identity rules will be scoped to the single namespace that the corresponding ACL Token or Role resides within.

ACL Roles

-> Added in Consul 1.5.0

An ACL role is a named set of policies and service identities and is composed of the following elements:

• ID - The role's auto-generated public identifier.
• Name - A unique meaningful name for the role.
• Description - A human readable description of the role. (Optional)
• Policy Set - The list of policies that are applicable for the role.
• Service Identity Set - The list of service identities that are applicable for the role.
• Namespace - Enterprise Only - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)

-> Consul Enterprise Namespacing - Roles may only link to policies defined in the same namespace as the role itself.

ACL Tokens

ACL tokens are used to determine if the caller is authorized to perform an action. An ACL token is composed of the following elements:

• Accessor ID - The token's public identifier.
• Secret ID -The bearer token used when making requests to Consul.
• Description - A human readable description of the token. (Optional)
• Policy Set - The list of policies that are applicable for the token.
• Role Set - The list of roles that are applicable for the token. (Added in Consul 1.5.0)
• Service Identity Set - The list of service identities that are applicable for the token. (Added in Consul 1.5.0)
• Locality - Indicates whether the token should be local to the datacenter it was created within or created in the primary datacenter and globally replicated.
• Expiration Time - The time at which this token is revoked. (Optional; Added in Consul 1.5.0)
• Namespace - Enterprise Only - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)

-> Consul Enterprise Namespacing - Tokens may only link to policies and roles defined in the same namespace as the token itself.

Builtin Tokens

During cluster bootstrapping when ACLs are enabled both the special anonymous and the master token will be injected.

• Anonymous Token - The anonymous token is used when a request is made to Consul without specifying a bearer token. The anonymous token's description and policies may be updated but Consul will prevent this token's deletion. When created, it will be assigned 00000000-0000-0000-0000-000000000002 for its Accessor ID and anonymous for its Secret ID.

• Master Token - When a master token is present within the Consul configuration, it is created and will be linked With the builtin Global Management policy giving it unrestricted privileges. The master token is created with the Secret ID set to the value of the configuration entry.

Authorization

The token Secret ID is passed along with each RPC request to the servers. Consul's HTTP endpoints can accept tokens via the token query string parameter, the X-Consul-Token request header, or an RFC6750 authorization bearer token. Consul's CLI commands can accept tokens via the token argument, or the CONSUL_HTTP_TOKEN environment variable. The CLI commands can also accept token values stored in files with the token-file argument, or the CONSUL_HTTP_TOKEN_FILE environment variable.

If no token is provided for an HTTP request then Consul will use the default ACL token if it has been configured. If no default ACL token was configured then the anonymous token will be used.

ACL Rules and Scope

The rules from all policies, roles, and service identities linked with a token are combined to form that token's effective rule set. Policy rules can be defined in either a whitelist or blacklist mode depending on the configuration of acl_default_policy. If the default policy is to "deny" access to all resources, then policy rules can be set to whitelist access to specific resources. Conversely, if the default policy is “allow” then policy rules can be used to explicitly deny access to resources.

The following table summarizes the ACL resources that are available for constructing rules:

Resource	Scope
acl	Operations for managing the ACL system ACL API
agent	Utility operations in the Agent API, other than service and check registration
event	Listing and firing events in the Event API
key	Key/value store operations in the KV Store API
keyring	Keyring operations in the Keyring API
node	Node-level catalog operations in the Catalog API, Health API, Prepared Query API, Network Coordinate API, and Agent API
operator	Cluster-level operations in the Operator API, other than the Keyring API
query	Prepared query operations in the Prepared Query API
service	Service-level catalog operations in the Catalog API, Health API, Prepared Query API, and Agent API
session	Session operations in the Session API

Since Consul snapshots actually contain ACL tokens, the Snapshot API requires a token with "write" privileges for the ACL system.

The following resources are not covered by ACL policies:

1. The Status API is used by servers when bootstrapping and exposes basic IP and port information about the servers, and does not allow modification of any state.

2. The datacenter listing operation of the Catalog API similarly exposes the names of known Consul datacenters, and does not allow modification of any state.

3. The connect CA roots endpoint exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul.

Constructing rules from these policies is covered in detail on the ACL Rules page.

-> Consul Enterprise Namespacing - In addition to directly linked policies, roles and service identities, Consul Enterprise will include the ACL policies and roles defined in the Namespaces definition. (Added in Consul Enterprise 1.7.0)

Configuring ACLs

ACLs are configured using several different configuration options. These are marked as to whether they are set on servers, clients, or both.

Configuration Option	Servers	Clients	Purpose
acl.enabled	REQUIRED	REQUIRED	Controls whether ACLs are enabled
acl.default_policy	OPTIONAL	N/A	Determines whitelist or blacklist mode
acl.down_policy	OPTIONAL	OPTIONAL	Determines what to do when the remote token or policy resolution fails
acl.role_ttl	OPTIONAL	OPTIONAL	Determines time-to-live for cached ACL Roles
acl.policy_ttl	OPTIONAL	OPTIONAL	Determines time-to-live for cached ACL Policies
acl.token_ttl	OPTIONAL	OPTIONAL	Determines time-to-live for cached ACL Tokens

A number of special tokens can also be configured which allow for bootstrapping the ACL system, or accessing Consul in special situations:

Special Token	Servers	Clients	Purpose
acl.tokens.agent_master	OPTIONAL	OPTIONAL	Special token that can be used to access Agent API when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the ACL Agent Master Token section for more details
acl.tokens.agent	OPTIONAL	OPTIONAL	Special token that is used for an agent's internal operations, see the ACL Agent Token section for more details
acl.tokens.master	OPTIONAL	N/A	Special token used to bootstrap the ACL system, see the Bootstrapping ACLs guide for more details
acl.tokens.default	OPTIONAL	OPTIONAL	Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents

All of these tokens except the master token can all be introduced or updated via the /v1/agent/token API.

ACL Agent Master Token

Since the acl.tokens.agent_master is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it

agent "<node name of agent>" {
  policy = "write"
}
node_prefix "" {
  policy = "read"
}

ACL Agent Token

The acl.tokens.agent is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the acl.tokens.default, though if the acl.tokens.agent_token isn't configured the acl.tokens.default will be used. The ACL agent token is used for the following operations by the agent:

1. Updating the agent's node entry using the Catalog API, including updating its node metadata, tagged addresses, and network coordinates
2. Performing anti-entropy syncing, in particular reading the node metadata and services registered with the catalog
3. Reading and writing the special _rexec section of the KV store when executing consul exec commands

Here's an example policy sufficient to accomplish the above for a node called mynode:

node "mynode" {
  policy = "write"
}
service_prefix "" {
  policy = "read"
}
key_prefix "_rexec" {
  policy = "write"
}

The service_prefix policy needs read access for any services that can be registered on the agent. If remote exec is disabled, the default, then the key_prefix policy can be omitted.

Next Steps

Setup ACLs with the Bootstrapping the ACL System guide or continue reading about ACL rules.