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.
The Consul Access Control List (ACL) system authenticates requests and authorizes
access to resources. It is used by the UI, API, CLI, service-to-service
communication, and agent-to-agent communication.
---
# ACL System
-> **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).
The Consul Access Control List (ACL) system authenticates requests and authorizes
access to resources. It is used by the UI, API, CLI, service-to-service
communication, and agent-to-agent communication.
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](https://en.wikipedia.org/wiki/Capability-based_security), 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](https://aws.amazon.com/iam/).
This page will introduce you to all of the core concepts of the ACL system. For a more
step-to-step guide see [Bootstrap and Explore ACLs] for getting started with ACLs and
[Secure Consul with ACLs] for configuring ACLs in a production environment.
To learn how to setup the ACL system on an existing Consul datacenter, use the [Bootstrapping The ACL System tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup?utm_source=consul.io&utm_medium=docs).
[Bootstrap and Explore ACLs]: https://learn.hashicorp.com/tutorials/consul/access-control-setup?utm_source=consul.io&utm_medium=docs
[Secure Consul with ACLs]: https://learn.hashicorp.com/tutorials/consul/access-control-setup-production?utm_source=consul.io&utm_medium=docs
## ACL System Overview
See allso the [ACL API reference](/api-docs/acl), [ACL CLI reference](/commands/acl), and
[Troubleshoot the ACL System](https://learn.hashicorp.com/tutorials/consul/access-control-troubleshoot).
The ACL system is designed to be easy to use and fast to enforce while providing administrative insight.
The diagram below shows the relationships between most of the components of the ACL system:
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.
## Overview
- **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.
The diagram below shows the relationships between the core components of the ACL system:
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](/docs/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)
## Tokens
- **ACL Node Identities** - Node identities are a policy template for
expressing a link to a policy suitable for use as an [Consul `agent` token
](/docs/agent/options#acl_tokens_agent). 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.8.1)
Tokens are the core method of authentication in Consul. The `SecretID` of the token
(often referred to as the ACL token) is an opaque string that is included in requests to
identify the person or system making the request. The ACL system will look up the ACL
token and grant or deny access based on the permissions associated with the token.
Permissions are granted to a token by linking it to [policies](#policies), [roles](#roles),
[service identities](#service-identities), and [node identities](#node-identities).
- **ACL Auth Methods and Binding Rules** - To learn more about these topics,
see the [auth methods documentation page](/docs/acl/auth-methods).
A Token also has an Accessor ID which is used in [Audit Logging](/docs/enterprise/audit-logging)
and API responses to identify the token without revealing the secret ID.
ACL tokens, policies, roles, auth methods, and binding rules are managed by
Consul operators via Consul's [ACL API](/api/acl/acl),
Tokens can be created directly from the [CLI](/commands/acl/token) or [API](/api-docs/acl/tokens).
[Auth Methods](/docs/security/acl/auth-methods) can be used to dynamically create tokens
from a trusted external system.
If the ACL system becomes inoperable, you can follow the
[reset procedure](https://learn.hashicorp.com/tutorials/consul/access-control-troubleshoot#reset-the-acl-system) at any time.
### ACL Policies
## Policies
An ACL policy (not to be confused with [policy dispositions](/docs/security/acl/acl-rules#policy-dispositions)) is a named set of rules and several attributes that define the policy domain. The ID is generated when the policy is created, but you can specify the attributes when creating the policy. Refer to the [ACL policy command line](https://www.consul.io/commands/acl/policy) documentation or [ACL policy API](/api-docs/acl/policies) documentation for additional information on how to create policies.
@ -117,7 +97,7 @@ $ consul acl policy list -format json -token <token_id>
Note that the `Hash`, `CreateIndex`, and `ModifyIndex` attributes are also printed. These attributes are printed for all responses and are not specific to ACL policies.
#### Builtin Policies
### 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
@ -126,11 +106,11 @@ Note that the `Hash`, `CreateIndex`, and `ModifyIndex` attributes are also print
- **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
within the Namespace. (Added in Consul Enterprise 1.7.0)
### ACL Service Identities
## Service Identities
-> Added in Consul 1.5.0
An ACL service identity is an [ACL policy](/docs/acl/acl-system#acl-policies) template for expressing a link to a policy
An ACL service identity is an [ACL policy](/docs/acl/acl-system#policies) template for expressing a link to a policy
suitable for use in [Consul Connect](/docs/connect). They are usable
on both tokens and roles and are composed of the following elements:
@ -169,11 +149,11 @@ examples of using a service identity.
-> **Service Scope for Namespace and Admin Partition** - Service identity rules in Consul Enterprise are scoped to the namespace or admin partition within which the corresponding ACL token or role resides.
### ACL Node Identities
## Node Identities
-> Added in Consul 1.8.1
An ACL node identity is an [ACL policy](/docs/acl/acl-system#acl-policies) template for expressing a link to a policy
An ACL node identity is an [ACL policy](/docs/acl/acl-system#policies) template for expressing a link to a policy
suitable for use as an [Consul `agent` token](/docs/agent/options#acl_tokens_agent). They are usable
on both tokens and roles and are composed of the following elements:
@ -201,7 +181,7 @@ service_prefix "" {
-> **Consul Enterprise Namespacing** - Node Identities can only be applied to tokens and roles in the `default` namespace.
The synthetic policy rules allow for `service:read` permissions on all services in all namespaces.
### ACL Roles
## Roles
-> Added in Consul 1.5.0
@ -217,94 +197,6 @@ of the following elements:
-> **Linking Roles to Policies in Consul Enterprise** - Roles can only be linked to policies that are defined in the same namespace and admin partition.
### ACL Tokens
Consul uses ACL tokens to determine if the caller is authorized to perform an action. An ACL token is composed of several attributes that you can specify when creating the token. Refer to the [ACL token command line](https://www.consul.io/commands/acl/token) documentation or [ACL token API](/api-docs/acl/tokens) documentation for additional information on how to create tokens.:
- **Accessor ID** - The token's public identifier.
- **Secret ID** -The bearer token used when making requests to Consul.
- **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
- **Local** - Indicates whether the token is local to the datacenter in which it was created. The attribute also can specify if the token was created in the primary datacenter and globally replicated.
- **CreateTime** - Timestamp indicating when the token was created.
- **Expiration Time** - The time at which this token is revoked. This attribute is option when creating a token. Added in Consul 1.5.0.
- **Namespace** <EnterpriseAlert inline /> - The namespace in which the token resides. Added in Consul Enterprise 1.7.0.
- **Partition** <EnterpriseAlert inline /> - The partition in which the token resides. Added in Consul Enterprise 1.11.0.
-> **Linking Tokens to Policies in Consul Enterprise** - Tokens can only be linked to policies that are defined in the same namespace and admin partition.
You can view the current ACL tokens on the command line or through the API. The following example demonstrates the command line usage:
```shell-session
$ consul acl token list -format json -token <token_id>
Note that the `CreateIndex`, `ModifyIndex`, and `Hash` attributes are also printed. These attributes are printed for all responses and are not specific to ACL tokens.
#### Builtin Tokens
During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `initial_management` 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.
- **Initial Management Token** - When an initial management 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 initial management
token is created with the Secret ID set to the value of the configuration entry.
In Consul 1.4 - 1.10, this was called the `master` token. It was renamed to `initial_management` token in Consul 1.11.
#### Authorization
The token Secret ID is passed along with each RPC request to the servers. Consul's
[HTTP endpoints](/api) can accept tokens via the `token`
query string parameter, the `X-Consul-Token` request header, or an
[CLI commands](/docs/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 Agent Recovery Token
Since the [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) 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
@ -425,5 +350,4 @@ The `service_prefix` policy needs read access for any services that can be regis
## Next Steps
Setup ACLs with the [Bootstrapping the ACL System tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production?utm_source=consul.io&utm_medium=docs) or continue reading about
[ACL rules](/docs/acl/acl-rules).
Continue reading about [ACL rules](/docs/acl/acl-rules).
Daniel Nephin
3 years ago