1--- 2layout: docs 3page_title: ACL System 4sidebar_title: ACL System 5description: >- 6 Consul provides an optional Access Control List (ACL) system which can be used 7 to control access to data and APIs. The ACL system is a Capability-based 8 system that relies on tokens which can have fine grained rules applied to 9 them. It is very similar to AWS IAM in many ways. 10--- 11 12# ACL System 13 14-> **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](/docs/acl/acl-legacy) 15 16Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. 17The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which 18are associated with policies to determine which fine grained rules can be applied. Consul's capability based 19ACL system is very similar to the design of [AWS IAM](https://aws.amazon.com/iam/). 20 21To learn how to setup the ACL system on an existing Consul datacenter, use the [Bootstrapping The ACL System guide](https://learn.hashicorp.com/consul/day-0/acl-guide?utm_source=consul.io&utm_medium=docs). 22 23## ACL System Overview 24 25The ACL system is designed to be easy to use and fast to enforce while providing administrative insight. 26At the highest level, there are two major components to the ACL system: 27 28- **ACL Policies** - Policies allow the grouping of a set of rules into a logical unit that can be reused and linked with 29 many tokens. 30 31- **ACL Tokens** - Requests to Consul are authorized by using bearer token. Each ACL token has a public 32 Accessor ID which is used to name a token, and a Secret ID which is used as the bearer token used to 33 make requests to Consul. 34 35For many scenarios policies and tokens are sufficient, but more advanced setups 36may benefit from additional components in the ACL system: 37 38- **ACL Roles** - Roles allow for the grouping of a set of policies and service 39 identities into a reusable higher-level entity that can be applied to many 40 tokens. (Added in Consul 1.5.0) 41 42- **ACL Service Identities** - Service identities are a policy template for 43 expressing a link to a policy suitable for use in [Consul 44 Connect](/docs/connect). At authorization time this acts like an 45 additional policy was attached, the contents of which are described further 46 below. These are directly attached to tokens and roles and are not 47 independently configured. (Added in Consul 1.5.0) 48 49- **ACL Node Identities** - Node identities are a policy template for 50 expressing a link to a policy suitable for use as an [Consul `agent` token 51 ](/docs/agent/options#acl_tokens_agent). At authorization time this acts like an 52 additional policy was attached, the contents of which are described further 53 below. These are directly attached to tokens and roles and are not 54 independently configured. (Added in Consul 1.8.1) 55 56- **ACL Auth Methods and Binding Rules** - To learn more about these topics, 57 see the [auth methods documentation page](/docs/acl/auth-methods). 58 59ACL tokens, policies, roles, auth methods, and binding rules are managed by 60Consul operators via Consul's [ACL API](/api/acl/acl), 61[ACL CLI](/docs/commands/acl), or systems like 62[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul). 63 64If the ACL system becomes inoperable, you can follow the 65[reset procedure](https://learn.hashicorp.com/consul/security-networking/acl-troubleshooting?utm_source=consul.io&utm_medium=docs) at any time. 66 67### ACL Policies 68 69An ACL policy is a named set of rules and is composed of the following elements: 70 71- **ID** - The policy's auto-generated public identifier. 72- **Name** - A unique meaningful name for the policy. 73- **Description** - A human readable description of the policy. (Optional) 74- **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules#rule-specification) documentation for more details. 75- **Datacenters** - A list of datacenters the policy is valid within. 76- **Namespace** - <EnterpriseAlert inline /> - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) 77 78-> **Consul Enterprise Namespacing** - Rules defined in a policy in any namespace other than `default` will be [restricted](/docs/acl/acl-rules#namespace-rules-enterprise) to being able to grant a subset of the overall privileges and only affecting that single namespace. 79 80#### Builtin Policies 81 82- **Global Management** - Grants unrestricted privileges to any token that uses it. When created it will be named `global-management` 83 and will be assigned the reserved ID of `00000000-0000-0000-0000-000000000001`. This policy can be renamed but modification 84 of anything else including the rule set and datacenter scoping will be prevented by Consul. 85 86- **Namespace Management** - <EnterpriseAlert inline /> - 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 87 within the Namespace. (Added in Consul Enterprise 1.7.0) 88 89### ACL Service Identities 90 91-> Added in Consul 1.5.0 92 93An ACL service identity is an [ACL policy](/docs/acl/acl-system#acl-policies) template for expressing a link to a policy 94suitable for use in [Consul Connect](/docs/connect). They are usable 95on both tokens and roles and are composed of the following elements: 96 97- **Service Name** - The name of the service. 98- **Datacenters** - A list of datacenters the effective policy is valid within. (Optional) 99 100Services participating in the service mesh will need privileges to both _be 101discovered_ and to _discover other healthy service instances_. Suitable 102policies tend to all look nearly identical so a service identity is a policy 103template to aid in avoiding boilerplate policy creation. 104 105During the authorization process, the configured service identity is automatically 106applied as a policy with the following preconfigured [ACL 107rules](/docs/acl/acl-system#acl-rules-and-scope): 108 109```hcl 110# Allow the service and its sidecar proxy to register into the catalog. 111service "<Service Name>" { 112 policy = "write" 113} 114service "<Service Name>-sidecar-proxy" { 115 policy = "write" 116} 117 118# Allow for any potential upstreams to be resolved. 119service_prefix "" { 120 policy = "read" 121} 122node_prefix "" { 123 policy = "read" 124} 125``` 126 127The [API documentation for roles](/api/acl/roles#sample-payload) has some 128examples of using a service identity. 129 130-> **Consul Enterprise Namespacing** - Service Identity rules will be scoped to the single namespace that 131the corresponding ACL Token or Role resides within. 132 133### ACL Node Identities 134 135-> Added in Consul 1.8.1 136 137An ACL node identity is an [ACL policy](/docs/acl/acl-system#acl-policies) template for expressing a link to a policy 138suitable for use as an [Consul `agent` token](/docs/agent/options#acl_tokens_agent). They are usable 139on both tokens and roles and are composed of the following elements: 140 141- **Node Name** - The name of the node to grant access to. 142- **Datacenter** - The datacenter that the node resides within. 143 144During the authorization process, the configured node identity is automatically 145applied as a policy with the following preconfigured [ACL 146rules](/docs/acl/acl-system#acl-rules-and-scope): 147 148```hcl 149# Allow the agent to register its own node in the Catalog and update its network coordinates 150node "<Node Name>" { 151 policy = "write" 152} 153 154# Allows the agent to detect and diff services registered to itself. This is used during 155# anti-entropy to reconcile difference between the agents knowledge of registered 156# services and checks in comparison with what is known in the Catalog. 157service_prefix "" { 158 policy = "read" 159} 160``` 161 162-> **Consul Enterprise Namespacing** - Node Identities can only be applied to tokens and roles in the `default` namespace. 163The synthetic policy rules allow for `service:read` permissions on all services in all namespaces. 164 165### ACL Roles 166 167-> Added in Consul 1.5.0 168 169An ACL role is a named set of policies and service identities and is composed 170of the following elements: 171 172- **ID** - The role's auto-generated public identifier. 173- **Name** - A unique meaningful name for the role. 174- **Description** - A human readable description of the role. (Optional) 175- **Policy Set** - The list of policies that are applicable for the role. 176- **Service Identity Set** - The list of service identities that are applicable for the role. 177- **Namespace** <EnterpriseAlert inline /> - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) 178 179-> **Consul Enterprise Namespacing** - Roles may only link to policies defined in the same namespace as the role itself. 180 181### ACL Tokens 182 183ACL tokens are used to determine if the caller is authorized to perform an action. An ACL token is composed of the following 184elements: 185 186- **Accessor ID** - The token's public identifier. 187- **Secret ID** -The bearer token used when making requests to Consul. 188- **Description** - A human readable description of the token. (Optional) 189- **Policy Set** - The list of policies that are applicable for the token. 190- **Role Set** - The list of roles that are applicable for the token. (Added in Consul 1.5.0) 191- **Service Identity Set** - The list of service identities that are applicable for the token. (Added in Consul 1.5.0) 192- **Locality** - Indicates whether the token should be local to the datacenter it was created within or created in 193 the primary datacenter and globally replicated. 194- **Expiration Time** - The time at which this token is revoked. (Optional; Added in Consul 1.5.0) 195- **Namespace** <EnterpriseAlert inline /> - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) 196 197-> **Consul Enterprise Namespacing** - Tokens may only link to policies and roles defined in the same namespace as 198the token itself. 199 200#### Builtin Tokens 201 202During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `master` token will be 203injected. 204 205- **Anonymous Token** - The anonymous token is used when a request is made to Consul without specifying a bearer token. 206 The anonymous token's description and policies may be updated but Consul will prevent this token's deletion. When created, 207 it will be assigned `00000000-0000-0000-0000-000000000002` for its Accessor ID and `anonymous` for its Secret ID. 208 209- **Master Token** - When a master token is present within the Consul configuration, it is created and will be linked 210 With the builtin Global Management policy giving it unrestricted privileges. The master token is created with the Secret ID 211 set to the value of the configuration entry. 212 213#### Authorization 214 215The token Secret ID is passed along with each RPC request to the servers. Consul's 216[HTTP endpoints](/api) can accept tokens via the `token` 217query string parameter, the `X-Consul-Token` request header, or an 218[RFC6750](https://tools.ietf.org/html/rfc6750) authorization bearer token. Consul's 219[CLI commands](/docs/commands) can accept tokens via the 220`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. The CLI 221commands can also accept token values stored in files with the `token-file` 222argument, or the `CONSUL_HTTP_TOKEN_FILE` environment variable. 223 224If no token is provided for an HTTP request then Consul will use the default ACL token 225if it has been configured. If no default ACL token was configured then the anonymous 226token will be used. 227 228#### ACL Rules and Scope 229 230The rules from all policies, roles, and service identities linked with a token are combined to form that token's 231effective rule set. Policy rules can be defined in either an allowlist or denylist 232mode depending on the configuration of [`acl_default_policy`](/docs/agent/options#acl_default_policy). 233If the default policy is to "deny" access to all resources, then policy rules can be set to 234allowlist access to specific resources. Conversely, if the default policy is “allow” then policy rules can 235be used to explicitly deny access to resources. 236 237The following table summarizes the ACL resources that are available for constructing 238rules: 239 240| Resource | Scope | 241| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 242| [`acl`](/docs/acl/acl-rules#acl-resource-rules) | Operations for managing the ACL system [ACL API](/api/acl/acl) | 243| [`agent`](/docs/acl/acl-rules#agent-rules) | Utility operations in the [Agent API](/api/agent), other than service and check registration | 244| [`event`](/docs/acl/acl-rules#event-rules) | Listing and firing events in the [Event API](/api/event) | 245| [`key`](/docs/acl/acl-rules#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv) | 246| [`keyring`](/docs/acl/acl-rules#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring) | 247| [`node`](/docs/acl/acl-rules#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), [Network Coordinate API](/api/coordinate), and [Agent API](/api/agent) | 248| [`operator`](/docs/acl/acl-rules#operator-rules) | Cluster-level operations in the [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring) | 249| [`query`](/docs/acl/acl-rules#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query) | 250| [`service`](/docs/acl/acl-rules#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), and [Agent API](/api/agent) | 251| [`session`](/docs/acl/acl-rules#session-rules) | Session operations in the [Session API](/api/session) | 252 253Since Consul snapshots actually contain ACL tokens, the [Snapshot API](/api/snapshot) 254requires a token with "write" privileges for the ACL system. 255 256The following resources are not covered by ACL policies: 257 2581. The [Status API](/api/status) is used by servers when bootstrapping and exposes 259 basic IP and port information about the servers, and does not allow modification 260 of any state. 261 2622. The datacenter listing operation of the 263 [Catalog API](/api/catalog#list-datacenters) similarly exposes the names of known 264 Consul datacenters, and does not allow modification of any state. 265 2663. The [connect CA roots endpoint](/api/connect/ca#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul. 267 268Constructing rules from these policies is covered in detail on the 269[ACL Rules](/docs/acl/acl-rules) page. 270 271-> **Consul Enterprise Namespacing** - In addition to directly linked policies, roles and service identities, Consul Enterprise 272will include the ACL policies and roles defined in the [Namespaces definition](/docs/enterprise/namespaces#namespace-definition). (Added in Consul Enterprise 1.7.0) 273 274## Configuring ACLs 275 276ACLs are configured using several different configuration options. These are marked 277as to whether they are set on servers, clients, or both. 278 279| Configuration Option | Servers | Clients | Purpose | 280| -------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- | 281| [`acl.enabled`](/docs/agent/options#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | 282| [`acl.default_policy`](/docs/agent/options#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | 283| [`acl.down_policy`](/docs/agent/options#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | 284| [`acl.role_ttl`](/docs/agent/options#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | 285| [`acl.policy_ttl`](/docs/agent/options#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | 286| [`acl.token_ttl`](/docs/agent/options#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | 287 288A number of special tokens can also be configured which allow for bootstrapping the ACL 289system, or accessing Consul in special situations: 290 291| Special Token | Servers | Clients | Purpose | 292| ------------------------------------------------------------------------ | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 293| [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | 294| [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | 295| [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) guide for more details | 296| [`acl.tokens.default`](/docs/agent/options#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 | 297 298All of these tokens except the `master` token can all be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens). 299 300#### ACL Agent Master Token 301 302Since the [`acl.tokens.agent_master`](/docs/agent/options#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 303 304```hcl 305agent "<node name of agent>" { 306 policy = "write" 307} 308node_prefix "" { 309 policy = "read" 310} 311``` 312 313#### ACL Agent Token 314 315The [`acl.tokens.agent`](/docs/agent/options#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`](/docs/agent/options#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: 316 3171. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates 3182. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog 3193. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands 320 321Here's an example policy sufficient to accomplish the above for a node called `mynode`: 322 323```hcl 324node "mynode" { 325 policy = "write" 326} 327service_prefix "" { 328 policy = "read" 329} 330key_prefix "_rexec" { 331 policy = "write" 332} 333``` 334 335The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. 336 337## Next Steps 338 339Setup ACLs with the [Bootstrapping the ACL System guide](https://learn.hashicorp.com/consul/security-networking/production-acls?utm_source=consul.io&utm_medium=docs) or continue reading about 340[ACL rules](/docs/acl/acl-rules). 341