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.3.0 and earlier:** This guide only applies in Consul versions 1.3.0 and before. If you are using the 1.4.0 or later please use the updated guide [here](/docs/acl/acl-system.html)
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
the ACL system was rewritten and the legacy system was deprecated. The new ACL system information can be found [here](/docs/acl/acl-system.html).
The legacy documentation has two sections.
- The [New ACL System Differences](#new-acl-system-differences) section
details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/docs/acl/acl-migrate-tokens.html)tokens.
- The [Legacy ACL System documentation](#legacy-acl-system) section details the
ACL system in Consul 1.3.0 and older.
# New ACL System Differences
The [ACL System documentation](/docs/acl/acl-system.html) and [legacy ACL
guide](/docs/acl/acl-legacy.html) describes the new and old systems in
detail. Below is a summary of the changes that need to be considered when
migrating legacy tokens to the new system.
### Token and Policy Separation
You can use a single policy in the new system for all tokens that share access
rules. For example, all tokens created using the clone endpoint in the legacy
system can be represented with a single policy and a set of tokens that map to
that policy.
### Rule Syntax Changes
The most significant change is that rules with selectors _no longer prefix match
by default_. In the legacy system the following rules would grant access to
nodes, services and keys _prefixed_ with foo.
```
node "foo" { policy = "write" }
service "foo" { policy = "write" }
key "foo" { policy = "write" }
```
In the new system the same syntax will only perform _exact_ match on the whole
node name, service name or key.
In general, exact match is what most operators intended most of the time so the
same policy can be kept, however if you rely on prefix match behavior then using
the same syntax will break behavior.
Prefix matching can be expressed in the new ACL system explicitly, making the
following rules in the new system exactly the same as the rules above in the
old.
```
node_prefix "foo" { policy = "write" }
service_prefix "foo" { policy = "write" }
key_prefix "foo" { policy = "write" }
```
### API Separation
The "old" API endpoints below continue to work for backwards compatibility but
will continue to create or show only "legacy" tokens that can't take full
advantage of the new ACL system improvements. They are documented fully under
[CLI commands](/docs/commands/index.html) can accept tokens via the
`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable.
If no token is provided, the rules associated with a special, configurable anonymous
token are automatically applied. The anonymous token is managed using the
[ACL API](/api/acl/acl.html) like any other ACL token, but using `anonymous` for the ID.
#### ACL Rules and Scope
Tokens are bound to a set of rules that control which Consul resources the token
has access to. Policies can be defined in either a whitelist or blacklist mode
depending on the configuration of
[`acl_default_policy`](/docs/agent/options.html#acl_default_policy). If the default
policy is to "deny" all actions, then token rules can be set to whitelist specific
actions. In the inverse, the "allow" all default behavior is a blacklist where rules
are used to prohibit actions. By default, Consul will allow all actions.
The following table summarizes the ACL policies that are available for constructing
rules:
| Policy | Scope |
| ------------------------ | ----- |
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration |
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) |
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) |
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) |
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) |
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) |
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html)
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), and [Agent API](/api/agent.html) |
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) |
Since Consul snapshots actually contain ACL tokens, the
[Snapshot API](/api/snapshot.html) requires a management token for snapshot operations
and does not use a special policy.
The following resources are not covered by ACL policies:
1. The [Status API](/api/status.html) 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](/api/catalog.html#list-datacenters) similarly exposes the names of known
Consul datacenters, and does not allow modification of any state.
Constructing rules from these policies is covered in detail in the
| [`primary_datacenter`](/docs/agent/options.html#primary_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs |
| [`acl_down_policy`](/docs/agent/options.html#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline |
There are some additional configuration items related to [ACL replication](#replication) and
[Version 8 ACL support](#version_8_acls). These are discussed in those respective sections
below.
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_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when the ACL datacenter isn't available, or servers are offline (for clients); 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 |
| [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy) | `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 |
| [`acl_master_token`](/docs/agent/options.html#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details |
| [`acl_token`](/docs/agent/options.html#acl_token_legacy) | `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 |
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
Since the [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy) 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 (the `node` policy was added in Consul 0.9.0):
```text
agent "<nodenameofagent>" {
policy = "write"
}
node "" {
policy = "read"
}
```
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
The [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) 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_token`](/docs/agent/options.html#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` 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](/api/catalog.html), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/anti-entropy.html) 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`](/docs/commands/exec.html) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
```text
node "mynode" {
policy = "write"
}
service "" {
policy = "read"
}
key "_rexec" {
policy = "write"
}
```
The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options.html#disable_remote_exec), the default, then the `key` policy can be omitted.
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
`SECURITY DEFINER` attribute which can be set on functions, and using the client's ACL
Token is similar to the complementary `SECURITY INVOKER` attribute.
Prepared queries were originally introduced in Consul 0.6.0, and ACL behavior remained
unchanged through version 0.6.3, but was then changed to allow better management of the
prepared query namespace.
These differences are outlined in the table below:
<tableclass="table table-bordered table-striped">
<tr>
<th>Operation</th>
<th>Version <= 0.6.3 </th>
<th>Version > 0.6.3 </th>
</tr>
<tr>
<td>Create static query without `Name`</td>
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
<td>No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
</tr>
<tr>
<td>Create static query with `Name`</td>
<td>The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query.</td>
<td>The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query.</td>
</tr>
<tr>
<td>Manage static query without `Name`</td>
<td>The ACL Token used to create the query, or a management token must be supplied in order to perform these operations.</td>
<td>Any client with the ID of the query can perform these operations.</td>
</tr>
<tr>
<td>Manage static query with a `Name`</td>
<td>The ACL token used to create the query, or a management token must be supplied in order to perform these operations.</td>
<td>Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed.</td>
</tr>
<tr>
<td>List queries</td>
<td>A management token is required to list any queries.</td>
<td>The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`.</td>
</tr>
<tr>
<td>Execute query</td>
<td>Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored.</td>
<td>The captured token, client's token, or anonymous token is used to filter the results, as described above.</td>
</tr>
</table>
#### Service Rules
The `service` policy controls service-level registration and read access to the [Catalog API](/api/catalog.html)
and service discovery with the [Health API](/api/health.html).
Service rules look like this:
```text
service "" {
policy = "read"
}
service "app" {
policy = "write"
}
service "admin" {
policy = "deny"
}
```
Service rules are keyed by the service name prefix they apply to, using the longest prefix match rule. In
the example above, the rules allow read-only access to any service name with the empty prefix, allow
read-write access to any service name that starts with "app", and deny all access to any service name that
starts with "admin".
Consul's DNS interface is affected by restrictions on service rules. If the
[`acl_token`](/docs/agent/options.html#acl_token) used by the agent does not have "read" access to a
given service, then the DNS interface will return no records when queried for it.
When reading from the catalog or retrieving information from the health endpoints, service rules are
used to filter the results of the query.
Service rules come into play when using the [Agent API](/api/agent.html) to register services or
checks. The agent will check tokens locally as a service or check is registered, and Consul also
performs periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an
ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
to use for registration events:
1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration
directive. This allows a single token to be configured globally and used
during all service and check registration operations.
2. Providing an ACL token with service and check definitions at registration
time. This allows for greater flexibility and enables the use of multiple
tokens on the same agent. Examples of what this looks like are available for
both [services](/docs/agent/services.html) and
[checks](/docs/agent/checks.html). Tokens may also be passed to the [HTTP
API](/api/index.html) for operations that require them. **Note:** all tokens
passed to an agent are persisted on local disk to allow recovery from
restarts. See [`-data-dir` flag
documentation](/docs/agent/options.html#acl_token) for notes on securing
access.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
[`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) or