luxolus/open-consul
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity

Refactored the ACL documentation

Browse source
This commit is contained in:
trujillo-adam 2022-02-09 16:07:49 -08:00
parent d33bcda622
commit 919f32270a
7 changed files with 1103 additions and 813 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

435
website/content/docs/security/acl/acl-policies.mdx Normal file
View file

@ -0,0 +1,435 @@
---
layout: docs
page_title: ACL Policies
description: >-
This topic describes policies as used in Consul's access control list (ACL) system. A policy is a group of one or more ACL rules that define which services and agents are authorized to communicate with other resources in the network.
---
# Policies
This topic describes policies, which are components in Consul's access control list (ACL) system. Policies define which services and agents are authorized to interact with resources in the network.
## Introduction
A policy is a group of one or more ACL rules that are linked to [ACL tokens](/docs/security/acl/acl-tokens). The following diagram describes the relationships between rules, policies, and tokens:
![ACL system component relationships](/img/acl-token-policy-rule-relationship.png)
The term "policy" should not be confused with the keyword `policy`. The keyword is a rule-level element that determines access to a resource (see [Policy Dispositions](#policy-dispositions)).
## Rules
Rules are one of several [attributes that form a policy](#policy-attributes). They are building blocks that define access to resources.
This section describes about how to assemble rules into policies. Refer to the [ACL Rules Reference](/docs/security/acl/acl-rules) for additional details about how to configure rules and how they affect access to resources.
### Rule Specification
A rule is composed of a resource declaration and an access level defined with the `policy` keyword and a [policy disposition](#policy-dispositions). The following syntax describes the basic structure of a rule:
<CodeTabs heading="Basic syntax for configuring an ACL rule">
<CodeBlockConfig lineNumbers>
```hcl
<resource> {
policy = "<policy disposition>"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"<resource>": [{
"policy": "<policy disposition>"
}]
```
</CodeBlockConfig>
</CodeTabs>
Access to the specified resource is granted or denied based on the policy disposition.
### Resource Labels
Many resources take an additional value that limits the scope of the rule to resources with the same label. A resource label can be the name of a specific set of resources, such as nodes configured with the same `name` value.
The following syntax describes how to include a resource label in the rule:
<CodeTabs heading="Syntax for applying an ACL rule to named resources">
<CodeBlockConfig lineNumbers>
```hcl
<resource> "<label>" {
policy = "<policy disposition>"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"<resource>": [{
"<label>": [{
"policy": "<policy disposition>"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
Labels provide operators with more granular control over access to the resouce, but the following resource types do not take a label:
- `acl`
- `keyring`
- `mesh`
- `operator`
Use the following syntax to create rules for these resources:
<CodeTabs heading="Syntax for resources that take ACL rule configurations directly">
<CodeBlockConfig lineNumbers>
```hcl
<resource> = "<policy disposition>"
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"<resource>": "<policy disposition>"
```
</CodeBlockConfig>
</CodeTabs>
### Policy Dispositions
Use the `policy` keyword and one of the following access levels to set a policy disposition:
- `read`: Allows the resource to be read but not modified.
- `write`: Allows the resource to be read and modified.
- `deny`: Denies read and write access to the resource.
The special `list` access level provices access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/options#acl_enable_key_list_policy) setting must be set to `true`.
### Matching and Prefix Values
You can define rules for labeled resources based on exact matches or by using resource prefixes to match several resource labels beginning with the same value. Matching resource labels on exact values is described in the [Resource Labels](#resource-labels) section.
The following example rule is an exact match that denies access to services labeled `web-prod`:
<CodeTabs heading="Example rule that denies access to services named 'web-prod'">
<CodeBlockConfig lineNumbers>
```hcl
service "web-prod" {
policy = "deny"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"service": [{
"web-prod" : [{
"policy" : "deny"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
You can append the resource with `_prefix` to match all resource labels beginning with the same value. The following example rule allows `write` access to all services with labels that begin with "web":
<CodeTabs heading="Example rule that grants read and write access to services with names beginning with 'web'">
<CodeBlockConfig lineNumbers>
```hcl
service_prefix "web" {
policy = "write"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"service_prefix": [{
"web" : [{
"policy" : "write"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
Prefix-based resource labels can also contain an empty string, which configures the rule to apply to all resources of the declared type. The following example rule allows `read` access to all `service` resources:
<CodeTabs heading="Example rule that grants read access to all services">
<CodeBlockConfig lineNumbers>
```hcl
service_prefix "" {
policy = "read"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"service_prefix" : [{
"" : [{
"policy" :"read"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
When using prefix-based rules, the most specific prefix match determines the action. In a real-world scenario, a combination of rules would be combined to create a flexible policy. Each team or business unit would use tokens based on policies that enforce several rules, for example:
- A rule that denies access to a specific resource label
- A prefix-based rule that allows write access to a class of resources
- An empty prefix that grants read-only access to all resource within the declared class
#### Matching Precedence
Exact matching rules will only apply to the exact resource specified. The order of precedence for matching rules are:
1. `deny` (highest priority)
1. `write`
1. `read`
## Policy Format
Define policies using the
[HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl/).
HCL is human readable and interoperable with JSON, making it easy to automate policy generation.
The following examples show the same policy formatted in HCL and JSON:
<CodeTabs heading="Example rules">
<CodeBlockConfig lineNumbers>
```hcl
# These control access to the key/value store.
key_prefix "" {
policy = "read"
}
key_prefix "foo/" {
policy = "write"
}
key_prefix "foo/private/" {
policy = "deny"
}
# Or for exact key matches
key "foo/bar/secret" {
policy = "deny"
}
# This controls access to cluster-wide Consul operator information.
operator = "read"
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
{
"key": [
{
"foo/bar/secret": [
{
"policy": "deny"
}
]
}
],
"key_prefix": [
{
"": [
{
"policy": "read"
}
]
},
{
"foo/": [
{
"policy": "write"
}
]
},
{
"foo/private/": [
{
"policy": "deny"
}
]
}
],
"operator": "read"
}
```
</CodeBlockConfig>
</CodeTabs>
## Rule Scope
The rules from all policies, including 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 an `allowlist` or `denylist` mode, depending on the configuration of the [`acl_default_policy`](/docs/agent/options#acl_default_policy).
If the default policy is configured to deny access to all resources, then policy rules can be set to `allowlist` access to specific resources.
If the default policy is to allow then access to all resources, policy rules can be used to explicitly deny access to resources.
## Implementing Policies
After defining policies, the person responsible for administrating ACLs in your organization can implement them through the command line or by calling the ACL HTTP API endpoint and including rules in the payload.
### Command Line
Use the `consul acl policy` command to manage policies. Refer to the [ACL command line documentation](/commands/acl/policy) for details.
The following example creates a policy called `my-app-policy` and applies the rules defined in `rules.hcl`:
```shell-session
$ consul acl policy create -name "my-app-policy" -description "Human-readable description of my policy" -rules @rules.hcl -token "<token with ACL 'write' access>"
```
Note that the command must present a token with permissions to use the ACL system. If the command is issued successfully, the console wil print information about the policy:
```shell-session
ID: <auto-generated ID>
Name: my-app-policy
Description: Human-readable description of my policy
Datacenters: <specified with the -valid-datacenter option>
Rules:
<rules defined in the rules.hcl file>
```
You can can define several attributes that attach additional metadata and specify the scope of the policy. See [Policy Attributes](#policy-attributes) for details.
### HTTP API Endpoint
The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/api/acl/acl) for details about the API.
The following example adds a set of rules to a policy called `my-app-policy`. The policy defines access to the `key` resource (Consul K/V). The rules are formatted in HCL, but they are wrapped in JSON so that the data can be sent using cURL:
```shell-session
$ curl \
--request PUT \
--data \
'{
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
}' http://127.0.0.1:8500/v1/acl/policy?token=<token with ACL "write" access>
```
The following call performs the same operation as the previous example using JSON:
```shell-session
$ curl \
--request PUT \
--data \
'{
"Name": "my-app-policy",
"Rules": "{\"key\":{\"\":{\"policy\":\"read\"},\"foo/\":{\"policy\":\"write\"},\"foo/private\":{\"policy\":\"deny\"}},\"operator\":\"read\"}"
}' http://127.0.0.1:8500/v1/acl/policy?token=<management token>
```
The policy configuration is returned when the call is succesfully performed:
```json
{
"CreateIndex": 7,
"Hash": "UMG6QEbV40Gs7Cgi6l/ZjYWUwRS0pIxxusFKyKOt8qI=",
"ID": "5f423562-aca1-53c3-e121-cb0eb2ea1cd3",
"ModifyIndex": 7,
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
}
```
### Linking Policies to Tokens
A policy that has been implemented must still be linked to a token before the policy has an effect. A service or agent presents the token when interacting with resources in the network. The ACL system processes evaluate the policies linked to the token to determine if the requester has access to the requested resource.
The person responsible for administrating ACLs can use the command line or call the API endpoint to link policies to tokens. Tokens can also be generated dynamically from an external system using Consul's [auth methods](/docs/security/acl/auth-methods) functionality.
Refer to the [tokens documentation](/docs/security/acl/acl-tokens), as well as the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#create-the-agent-token), for details about creating and linking policies to tokens.
## Policy Attributes
Policies may have several attributes that enable you to perform specific functions. For example, you can configure the policy's scope by specifying the name of a datacenter, namespace (Consul Enterprise), or administrative partition (Consul Enterprise) when interacting or creating policies.
Additional metadata, such as the values of the `ID` and `name` fields, provide handles for updating and managing policies.
Refer to the following topics for additional information:
- [Namespaces](/docs/enterprise/namespaces)
- [Admin Partitions](/docs/enterprise/admin-partitions)
ACL policies can have the following attributes:
| Attribute | Description | Required | Default |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | --------- |
| `ID` | The policy's public identifier. Present the `ID` (or the `name`) value when interacting with policies. You can specify a value when creating policies or use the value auto-generated by Consul. | N/A | N/A |
| `name` | Unique name for the policy. | Required | none |
| `description` | Human readable description of the policy. | Optional | none |
| `rules` | Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules#rule-specification) documentation for more details. | Optional | none |
| `datacenter` | Datacenter in which the policy is valid. More than one datacenter can be specified. | Optional | none |
| `namespace` | <EnterpriseAlert inline /> Namespace in which the policy is valid. Added in Consul Enterprise 1.7.0. | Optional | `default` |
| `partition` | <EnterpriseAlert inline /> Admin partition in which the policy is valid. Added in Consul Enterprise 1.11.0 | Optional | `default` |
-> **Non-default Namespaces and Partitions** - Rules defined in a policy tied to an namespace or admin partition other than `default` can only grant a subset of privileges that affect the namespace or partition. See [Namespace Rules](/docs/acl/acl-rules#namespace-rules) and [Admin Partition Rules](/docs/acl/acl-rules#admin-partition-rules) for additional information.
You can view the current ACL policies on the command line or through the API. The following example demonstrates the command line usage:
```shell-session
$ consul acl policy list -format json -token <token_id>
[
{
"ID": "56595ec1-52e4-d6de-e566-3b78696d5459",
"Name": "b-policy",
"Description": "",
"Datacenters": null,
"Hash": "ULwaXlI6Ecqb9YSPegXWgVL1LlwctY9TeeAOhp5HGBA=",
"CreateIndex": 126,
"ModifyIndex": 126,
"Namespace": "default",
"Partition": "default"
},
{
"ID": "00000000-0000-0000-0000-000000000001",
"Name": "global-management",
"Description": "Builtin Policy that grants unlimited access",
"Datacenters": null,
"Hash": "W1bQuDAlAlxEb4ZWwnVHplnt3I5oPKOZJQITh79Xlog=",
"CreateIndex": 70,
"ModifyIndex": 70,
"Namespace": "default",
"Partition": "default"
}
]
```
The `Hash`, `CreateIndex`, and `ModifyIndex` attributes are also printed. These attributes are printed for all responses and are not specific to ACL policies.
## Built-in Policies
New installations of Consul ship with the following built-ib policies.
### Global Management
The `global-management` policy grants unrestricted privileges to any token linked to it. The policy is assigned the reserved ID of `00000000-0000-0000-0000-000000000001`. You can rename the global management policy, but Consul will prevent you from modifying any other attributes, including the rule set and datacenter scope.
### Namespace Management <EnterpriseAlert inline />
The `namespace-management` policy will be injected into all namespaces you create. The policy will be assigned a randomized UUID and can be managed as a normal, user-defined policy within the namespace. This feature was added in Consul Enterprise 1.7.0.

144
website/content/docs/security/acl/acl-roles.mdx Normal file
View file

@ -0,0 +1,144 @@
---
layout: docs
page_title: Roles
description: >-
This topic describes roles within the access control list (ACL) system. A role is a named set of policies and service identities.
They are intended to
---
# Roles
A role is a collection of policies that your ACL administrator can link to a token.
They enable you to reuse policies by decoupling the policies from the token distributed to team members.
Instead, the token is linked to the role, which is able to hold several policies that can be updated asynchronously without distributing new tokens to users.
As a result, roles can provide a more convenient authentication infrastrcture than creating unique policies and tokens for each requester.
## Workflow Overview
Roles are configurations link several policies to a token. The following procedure describes the workflow for implementing roles.
1. Assemble rules into policies (see [Policies](/docs/security/acl/acl-policies)) and register them in Consul.
1. Define a role and include the policy IDs or names.
1. Register the role in Consule and link it to a token.
1. Distribute the tokens to users for implementation.
## Creating Roles
Creating roles is commonly the responsibility of the Consul ACLs administrator.
Roles have several attributes, including service identities and node identities.
Refer to the following documentation for details:
- [Role Attributes](#role-attributes)
- [Service Identities](#service-identities)
- [Node Identities](#node-identities)
Use the Consul command line or API endpoint to create roles.
### Command Line
Issue the `consul acl role create` command to create roles. In the following example, a role named `crawler` is created that contains a policy named `crawler-kv` and a policy named `crawler-key`.
```shell-session
$ consul acl role create -name "crawler" -description "web crawler role" -policy-name "crawler-kv" -policy-name "crawler-key"
```
Refer to the [command line documentation](/command/acl/role) for details.
### API
Make a `PUT` call to the `acl/role` endpoint and specify the role configuration in the payload to create roles. You can save the role definition in a JSON file or use escaped JSON in the call. In the following example call, the payload is defined externally.
```shell-session
$ curl -X PUT --data @payload.json http://127.0.0.1:8500/v1/acl/role
```
Refer to the [API documentation](/api-docs/acl/roles) for details.
## Role Attributes
Roles may contain the following table describe the attributes:
- `ID`: The `ID` is an auto-generated public identifier. You can specify the role `ID` when linking it to tokens.
- `Name`: A unique meaningful name for the role. You can specify the role `Name` when linking it to tokens.
- `Description`: (Optional) A human-readable description of the role.
- `Policies`: Specifies a the list of policies that are applicable for the role. The object can reference the policy `ID` or `Name` attribute.
- `ServiceIdentities`: Specifies a list of services that are applicable for the role. See [Service Identities](#service-identities) for details.
- `NodeIdentities`: Specifies a list of nodes that are applicable for the role. See [Node Identities](#node-identities) for details.
- `Namespace`: <EnterpriseAlert inline /> The namespace this policy resides within. Roles can only be linked to policies that are defined in the same namespace and admin partition. See [Namespaces](/docs/enterprise/namespaces) and [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.7.0+.
## Service Identities
<!-- -> Added in Consul 1.5.0 # Remove and lean on versioning?-->
Service identities are methods for linking services that participate in a Consul service mesh to a policy.
They are configurations added to a role that specifies a services that participate in a Consul service mesh and links them to a policy.
Service identities are templates that provide privileges to _be discovered_ and to _discover other healthy service instances_ in a service mesh.
See [Service Mesh](/docs/connect) for additional information about Consul service mesh.
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)
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](/docs/acl/acl-system#acl-rules-and-scope):
```hcl
# 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](/api/acl/roles#sample-payload) has some
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.
## Node Identities
-> Added in Consul 1.8.1
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:
- **Node Name** - The name of the node to grant access to.
- **Datacenter** - The datacenter that the node resides within.
During the authorization process, the configured node identity is automatically
applied as a policy with the following preconfigured [ACL
rules](/docs/acl/acl-system#acl-rules-and-scope):
```hcl
# Allow the agent to register its own node in the Catalog and update its network coordinates
node "<Node Name>" {
policy = "write"
}
# Allows the agent to detect and diff services registered to itself. This is used during
# anti-entropy to reconcile difference between the agents knowledge of registered
# services and checks in comparison with what is known in the Catalog.
service_prefix "" {
policy = "read"
}
```
-> **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.

640
website/content/docs/security/acl/acl-rules.mdx
View file

@ -1,340 +1,45 @@
---
layout: docs
page_title: ACL Rules
page_title: ACL Rules Reference
description: >-
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.
This topic provides reference information for the types of access control level (ACL) rules you can create and how they affect access to datacenter resources.
---
# ACL Rules
# Rules Reference
This topic describes how to configure rules for Consul's access control list (ACL) system. The ACL system enables you to control access to data and APIs. Refer to the [ACL system documentation](/docs/acl/acl-system) to learn more about ACLs.
This topic provides reference information for the types of access control level (ACL) rules you can create and how they affect access to datacenter resources. For details on how to create rules and group them into policies, see [Policies](/docs/security/acl/acl-policies).
-> **1.4.0 and later:** This topic applies to Consul versions 1.4.0 and later. Refer to the [legacy ACL system documentation](/docs/acl/acl-legacy) for older versions of Consul.
## Rule Specification
ACL rules describe the level of access to resources. A rule is composed of a resource declaration and an access level defined with the `policy` keyword and a [policy disposition](#policy-dispositions). The following syntax describes the basic structure of a rule:
<CodeTabs heading="Basic syntax for configuring an ACL rule">
<CodeBlockConfig lineNumbers>
```hcl
<resource> {
policy = "<policy disposition>"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"<resource>": [{
"policy": "<policy disposition>"
}]
```
</CodeBlockConfig>
</CodeTabs>
### Resource Labels
Many resources take an additional value that limits the scope of the rule to resources with the same label. A resource label can be the name of a specific set of resources, such as nodes configured with the same `name` value.
The following syntax describes how to include a resource label in the rule:
<CodeTabs heading="Syntax for applying an ACL rule to named resources">
<CodeBlockConfig lineNumbers>
```hcl
<resource> "<label>" {
policy = "<policy disposition>"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"<resource>": [{
"<label>": [{
"policy": "<policy disposition>"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
Labels provide operators with more granular control over access to the resouce, but the following resource types do not take a label:
* `acl`
* `keyring`
* `mesh`
* `operator`
Use the following syntax to create rules for these resources:
<CodeTabs heading="Syntax for resources that take ACL rule configurations directly">
<CodeBlockConfig lineNumbers>
```hcl
<resource> = "<policy disposition>"
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"<resource>": "<policy disposition>"
```
</CodeBlockConfig>
</CodeTabs>
### Policy Dispositions
Use the `policy` keyword and one of the following access levels to set a policy disposition:
- `read`: Allows the resource to be read but not modified.
- `write`: Allows the resource to be read and modified.
- `deny`: Denies read and write access to the resource.
The special `list` access level provices access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/options#acl_enable_key_list_policy) setting must be set to `true`.
### Matching and Prefix Values
You can define rules for labeled resources based on exact matches or by using resource prefixes to match several resource labels beginning with the same value. Matching resource labels on exact values is described in the [Resource Labels](#resource-labels) section.
The following example rule is an exact match that denies access to services labeled `web-prod`:
<CodeTabs heading="Example rule that denies access to services named 'web-prod'">
<CodeBlockConfig lineNumbers>
```hcl
service "web-prod" {
policy = "deny"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"service": [{
"web-prod" : [{
"policy" : "deny"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
You can append the resource with `_prefix` to match all resource labels beginning with the same value. The following example rule allows `write` access to all services with labels that begin with "web":
<CodeTabs heading="Example rule that grants read and write access to services with names beginning with 'web'">
<CodeBlockConfig lineNumbers>
```hcl
service_prefix "web" {
policy = "write"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"service_prefix": [{
"web" : [{
"policy" : "write"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
Prefix-based resource labels can also contain an empty string, which configures the rule to apply to all resources of the declared type. The following example rule allows `read` access to all `service` resources:
<CodeTabs heading="Example rule that grants read access to all services">
<CodeBlockConfig lineNumbers>
```hcl
service_prefix "" {
policy = "read"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
"service_prefix" : [{
"" : [{
"policy" :"read"
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
When using prefix-based rules, the most specific prefix match determines the action. In a real-world scenario, a combination of rules would be combined to create a flexible policy. Each team or business unit would use tokens based on policies that enforce several rules, for example:
* A rule that denies access to a specific resource label
* A prefix-based rule that allows write access to a class of resources
* An empty prefix that grants read-only access to all resource within the declared class
#### Matching Precedence
Exact matching rules will only apply to the exact resource specified. The order of precedence for matching rules are:
1. `deny` (highest priority)
1. `write`
1. `read`
### Formatting Rules
Define rules using the
[HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl/).
HCL is human readable and interoperable with JSON, making it easy to automate rule generation.
The following examples show the same rules formatted in HCL and JSON:
<CodeTabs heading="Example rules">
<CodeBlockConfig lineNumbers>
```hcl
# These control access to the key/value store.
key_prefix "" {
policy = "read"
}
key_prefix "foo/" {
policy = "write"
}
key_prefix "foo/private/" {
policy = "deny"
}
# Or for exact key matches
key "foo/bar/secret" {
policy = "deny"
}
# This controls access to cluster-wide Consul operator information.
operator = "read"
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers>
```json
{
"key": [
{
"foo/bar/secret": [
{
"policy": "deny"
}
]
}
],
"key_prefix": [
{
"": [
{
"policy": "read"
}
]
},
{
"foo/": [
{
"policy": "write"
}
]
},
{
"foo/private/": [
{
"policy": "deny"
}
]
}
],
"operator": "read"
}
```
</CodeBlockConfig>
</CodeTabs>
## Defining Rules with the ACL API
You can configure ACLs remotely by calling the ACL HTTP API endpoint and including rules in the payload. The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/api/acl/acl) for details about the API.
The following example adds a set of rules that apply to the `key` resource (Consul K/V) within the `my-app-policy` policy. The rules are formatted in HCL, but they are wrapped in JSON so that the data can be sent using cURL:
```shell-session
$ curl \
--request PUT \
--data \
'{
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
}' http://127.0.0.1:8500/v1/acl/policy?token=<token with ACL "write">
```
The following call performs the same operation as the previous example using JSON:
```shell-session
$ curl \
--request PUT \
--data \
'{
"Name": "my-app-policy",
"Rules": "{\"key\":{\"\":{\"policy\":\"read\"},\"foo/\":{\"policy\":\"write\"},\"foo/private\":{\"policy\":\"deny\"}},\"operator\":\"read\"}"
}' http://127.0.0.1:8500/v1/acl/policy?token=<management token>
```
The policy configuration is returned when the call is succesfully performaed:
```json
{
"CreateIndex": 7,
"Hash": "UMG6QEbV40Gs7Cgi6l/ZjYWUwRS0pIxxusFKyKOt8qI=",
"ID": "5f423562-aca1-53c3-e121-cb0eb2ea1cd3",
"ModifyIndex": 7,
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
}
```
The policy can now be specified either by name or by ID when
[creating a token](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#create-the-agent-token).
This will grant the rules provided to the [bearer of that token](/api#authentication).
## Resource and Rule Reference
## Overview
The following table provides an overview of the resources you can use to create ACL rules.
| Resource | Description | Labels |
|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `acl` | Controls access to ACL operations in the [ACL API](/api/acl/acl). <br/>See [ACL Resource Rules](#acl-resource-rules) for details. | No |
| `partition`<br/>`partition_prefix` | <EnterpriseAlert inline /> Controls access to one or more admin partitions. <br/>See [Admin Partition Rules](#admin-partition-rules) for details. | Yes |
| `agent`<br/>`agent_prefix` | Controls access to the utility operations in the [Agent API](/api/agent), such as `join` and `leave`. <br/>See [Agent Rules](#agent-rules) for details. | Yes |
| `event`<br/>`event_prefix` | Controls access to event operations in the [Event API](/api/event), such as firing and listing events. <br/>See [Event Rules](#event-rules) for details. | Yes |
| `key`<br/>`key_prefix` &nbsp; | Controls access to key/value store operations in the [KV API](/api/kv). <br/>Can also use the `list` access level when setting the policy disposition. <br/>Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul). <br/>See [Key/Value Rules](#key-value-rules) for details. | Yes |
| `keyring` &nbsp; &nbsp; &nbsp; | Controls access to keyring operations in the [Keyring API](/api/keyring). <br/>See [Keyring Rules](#keyring-rules) for details. | No |
| `mesh` &nbsp; &nbsp; &nbsp; | Provides operator-level permissions for resources in the admin partition, such as ingress gateways or mesh proxy defaults. See [Mesh Rules](#mesh-rules) for details. | No |
| `namespace`<br/>`namespace_prefix` | <EnterpriseAlert inline /> Controls access to one or more namespaces. <br/>See [Namespace Rules](#namespace-rules) for details. | Yes |
| `node`<br/>`node_prefix` &nbsp; | Controls access to node-level registration and read access to the [Catalog API](/api/catalog). <br/>See [Node Rules](#node-rules) for details. | Yes |
| `operator` &nbsp; &nbsp; &nbsp; | Controls access to cluster-level operations available in the [Operator API](/api/operator) excluding keyring API endpoints. <br/>See [Operator Rules](#operator-rules) for details. | No |
| `query`<br/>`query_prefix` | Controls access to create, update, and delete prepared queries in the [Prepared Query API](/api/query). Access to the [node](#node-rules) and [service](#service-rules) must also be granted. <br/>See [Prepared Query Rules](#prepared-query-rules) for details. | Yes |
| `service`<br/>`service_prefix` | Controls service-level registration and read access to the [Catalog API](/api/catalog), as well as service discovery with the [Health API](/api/health). <br/>See [Service Rules](#node-rules) for details. | Yes |
| `session`<br/>`session_prefix` | Controls access to operations in the [Session API](/api/session). <br/>See [Session Rules](#session-rules) for details. | Yes |
| Resource | Description | Labels |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `acl` | Controls access to ACL operations in the [ACL API](/api/acl/acl). <br/>See [ACL Resource Rules](#acl-resource-rules) for details. | No |
| `partition`<br/>`partition_prefix` | <EnterpriseAlert inline /> Controls access to one or more admin partitions. <br/>See [Admin Partition Rules](#admin-partition-rules) for details. | Yes |
| `agent`<br/>`agent_prefix` | Controls access to the utility operations in the [Agent API](/api/agent), such as `join` and `leave`. <br/>See [Agent Rules](#agent-rules) for details. | Yes |
| `event`<br/>`event_prefix` | Controls access to event operations in the [Event API](/api/event), such as firing and listing events. <br/>See [Event Rules](#event-rules) for details. | Yes |
| `key`<br/>`key_prefix` &nbsp; | Controls access to key/value store operations in the [KV API](/api/kv). <br/>Can also use the `list` access level when setting the policy disposition. <br/>Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul). <br/>See [Key/Value Rules](#key-value-rules) for details. | Yes |
| `keyring` &nbsp; &nbsp; &nbsp; | Controls access to keyring operations in the [Keyring API](/api/keyring). <br/>See [Keyring Rules](#keyring-rules) for details. | No |
| `mesh` &nbsp; &nbsp; &nbsp; | Provides operator-level permissions for resources in the admin partition, such as ingress gateways or mesh proxy defaults. See [Mesh Rules](#mesh-rules) for details. | No |
| `namespace`<br/>`namespace_prefix` | <EnterpriseAlert inline /> Controls access to one or more namespaces. <br/>See [Namespace Rules](#namespace-rules) for details. | Yes |
| `node`<br/>`node_prefix` &nbsp; | Controls access to node-level 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) <br/>See [Node Rules](#node-rules) for details. | Yes |
| `operator` &nbsp; &nbsp; &nbsp; | Controls access to cluster-level operations available in the [Operator API](/api/operator) excluding keyring API endpoints. <br/>See [Operator Rules](#operator-rules) for details. | No |
| `query`<br/>`query_prefix` | Controls access to create, update, and delete prepared queries in the [Prepared Query API](/api/query). Access to the [node](#node-rules) and [service](#service-rules) must also be granted. <br/>See [Prepared Query Rules](#prepared-query-rules) for details. | Yes |
| `service`<br/>`service_prefix` | Controls service-level operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Intentions API](/api/connect/intentions), [Prepared Query API](/api/query), and [Agent API](/api/agent). <br/>See [Service Rules](#node-rules) for details. | Yes |
| `session`<br/>`session_prefix` | Controls access to operations in the [Session API](/api/session). <br/>See [Session Rules](#session-rules) for details. | Yes |
The following resources are not covered by ACL policies:
- The [Status API](/api/status) is used by servers when bootstrapping and exposes basic IP and port information about the servers, and does not allow modification of any state.
- The datacenter listing operation of the [Catalog API](/api/catalog#list-datacenters) similarly exposes the names of known Consul datacenters, and does not allow modification of any state.
- 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.
-> **Consul Enterprise Namespace** - In addition to directly-linked policies, roles, and service identities, Consul Enterprise enables ACL policies and roles to be defined in the [Namespaces definition](/docs/enterprise/namespaces#namespace-definition) (Consul Enterprise 1.7.0+).
The following topics provide additional details about the available resources.
### ACL Resource Rules
## ACL Resource Rules
The `acl` resource controls access to ACL operations in the [ACL API](/api/acl/acl). Only one `acl` rule is allowed per policy. The value is set to one of the [policy dispositions](#policy-dispositions).
@ -361,7 +66,7 @@ acl = "write"
</CodeBlockConfig>
</CodeTabs>
### Admin Partition Rules <EnterpriseAlert inline />
## Admin Partition Rules <EnterpriseAlert inline />
The `partition` and `partition_prefix` resource controls access to one or more admin partitions.
You can include any number of namespace rules inside the admin partition.
@ -395,55 +100,84 @@ partition_prefix "ex-" {
<CodeBlockConfig>
```json
{
"partition": [{
"example": [{
"mesh": "write",
"node": [{
"my-node": [{
"policy": "write"
}],
"namespace": [{
"ex-namespace": [{
"policy": "read"
}]
}],
"namespace_prefix": [{
"exns-": [{
"policy": "read"
}]
}]
}]
}]
}]
({
"partition": [
{
"example": [
{
"mesh": "write",
"node": [
{
"my-node": [
{
"policy": "write"
}
],
"namespace": [
{
"ex-namespace": [
{
"policy": "read"
}
]
}
],
"namespace_prefix": [
{
"exns-": [
{
"policy": "read"
}
]
}
]
}
]
}
]
}
]
},
{
"partition_prefix": [{
"": [{
"policy": "read"
}],
"example": [{
"mesh": "read",
"node": [{
"my-node": [{
"policy": "read"
}]
}],
"namespace": [{
"ex-namespace": [{
"policy": "read"
}]
}]
}]
}]
}
"partition_prefix": [
{
"": [
{
"policy": "read"
}
],
"example": [
{
"mesh": "read",
"node": [
{
"my-node": [
{
"policy": "read"
}
]
}
],
"namespace": [
{
"ex-namespace": [
{
"policy": "read"
}
]
}
]
}
]
}
]
})
```
</CodeBlockConfig>
</CodeTabs>
### Agent Rules
## Agent Rules
The `agent` and `agent_prefix` resources control access to the utility operations in the [Agent API](/api/agent),
such as join and leave. All of the catalog-related operations are covered by the [`node` or `node_prefix`](#node-rules)
@ -496,7 +230,7 @@ a cluster, or during an outage of the Consul servers or ACL datacenter, a specia
configured with [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) to allow
write access to these operations even if no ACL resolution capability is available.
### Event Rules
## Event Rules
The `event` and `event_prefix` resources control access to event operations in the [Event API](/api/event), such as
firing events and listing events.
@ -512,6 +246,7 @@ event "deploy" {
policy = "write"
}
```
</CodeBlockConfig>
<CodeBlockConfig>
@ -539,7 +274,7 @@ operation, so to enable this feature in a Consul environment with ACLs enabled,
give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
### Key/Value Rules
## Key/Value Rules
The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/api/kv).
@ -557,6 +292,7 @@ key "bar" {
policy = "deny"
}
```
</CodeBlockConfig>
<CodeBlockConfig>
@ -582,11 +318,10 @@ key "bar" {
Key rules are labeled with the key name they apply to. In the example above, the rules allow read-only access
to any key name with the empty prefix rule, allow read-write access to the "foo" key, and deny access to the "bar" key.
#### List Policy for Keys
### List Policy for Keys
Enable the `list` policy disposition (Consul 1.0+) by setting the `acl.enable_key_list_policy` parameter to `true`. The disposition provides recursive access to `key` entries. Refer to the [KV API](/api/kv#recurse) documentation for additional information. In the following example, `key` resources that start with `bar` are listed.
<CodeTabs heading="Example 'key' rules">
<CodeBlockConfig>
@ -648,7 +383,7 @@ EOF
For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel).
### Keyring Rules
## Keyring Rules
The `keyring` resource controls access to keyring operations in the [Keyring API](/api/operator/keyring). Only one keyring policy is allowed per rule set. The value is set to one of the policy dispositions, but may be read and updated.
@ -679,18 +414,20 @@ The `mesh` resource controls access to ingress gateways, terminating gateways, a
```hcl
mesh = "write"
```
</CodeBlockConfig>
<CodeBlockConfig>
```json
"mesh" : "write"
```
</CodeBlockConfig>
</CodeTabs>
See [Admin Partition Rules](#admin-partition-rules) for another example rule that uses the `mesh` resource.
### Namespace Rules <EnterpriseAlert inline />
## Namespace Rules <EnterpriseAlert inline />
The `namespace` and `namespace_prefix` resource controls access to Consul namespaces. Namespaces define a scope of resources for which ACL rules apply. ACL rules, themselves, can then be defined to only to apply to specific namespaces.
@ -745,59 +482,92 @@ namespace "foo" {
}
}
```
</CodeBlockConfig>
<CodeBlockConfig>
```json
{
"namespace": [{
"foo": [{
"acl": "write",
"key_prefix": [{
"": [{
"policy": "write"
}]
}],
"node_prefix": [{
"": [{
"policy": "read"
}]
}],
"policy": "write",
"service_prefix": [{
"": [{
"policy": "write"
}]
}],
"session_prefix": [{
"": [{
"policy": "write"
}]
}]
}]
}],
"namespace_prefix": [{
"": [{
"node_prefix": [{
"": [{
"policy": "read"
}]
}],
"policy": "write",
"service_prefix": [{
"": [{
"policy": "read"
}]
}]
}]
}]
"namespace": [
{
"foo": [
{
"acl": "write",
"key_prefix": [
{
"": [
{
"policy": "write"
}
]
}
],
"node_prefix": [
{
"": [
{
"policy": "read"
}
]
}
],
"policy": "write",
"service_prefix": [
{
"": [
{
"policy": "write"
}
]
}
],
"session_prefix": [
{
"": [
{
"policy": "write"
}
]
}
]
}
]
}
],
"namespace_prefix": [
{
"": [
{
"node_prefix": [
{
"": [
{
"policy": "read"
}
]
}
],
"policy": "write",
"service_prefix": [
{
"": [
{
"policy": "read"
}
]
}
]
}
]
}
]
}
```
</CodeBlockConfig>
</CodeTabs>
#### Restrictions
### Restrictions
The following restrictions apply when a rule is defined in any user-created namespace:
@ -811,20 +581,20 @@ These restrictions do not apply to the `default` namespace created by Consul. In
above are permissions that only an operator should have and thus granting these permissions can
only be done within the default namespace.
#### Implicit Namespacing
### Implicit Namespacing
Rules and policies created within a namespace will inherit the namespace configuration.
This means that rules and policies will be implicitly namespaced and do not need additional configuration.
The restrictions outlined above will apply to these rules and policies. Additionally, rules and policies within a
specific namespace are prevented from accessing resources in another namespace.
### Node Rules
## Node Rules
The `node` and `node_prefix` resources control access to the following API behaviors:
* node-level registration and read access to the [Catalog API](/api/catalog)
* service discovery with the [Health API](/api/health)
* filtering results in [Agent API](/api/agent) operations, such as fetching the list of cluster members.
- node-level registration and read access to the [Catalog API](/api/catalog)
- service discovery with the [Health API](/api/health)
- filtering results in [Agent API](/api/agent) operations, such as fetching the list of cluster members.
You can use resource labels to scope the rule to a specific resource or set of resources.
@ -862,10 +632,11 @@ node "admin" {
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
#### Registering and Querying Node Information
### Registering and Querying Node Information
Agents must be configured with `write` privileges for their own node name so that the agent can register their node metadata, tagged addresses, and other information in the catalog.
If configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog.
@ -878,14 +649,14 @@ Node rules are used to filter query results when reading from the catalog or ret
Consul agents check tokens locally when health checks are registered and when Consul performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs.
These actions may required an ACL token to complete. Use the following methods to configure ACL tokens for registration events:
* Configure a global token in the [acl.tokens.default](/docs/agent/options#acl_tokens_default) parameter.
This allows a single token to be used during all check registration operations.
* Provide 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.
Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples.
Tokens may also be passed to the [HTTP API](/api) for operations that require them.
- Configure a global token in the [acl.tokens.default](/docs/agent/options#acl_tokens_default) parameter.
This allows a single token to be used during all check registration operations.
- Provide 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.
Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples.
Tokens may also be passed to the [HTTP API](/api) for operations that require them.
### Operator Rules
## Operator Rules
The `operator` resource controls access to cluster-level operations in the
[Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring).
@ -899,17 +670,18 @@ diagnostic purposes but it will not make changes.
```hcl
operator = "read"
```
</CodeBlockConfig>
<CodeBlockConfig>
```json
"operator" : "read"
```
</CodeBlockConfig>
</CodeTabs>
### Prepared Query Rules
## Prepared Query Rules
The `query` and `query_prefix` resources control access to create, update, and delete prepared queries in the
[Prepared Query API](/api/query). Specify the resource label in query rules to determine the scope of the rule.
@ -943,6 +715,7 @@ query "foo" {
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
@ -1017,7 +790,7 @@ These differences are outlined in the table below:
| List queries | A token with management privileges is required to list any queries. | The client token's `query` ACL policy is used to determine which queries they can see. Only tokens with management privileges can see prepared queries without `Name`. |
| Execute query | 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. | The captured token, client's token, or anonymous token is used to filter the results, as described above. |
### Service Rules
## Service Rules
The `service` and `service_prefix` resources control service-level registration and read access to the [Catalog API](/api/catalog) and service discovery with the [Health API](/api/health).
Specify the resource label in service rules to set the scope of the rule.
@ -1038,6 +811,7 @@ service "admin" {
policy = "deny"
}
```
</CodeBlockConfig>
<CodeBlockConfig>
@ -1056,6 +830,7 @@ service "admin" {
}]
}]
```
</CodeBlockConfig>
</CodeTabs>
@ -1116,13 +891,14 @@ service "app" {
"intentions" : "read"
}]
```
</CodeBlockConfig>
</CodeTabs>
Refer to [Intention Management Permissions](/docs/connect/intentions#intention-management-permissions)
for more information about managing intentions access with service rules.
### Session Rules
## Session Rules
The `session` and `session_prefix` resources controls access to [Session API](/api/session) operations.

359
website/content/docs/security/acl/acl-system.mdx
View file

@ -1,342 +1,91 @@
---
layout: docs
page_title: ACL System
page_title: Access Control List (ACL) Overview
description: >-
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.
This topic describes provides an overview of the optional access control list (ACL) system shipped with Consul. The ACL system authenticates requests and authorizes access to resources. It is used by the UI, API, and CLI for service-to-service communication and agent-to-agent communication.
---
# ACL System
# Access Control List (ACL) Overview
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.
This topic describes core concepts associated with the optioal access control list (ACL) system shipped with Consul. ACLs authenticate requests and authorize access to resources. They also control access to the Consul UI, API, and CLI, as well as secure service-to-service and agent-to-agent communication.
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.
Refer to the following tutorials for step-by-step instructions on how to get started using ACLs:
[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
- [Bootstrap and Explore ACLs]
- [Secure Consul with ACLs]
- [Troubleshoot the ACL System](https://learn.hashicorp.com/tutorials/consul/access-control-troubleshoot)
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).
[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
Refer to the [ACL API reference](/api-docs/acl) and [ACL CLI reference](/commands/acl) for additional usage information.
## Overview
## Workflow Overview
The diagram below shows the relationships between the core components of the ACL system:
Implementations may vary depending on the needs of the organization, but the following procedure describes the basic workflow for for creating and implementing ACLs:
1. The person responsible for administrating ACLs in your organization specifies one or more authentication rules to define a [policy](#policies).
1. The ACL administrator uses the Consul API to generate and link a [token](#tokens) to one or more policies. The following diagram illustrates the relationship between rules, policies, and tokens:
![ACL system component relationships](/img/acl-token-policy-rule-relationship.png)
The ACL administrator can create and link additional artifacts to tokens, such as [service identities](#service-identities), [node identities](#node-identities), and [roles](#roles) that enable policies to accommodate more complex requirements.
1. Tokens are distributed to end users and incorporated into their services.
1. Agents and services present the token when making requests.
1. Consul evaluates the token to determine if the request has permission to interact with the requested resource.
## Tokens
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 tokens are the core method of authentication in Consul. Tokens contain several attributes, but the value of the `SecretID` field (sometimes referred to as the ACL token) is the attribute that you or your service must include to identify the person or system making the request. Your ACL administrator may also use the token's `AccessorID` for audit logging purposes.
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.
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.
Consul HTTP API requests accept a token from an [HTTP Header](/api-docs/index#authentication),
and CLI requests accept a token from
[`-token` command line flag](/commands#authentication) or
[`CONSUL_HTTP_TOKEN_FILE` environment variable](/commands#consul_http_token_file).
Refer to the following topics for details about tokens:
- [Tokens](/docs/security/acl/acl-tokens)
- [ACL token command line](/commands/acl/token)
- [ACL tokens API](/api-docs/acl/tokens)
## 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.
An ACL policy is a set of rules grant or deny access to resources in the network.
The person responsible for administrating ACLs in your organization will assemble and create policies and link them to tokens.
Tokens are the artifacts distributed to users so that they can be implemented.
In addition to the rules that authenticate access to services, several attributes may be assigned policies that determine their scope.
ACL policies can have the following attributes:
Refer to the following topics for details about policies:
| Attribute | Description | Required | Default |
| --- | --- | --- | --- |
| `ID` | The policy's auto-generated public identifier. | N/A | N/A |
| `name` | Unique name for the policy. | Required | none |
| `description` | Human readable description of the policy. | Optional | none |
| `rules` | Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules#rule-specification) documentation for more details. | Optional | none |
| `datacenter` | Datacenter in which the policy is valid. More than one datacenter can be specified. | Optional | none |
| `namespace` | <EnterpriseAlert inline /> Namespace in which the policy is valid. Added in Consul Enterprise 1.7.0. | Optional | `default` |
| `partition` | <EnterpriseAlert inline /> Admin partition in which the policy is valid. Added in Consul Enterprise 1.11.0 | Optional | `default` |
-> **Non-default Namespaces and Partitions** - Rules defined in a policy tied to an namespace or admin partition other than `default` can only grant a subset of privileges that affect the namespace or partition. See [Namespace Rules](/docs/acl/acl-rules#namespace-rules) and [Admin Partition Rules](/docs/acl/acl-rules#admin-partition-rules) for additional information.
You can view the current ACL policies on the command line or through the API. The following example demonstrates the command line usage:
```shell-session
$ consul acl policy list -format json -token <token_id>
[
{
"ID": "56595ec1-52e4-d6de-e566-3b78696d5459",
"Name": "b-policy",
"Description": "",
"Datacenters": null,
"Hash": "ULwaXlI6Ecqb9YSPegXWgVL1LlwctY9TeeAOhp5HGBA=",
"CreateIndex": 126,
"ModifyIndex": 126,
"Namespace": "default",
"Partition": "default"
},
{
"ID": "00000000-0000-0000-0000-000000000001",
"Name": "global-management",
"Description": "Builtin Policy that grants unlimited access",
"Datacenters": null,
"Hash": "W1bQuDAlAlxEb4ZWwnVHplnt3I5oPKOZJQITh79Xlog=",
"CreateIndex": 70,
"ModifyIndex": 70,
"Namespace": "default",
"Partition": "default"
}
]
```
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
- **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** - <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)
## Service Identities
-> Added in Consul 1.5.0
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:
- **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](/docs/acl/acl-system#acl-rules-and-scope):
```hcl
# 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](/api/acl/roles#sample-payload) has some
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.
## Node Identities
-> Added in Consul 1.8.1
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:
- **Node Name** - The name of the node to grant access to.
- **Datacenter** - The datacenter that the node resides within.
During the authorization process, the configured node identity is automatically
applied as a policy with the following preconfigured [ACL
rules](/docs/acl/acl-system#acl-rules-and-scope):
```hcl
# Allow the agent to register its own node in the Catalog and update its network coordinates
node "<Node Name>" {
policy = "write"
}
# Allows the agent to detect and diff services registered to itself. This is used during
# anti-entropy to reconcile difference between the agents knowledge of registered
# services and checks in comparison with what is known in the Catalog.
service_prefix "" {
policy = "read"
}
```
-> **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.
- [Policies](/docs/security/acl/policies)
- [ACL policy command line](/commands/acl/policy)
- [ACL policy API](/api-docs/acl/policies)
## Roles
-> Added in Consul 1.5.0
A role is a collection of policies that your ACL administrator can link to a token.
They enable you to reuse policies by decoupling the policies from the token distributed to team members.
Instead, the token is linked to the role, which is able to hold several policies that can be updated asynchronously without distributing new tokens to users.
As a result, roles can provide a more convenient authentication infrastrcture than creating unique policies and tokens for each requester.
An ACL role is a named set of policies and service identities and is composed
of the following elements:
Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional information.
- **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** <EnterpriseAlert inline /> - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
## Service Identities
-> **Linking Roles to Policies in Consul Enterprise** - Roles can only be linked to policies that are defined in the same namespace and admin partition.
An ACL service identity is an ACL policy template for expressing a link to a policy suitable for use in a [service mesh](/docs/connect).
#### ACL Rules and Scope
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.
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 an allowlist or denylist
mode depending on the configuration of [`acl_default_policy`](/docs/agent/options#acl_default_policy).
If the default policy is to "deny" access to all resources, then policy rules can be set to
allowlist access to specific resources. Conversely, if the default policy is “allow” then policy rules can
be used to explicitly deny access to resources.
Service identities can be used in tokens and roles. Refer to the following topics for additional information about service identities:
The following table summarizes the ACL resources that are available for constructing
rules:
- [Service Identities](/docs/security/acl/acl-roles#service-identities)
- [API documentation for roles](/api/acl/roles#sample-payload)
| Resource | Scope |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`acl`](/docs/acl/acl-rules#acl-resource-rules) | Operations for managing the ACL system [ACL API](/api/acl/acl) |
| [`agent`](/docs/acl/acl-rules#agent-rules) | Utility operations in the [Agent API](/api/agent), other than service and check registration |
| [`event`](/docs/acl/acl-rules#event-rules) | Listing and firing events in the [Event API](/api/event) |
| [`key`](/docs/acl/acl-rules#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv) |
| [`keyring`](/docs/acl/acl-rules#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring) |
| [`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) |
| [`operator`](/docs/acl/acl-rules#operator-rules) | Cluster-level operations in the [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring) |
| [`query`](/docs/acl/acl-rules#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query) |
| [`service`](/docs/acl/acl-rules#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Intentions API](/api/connect/intentions), [Prepared Query API](/api/query), and [Agent API](/api/agent) |
| [`session`](/docs/acl/acl-rules#session-rules) | Session operations in the [Session API](/api/session) |
## Node Identities
Since Consul snapshots actually contain ACL tokens, the [Snapshot API](/api/snapshot)
requires a token with "write" privileges for the ACL system.
A node identity is a template that can be configured in tokens and roles.
They link nodes to policies suitable for use as an [Consul `agent` token](/docs/agent/options#acl_tokens_agent).
During the authorization process, the configured node identity is automatically applied as a policy.
The following resources are not covered by ACL policies:
Refer to the following topics for additional information about node identities:
1. The [Status API](/api/status) 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#list-datacenters) similarly exposes the names of known
Consul datacenters, and does not allow modification of any state.
3. 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.
Constructing rules from these policies is covered in detail on the
[ACL Rules](/docs/acl/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](/docs/enterprise/namespaces#namespace-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`](/docs/agent/options#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled |
| [`acl.default_policy`](/docs/agent/options#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode |
| [`acl.down_policy`](/docs/agent/options#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails |
| [`acl.role_ttl`](/docs/agent/options#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles |
| [`acl.policy_ttl`](/docs/agent/options#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies |
| [`acl.token_ttl`](/docs/agent/options#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens |
## Special and builtin 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_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | `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 Recovery Token](#acl-agent-recovery-token) section for more details |
| [`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 |
| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, check the [Bootstrapping ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) tutorial for more details |
| [`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 |
All of these tokens except the `initial_management` token can all be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens).
In Consul 1.4 - 1.10, the following special tokens were known by different names:
| New Name (1.11+) | Old Name (1.4 - 1.10) |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) |
| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) |
#### 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.
#### 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
In Consul 1.4 - 1.10, this was called the `agent_master` token. It was renamed to `agent_recovery` token in Consul 1.11.
```hcl
agent "<node name of agent>" {
policy = "write"
}
node_prefix "" {
policy = "read"
}
```
#### ACL Agent Token
The [`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` 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](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/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/exec) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
```hcl
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](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted.
## Next Steps
Continue reading about [ACL rules](/docs/acl/acl-rules).
- [Node Identities](/docs/security/acl/acl-roles#node-identities)
- [API documentation for roles](/api/acl/roles#sample-payload)

248
website/content/docs/security/acl/acl-tokens.mdx Normal file
View file

@ -0,0 +1,248 @@
---
layout: docs
page_title: Tokens
description: >-
This topic describes access control list (ACL) tokens. Tokens are the core method of authentication in Consul.
---
# Tokens
This topic describes access control list (ACL) tokens, which are the core method of authentication in Consul.
## Introduction
Tokens are artifacts in the ACL system used to authenticate users, services, and Consul agents. When ACLs are enabled, entities requesting access to a resource must include a token that has been linked with a policy, service identity, or node identity that grants permission to the resource. The ACL system checks the token and grants or denies access to resource based on the associated permissions.
Refer to the [ACL system workflow overview](/docs/security/acl/acl-system#workflow-overview) for an information about tokens' role in the ACL system.
## Creating Tokens
The person responsible for administrating ACLs can use the API or CLI to create and link tokens to entities that enable permissions to resources.
Refer to the [ACL API ](/api-docs/acl) and [ACL CLI](/commands/acl) documentation for instructions on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an
[auth method](/docs/security/acl/auth-methods).
## Passing Tokens
Users deploying their services into the network or performing some operations in the Consul command line or GUI will need to include the value of the token's `SecretID` attribute. The `SecretID` is often referred to as the ACL token. It is an opaque string that identifies the requester so that the ACL system can determine if access to the requested resource should be granted or denied.
Tokens have several additional attributes. Refer to the (see [Token Attributes](#token-attributes)).
### Service Requests
Specify the value of the `SecretID` attribute with the `token` parameter when configuring your services. In the following example service configuration, the `token` has been included as a string parameter to the `redis` service:
<CodeTabs>
<CodeBlockConfig lineNumbers highlight="6">
```hcl
"service" = {
"id" = "redis"
"name" = "redis"
...
"namespace" = "foo"
"token" = "233b604b-b92e-48c8-a253-5f11514e4b50"
}
```
</CodeBlockConfig>
<CodeBlockConfig lineNumbers highlight="6">
```json
{
"service": {
"id": "redis",
"name": "redis",
...
"token": "233b604b-b92e-48c8-a253-5f11514e4b50",
"namespace": "foo"
}
}
```
</CodeBlockConfig>
</CodeTabs>
Refer to the [service definitions documentation](/docs/discovery/services#service-definition) for additional information.
### Agent Requests
Consul agents can be configured to hold several ACL tokens (see [`tokens`](/docs/agent/options#acl_tokens_default)) to accommodate several use cases. The following table describes agent configuration fields where ACLs are applicable and whether the configurations apply to servers, clients, or both.
| Configuration Option | Servers | Clients | Purpose |
| -------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- |
| [`acl.enabled`](/docs/agent/options#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled |
| [`acl.default_policy`](/docs/agent/options#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode |
| [`acl.down_policy`](/docs/agent/options#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails |
| [`acl.role_ttl`](/docs/agent/options#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles |
| [`acl.policy_ttl`](/docs/agent/options#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies |
| [`acl.token_ttl`](/docs/agent/options#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens |
In the following example, the agent is configured to use a default token:
<CodeTabs>
<CodeBlockConfig>
```hcl
"tokens" = {
"default" = "233b604b-b92e-48c8-a253-5f11514e4b50"
}
```
</CodeBlockConfig>
<CodeBlockConfig>
```json
{
"tokens": {
"default": "233b604b-b92e-48c8-a253-5f11514e4b50"
}
}
```
</CodeBlockConfig>
</CodeTabs>
Refer to the [agent configurations documentation]() for additional information.
### Command Line Requests
To make a request on the command line, specify the ACL token with the [`-token` command line flag](/commands#authentication).
In the following example, a token is included to enable the user to create an intention on the command line:
```shell-session
$ consul intention create -file one.json two.json -token "233b604b-b92e-48c8-a253-5f11514e4b50"
```
Refer to the documentation for the command line operations you want to perform for additional information.
#### Environment Variables
You can export tokens to environment variables on the local machine, which enable you to omit the `-token` flag when performing operations on the Consul command line. Refer to the [Consul command line documentation](/commands#environment-variables) for details.
### API Requests
Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs/index#authentication) for details.
The following example shows the header for a GET request to the `agent/members` endpoint.
```shell-session
$ curl --header "X-Consul-Token: <token>" "http://127.0.0.1:8500/v1/agent/members"
```
## Token Attributes
The following table is a partial list of attributes that a token may contain.
Refer to the [API](/api-docs/acl/token) or [command line](/commands/acl/token) documentation for all attributes that can be assigned or generated for a token:
| Attribute | Description | Type | Default |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- |
| `AccessorID` | Used for [audit logging](/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated |
| `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated |
| `Partition` | <EnterpriseAlert inline/> Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. | `default` |
| `Namespace` | <EnterpriseAlert inline/> Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/docs/enterprise/namespaces) for additional information. | String | `default` |
| `Description` | Human-readable description for documenting the purpose of the token. | String | none |
| `Local` | Indicates whether the token should be replicated globally or local to the datacenter. <br/> Set to `false` to replicate globally across all reachable datacenters. <br/>Setting to `true` configures the token to functional in the local datacenter only. | Boolean | `false` |
| `ServiceIdentities` | Specifies a list of nodes to apply to the token. See [Service Identities](/docs/security/roles#service-identities) in the "Roles" topic for additional information. | Array | none |
| `NodeIdentities` | Specifies a list of nodes to apply to the token. See [Node Identities](/docs/security/roles##node-identities) in the "Roles" topic for additional information. | Array | none |
| `Legacy` | Indicates if the token was created using the the legacy ACL system. | Boolean | `false` |
| `Policies` | List of policies linked to the token, including the policy ID and name. | String | none |
## Special-purpose Tokens
Your ACL admininstrator can configure several tokens that enable specific functions, such as bootstrapping the ACL
system or accessing Consul under specific conditions. The following table describes the special-purpose tokens:
| Token | Servers | Clients | Description |
| ------------------------------------------------------------------------------------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | `OPTIONAL` | `OPTIONAL` | Enables access to the [Agent API](/api/agent) when remote bearer token resolution fails. <br/>Used for setting up the cluster and performing initial join operations. <br/>See [ACL Agent Recovery Token](#acl-agent-recovery-token) for details. |
| [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Used for internal agent operations. See [ACL Agent Token](#acl-agent-token) for details. |
| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Used to bootstrap the ACL system. See [Initial Management Token](#initial-management-token). |
| [`acl.tokens.default`](/docs/agent/options#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Specifies a default token to use for client requests if no token is supplied. This is commonly configured with read-only access to services to enable DNS service discovery on agents. |
All reserved tokens except the `initial_management` token can be created or updated using the [/v1/agent/token API](/api/agent#update-acl-tokens).
### Snapshot Tokens
Snapshots are artifacts created with the [snapshot API](/api/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and require, and interacting with them requires a token with `write` privileges.
### ACL Agent Token
The [`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` 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](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/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/exec) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
```hcl
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](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted.
<!-- Consider removing this content now that we have versioned docs
In Consul 1.4 - 1.10, the following special tokens were known by different names:
| New Name (1.11+) | Old Name (1.4 - 1.10) |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) |
| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) |
-->
## Built-in Tokens
Consul includes a built-in anonymous token and intial management token. Both tokens are injected during when you bootstrap the cluster.
### Anonymous Token
The anonymous token is used when a request is made to Consul without specifying a bearer token.
This token has the following attributes (see [Token Attributes](#token-attributes) for additional information):
- `AccessorID`: `00000000-0000-0000-0000-000000000002`
- `SecretID`: `anonymous`
The description and policies may be updated, but the anonymous token cannot be deleted.
### Initial Management Token
Including an initial management token in the Consul configuration creates the token and links it with the built-in global management policy.
The bearer will have have unrestricted privileges to resources and APIs.
The `SecretID` attribute will be set to the value of the configuration entry.
See the [Bootstrapping ACLs tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for guidance on bootstrapping.
<!-- Consider removing this content now that we have versioned docs
In Consul 1.4 - 1.10, this was called the `master` token. It was renamed to `initial_management` token in Consul 1.11.
-->
### ACL Agent Recovery Token
The [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) is designed to be used when the Consul servers are not available. The policy linked to the token is managed locally on the agent and does not require a token to be defined on the Consul servers. Once set, it implicitly has the following policy associated with it
<!-- Consider removing this content now that we have versioned docs
In Consul 1.4 - 1.10, this was called the `agent_master` token. It was renamed to `agent_recovery` token in Consul 1.11.
-->
```hcl
agent "<node name of agent>" {
policy = "write"
}
node_prefix "" {
policy = "read"
}
```

70
website/content/docs/security/acl/index.mdx
View file

@ -1,70 +0,0 @@
---
layout: docs
page_title: ACL Guides
description: >-
Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. Select the following guide for your use
case.
---
# ACL Documentation and Guides
Consul uses Access Control Lists (ACLs) to secure the UI, API, CLI, service
communications, and agent communications. At the core, ACLs operate by grouping
rules into policies, then associating one or more policies with a token.
The following documentation and guides will help you understand and implement
ACLs.
## ACL Documentation
### 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. The
[ACL System documentation](/docs/acl/acl-system) details the functionality
of Consul ACLs.
### ACL Rules
A core part of the ACL system is the rule language, which is used to describe
the policy that must be enforced. Read the ACL rules
[documentation](/docs/acl/acl-rules) to learn about rule specifications.
### ACL Auth Methods
An auth method is a component in Consul that performs authentication against a
trusted external party to authorize the creation of an ACL tokens usable within
the local datacenter. Read the ACL auth method
[documentation](/docs/acl/auth-methods) to learn more about how they
work and why you may want to use them.
### ACL Legacy System
The ACL system in Consul 1.3.1 and older is now called legacy. For information
on bootstrapping the legacy system, ACL rules, and a general ACL system
overview, read the legacy [documentation](/docs/acl/acl-legacy).
### ACL Migration
[The migration documentation](/docs/acl/acl-migrate-tokens) details how to
upgrade existing legacy tokens after upgrading to 1.4.0. It will briefly
describe what changed, and then walk through the high-level migration process
options, finally giving some specific examples of migration strategies. The new
ACL system has improvements for the security and management of ACL tokens and
policies.
## Learn ACL Guide
~> Note: the following guide is located on HashiCorp Learn. By selecting it,
you will be directed to a new site.
### Securing Consul with ACLs
In this guide, you will learn how to secure the UI, API, CLI, service
communications, and agent communications with ACLs. When securing your cluster
you should configure the ACLs first. The ACL documentation introduces basic
concepts and syntax for the ACL system, and we recommend that you read it
before you begin [this
tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).

20
website/data/docs-nav-data.json
View file

@ -799,15 +799,23 @@
"title": "Access Control (ACLs)",
"routes": [
{
"title": "Overview",
"path": "security/acl"
},
{
"title": "ACL System",
"title": "ACL System Overview",
"path": "security/acl/acl-system"
},
{
"title": "ACL Rules",
"title": "Tokens",
"path": "security/acl/acl-tokens"
},
{
"title": "Policies",
"path": "security/acl/acl-policies"
},
{
"title": "Roles",
"path": "security/acl/acl-roles"
},
{
"title": "Rules Reference",
"path": "security/acl/acl-rules"
},
{