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

Merge pull request #12460 from hashicorp/docs-day-acl-improvements 

Docs day acl improvements
This commit is contained in:
trujillo-adam 2022-03-08 19:34:26 -08:00 committed by GitHub
parent b4276e971e 4274de868d
commit 19cfa8bcaa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 1468 additions and 916 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/api-docs/index.mdx
View File

@ -18,7 +18,11 @@ requests using the `X-Consul-Token` header or with the
Bearer scheme in the authorization header.
This reduces the probability of the
token accidentally getting logged or exposed. When using authentication,
clients should communicate via TLS. If you don’t provide a token in the request, then the agent default token will be used.
clients should communicate via TLS.
If no token is provided for an HTTP request then Consul will use the default ACL token
if it has been configured. If no default ACL token was configured then the anonymous
token will be used.
Below is an example using `curl` with `X-Consul-Token`.
@ -28,7 +32,7 @@ $ curl \
http://127.0.0.1:8500/v1/agent/members
```
Below is an example using `curl` with Bearer scheme.
Below is an example using `curl` with a [RFC6750](https://tools.ietf.org/html/rfc6750) Bearer token.
```shell-session
$ curl \

9
website/content/commands/index.mdx
View File

@ -91,6 +91,15 @@ Command Options
Joins a server to another server in the WAN pool.
```
## Authentication
When the [ACL system is enabled](/docs/agent/options#acl_enabled) the Consul CLI will
require an [ACL token](/docs/security/acl/acl-system#tokens) to perform API requests.
The ACL token can be provided directly on the command line using the `-token` command line flag,
from a file using the `-token-file` command line flag, or from the
[`CONSUL_HTTP_TOKEN`](#consul_http_token_file) environment variable.
## Autocompletion
The `consul` command features opt-in subcommand autocompletion that you can

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

@ -0,0 +1,543 @@
---
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 provides access to all keys with the specified resource label in the [Consul KV](/commands/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 resources 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 you can specify `allowlist` in policy rules to explicitly allow access to resources.
Conversely, if the default policy is configured to allow access to all resources, then you can specify `denylist` in policy rules 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-in 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.
## Example Policies
This section includes example policy configurations for achieving specific use-cases.
### Enable the Snapshot Agent to Run on a Specific Node
The `consul snapshot agent` command starts a process that takes snapshots of the state of the Consul servers and either saves them locally or pushes them to a remote storage service. Refer to [Consul Snapshot Agent](/commands/snapshot/agent) for additional information.
In the following example, the ACL policy enables the snapshot agent to run on a node named `server-1234`.
<CodeTabs>
```hcl
# Required to read and snapshot ACL data
acl = "write"
# Allow the snapshot agent to create the key consul-snapshot/lock which will
# serve as a leader election lock when multiple snapshot agents are running in
# an environment
key "consul-snapshot/lock" {
policy = "write"
}
# Allow the snapshot agent to create sessions on the specified node
session "server-1234" {
policy = "write"
}
# Allow the snapshot agent to register itself into the catalog
service "consul-snapshot" {
policy = "write"
}
```
```json
{
"acl": "write",
"key": {
"consul-snapshot/lock": {
"policy": "write"
}
},
"session": {
"server-1234": {
"policy": "write"
}
},
"service": {
"consul-snapshot": {
"policy": "write"
}
}
}
```
</CodeTabs>
### Enable Vault to Access the Consul Storage Backend
If you are using [Vault](https://www.vaultproject.io/docs) to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/docs/dynamic-app-config/kv) and the [Vault storage documentation](https://www.vaultproject.io/docs/configuration/storage) for additional information.
In the following example, Vault is registered as a service and provided access to Consul's KV store.
<CodeTabs>
```hcl
# Provide KV visibility to all agents.
agent_prefix "" {
"policy" = "read"
}
# Enable resources prefixed with 'vault/' to write to the KV
key_prefix "vault/" {
"policy" = "write"
}
# Enable the vault service to write to the KV
service "vault" {
"policy" = "write"
}
# Enable the agent to initialize a new session.
session_prefix "" {
"policy" = "write"
}
```
```json
{
"key_prefix": {
"vault/": {
"policy": "write"
}
},
"service": {
"vault": {
"policy": "write"
}
},
"agent_prefix": {
"": {
"policy": "read"
}
},
"session_prefix": {
"": {
"policy": "write"
}
}
}
```
</CodeTabs>

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

@ -0,0 +1,372 @@
---
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 enable you to reuse policies by decoupling the policies from the token distributed to team members.
---
# 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 linking 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](/commands/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 --request 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 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 that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See [Namespaces](/docs/enterprise/namespaces) for additional information. Requires Consul Enterprise 1.7.0+
- `Partition`: <EnterpriseAlert inline/> The admin partition that the policy resides in. Roles can only be linked to policies that are defined in the same admin partition. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.10.0+.
## Service Identities
<!-- -> Added in Consul 1.5.0 # Remove and lean on versioning?-->
You can specify a service identity when configuring roles or linking tokens to policies. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service.
Service identities are used during the authorization process to automatically generate a policy for the service(s) specifed. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. Refer to the [service mesh](/docs/connect) topic for additional information about Consul service mesh.
### Service Identity Specification
Use the following syntax to define a service identity:
<CodeTabs>
```json
{
"ServiceIdentities": [
{
"ServiceName": "<service name>",
"Datacenters": ["<datacenter name>"]
}
]
}
```
```hcl
"ServiceIdentities" = {
"ServiceName" = "<service name>"
"Datacenters" = ["<datacenter name>"]
}
```
</CodeTabs>
- `ServiceIdentities`: Declares a service identity block.
- `ServiceIdentities.ServiceName`: String value that specifies the name of the service you want to associate with the policy.
- `ServiceIdentitites.Datacenters`: Array that specifies the names of datacenters in which the service identity applies. This field is optional.
Refer to the the [API documentation for roles](/api/acl/roles#sample-payload) for additional information and examples.
-> **Scope for Namespace and Admin Partition** - In Consul Enterprise, service identities inherit the namespace or admin partition scope of the corresponding ACL token or role.
The following policy is generated for each service when a service identity is declared:
```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"
}
```
Refer to the [rules reference](/docs/security/acl/acl-rules) for information about the rules in the policy.
### Example
The following role configuration contains service identities for the `web` and `db` services. Note that the `db` service is also scoped to the `dc1` datacenter so that the policy will only be applied to instances of `db` in `dc1`.
<CodeTabs>
<CodeBlockConfig filename="example-role.hcl">
```hcl
Description = "Showcases all input parameters"
Name = "example-role"
Policies = {
ID = "783beef3-783f-f41f-7422-7087dc272765"
}
Policies = {
Name = "node-read"
}
ServiceIdentities = {
ServiceName = "web"
}
ServiceIdentities = {
Datacenters = ["dc1"]
ServiceName = "db"
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="example-role.json">
```json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765"
},
{
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": ["dc1"]
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
]
}
```
</CodeBlockConfig>
</CodeTabs>
During the authorization process, the following policies for the `web` and `db` services will be generated and linked to the token:
<CodeBlockConfig filename="web-policy.hcl">
```hcl
# Allow the service and its sidecar proxy to register into the catalog.
service "web" {
policy = "write"
}
service "web-sidecar-proxy" {
policy = "write"
}
# Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
```
</CodeBlockConfig>
Per the `ServiceIdentitites.Datacenters` configuration, the `db` policy is scoped to resources in the `dc1` datacenter.
<CodeBlockConfig filename="db-policy.hcl">
```hcl
# Allow the service and its sidecar proxy to register into the catalog.
service "db" {
policy = "write"
}
service "db-sidecar-proxy" {
policy = "write"
}
# Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
```
</CodeBlockConfig>
## Node Identities
<!-- -> Added in Consul 1.8.1 -- remove and lean on doc version? -->
You can specify a node identity when configuring roles or linking tokens to policies. _Node_ commonly refers to a Consul agent, but a node can also be a physical server, cloud instance, virtual machine, or container.
Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specifed. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
### Node Identity Specification
Use the following syntax to define a node identity:
<CodeTabs>
```json
{
"NodeIdentities": [
{
"NodeName": "<node name>",
"Datacenters": ["<datacenter name>"]
}
]
}
```
```hcl
NodeIdentities = {
NodeName = "<node name>"
Datacenters = ["<datacenter name>"]
}
```
</CodeTabs>
- `NodeIdentities`: Declares a node identity block.
- `NodeIdentities.NodeName`: String value that specifies the name of the node you want to associate with the policy.
- `NodeIdentitites.Datacenters`: Array that specifies the names of datacenters in which the node identity applies. This field is optional.
Refer to the the [API documentation for roles](/api/acl/roles#sample-payload) for additional information and examples.
-> **Consul Enterprise Namespacing** - Node Identities can only be applied to tokens and roles in the `default` namespace. The generated policy rules allow for `service:read` permissions on all services in all namespaces.
The following policy is generated for each node when a node identity is declared:
```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"
}
```
Refer to the [rules reference](/docs/security/acl/acl-rules) for information about the rules in the policy.
### Example
The following role configuration contains a node identity for `node-1`. Note that the node identity is also scoped to the `dc2` datacenter. As a result, the policy will only be applied to nodes named `node-1` in `dc2`.
<CodeTabs>
<CodeBlockConfig filename="example-role.hcl">
```hcl
Description = "Showcases all input parameters"
Name = "example-role"
NodeIdentities = {
Datacenter = "dc2"
NodeName = "node-1",
}
Policies = {
ID = "783beef3-783f-f41f-7422-7087dc272765"
}
Policies = {
Name = "node-read"
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="example-role.json">
```json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765"
},
{
"Name": "node-read"
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
]
}
```
</CodeBlockConfig>
</CodeTabs>
During the authorization process, the following policy will be generated and linked to the token:
<CodeBlockConfig filename="node-1-policy.hcl">
```hcl
# Allow the agent to register its own node in the Catalog and update its network coordinates
node "node-1" {
policy = "write"
}
# Allows the agent to detect and diff services registered to itself. This is used during
# anti-entropy to reconcile differences between the agent's knowledge of registered
# services and checks in comparison with what is known in the Catalog.
service_prefix "" {
policy = "read"
}
```
</CodeBlockConfig>

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/security/acl/acl-system) to learn more about ACLs.
This topic provides reference information for the types of access control list (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/security/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 resource, 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 provides 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-docs/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 successfully 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\""
}
```
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-docs/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](#service-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-docs/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/architecture/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/discovery/services) and [checks](/docs/discovery/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.

429
website/content/docs/security/acl/acl-system.mdx
View File

@ -1,429 +0,0 @@
---
layout: docs
page_title: ACL System
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.
---
# ACL System
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/security/acl/acl-legacy).
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs.
The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which
are associated with policies to determine which fine grained rules can be applied. Consul's capability based
ACL system is very similar to the design of [AWS IAM](https://aws.amazon.com/iam/).
To learn how to setup the ACL system on an existing Consul datacenter, use the [Bootstrapping The ACL System tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup?utm_source=consul.io&utm_medium=docs).
## ACL System Overview
The ACL system is designed to be easy to use and fast to enforce while providing administrative insight.
The diagram below shows the relationships between most of the components of the ACL system:
![ACL system component relationships](/img/acl-token-policy-rule-relationship.png)
At the highest level, there are two major components to the ACL system:
- **ACL Policies** - Policies allow the grouping of a set of rules into a logical unit that can be reused and linked with
many tokens.
- **ACL Tokens** - Requests to Consul are authorized by using bearer token. Each ACL token has a public
Accessor ID which is used to name a token, and a Secret ID which is used as the bearer token used to
make requests to Consul.
For many scenarios policies and tokens are sufficient, but more advanced setups
may benefit from additional components in the ACL system:
- **ACL Roles** - Roles allow for the grouping of a set of policies and service
identities into a reusable higher-level entity that can be applied to many
tokens. (Added in Consul 1.5.0)
- **ACL Service Identities** - Service identities are a policy template for
expressing a link to a policy suitable for use in [Consul
Connect](/docs/connect). At authorization time this acts like an
additional policy was attached, the contents of which are described further
below. These are directly attached to tokens and roles and are not
independently configured. (Added in Consul 1.5.0)
- **ACL Node Identities** - Node identities are a policy template for
expressing a link to a policy suitable for use as an [Consul `agent` token
](/docs/agent/options#acl_tokens_agent). At authorization time this acts like an
additional policy was attached, the contents of which are described further
below. These are directly attached to tokens and roles and are not
independently configured. (Added in Consul 1.8.1)
- **ACL Auth Methods and Binding Rules** - To learn more about these topics,
see the [auth methods documentation page](/docs/security/acl/auth-methods).
ACL tokens, policies, roles, auth methods, and binding rules are managed by
Consul operators via Consul's [ACL API](/api-docs/acl),
[ACL CLI](/commands/acl), or systems like
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul).
If the ACL system becomes inoperable, you can follow the
[reset procedure](https://learn.hashicorp.com/tutorials/consul/access-control-troubleshoot#reset-the-acl-system) at any time.
### ACL Policies
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](/commands/acl/policy) documentation or [ACL policy API](/api-docs/acl/policies) documentation for additional information on how to create policies.
ACL policies can have the following attributes:
| 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/security/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/security/acl/acl-rules#namespace-rules) and [Admin Partition Rules](/docs/security/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)
### ACL Service Identities
-> Added in Consul 1.5.0
An ACL service identity is an [ACL policy](/docs/security/acl/acl-system#acl-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/security/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.
### ACL Node Identities
-> Added in Consul 1.8.1
An ACL node identity is an [ACL policy](/docs/security/acl/acl-system#acl-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/security/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.
### ACL Roles
-> Added in Consul 1.5.0
An ACL role is a named set of policies and service identities and is composed
of the following elements:
- **ID** - The role's auto-generated public identifier.
- **Name** - A unique meaningful name for the role.
- **Description** - A human readable description of the role. (Optional)
- **Policy Set** - The list of policies that are applicable for the role.
- **Service Identity Set** - The list of service identities that are applicable for the role.
- **Namespace** <EnterpriseAlert inline /> - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
-> **Linking Roles to Policies in Consul Enterprise** - Roles can only be linked to policies that are defined in the same namespace and admin partition.
### ACL Tokens
Consul uses ACL tokens to determine if the caller is authorized to perform an action. An ACL token is composed of several attributes that you can specify when creating the token. Refer to the [ACL token command line](/commands/acl/token) documentation or [ACL token API](/api-docs/acl/tokens) documentation for additional information on how to create tokens.:
- **Accessor ID** - The token's public identifier.
- **Secret ID** -The bearer token used when making requests to Consul.
- **Policy Set** - The list of policies that are applicable for the token.
- **Role Set** - The list of roles that are applicable for the token. Added in Consul 1.5.0.
- **Service Identity Set** - The list of service identities that are applicable for the token. Added in Consul 1.5.0
- **Local** - Indicates whether the token is local to the datacenter in which it was created. The attribute also can specify if the token was created in the primary datacenter and globally replicated.
- **CreateTime** - Timestamp indicating when the token was created.
- **Expiration Time** - The time at which this token is revoked. This attribute is option when creating a token. Added in Consul 1.5.0.
- **Namespace** <EnterpriseAlert inline /> - The namespace in which the token resides. Added in Consul Enterprise 1.7.0.
- **Partition** <EnterpriseAlert inline /> - The partition in which the token resides. Added in Consul Enterprise 1.11.0.
-> **Linking Tokens to Policies in Consul Enterprise** - Tokens can only be linked to policies that are defined in the same namespace and admin partition.
You can view the current ACL tokens on the command line or through the API. The following example demonstrates the command line usage:
```shell-session
$ consul acl token list -format json -token <token_id>
[
{
"CreateIndex": 75,
"ModifyIndex": 75,
"AccessorID": "c3274caa-fbe4-b457-f4af-c05ba89a048d",
"SecretID": "105c016a-ae9c-2006-ce23-4ef8823ba2af",
"Description": "Bootstrap Token (Global Management)",
"Policies": [
{
"ID": "00000000-0000-0000-0000-000000000001",
"Name": "global-management"
}
],
"Local": false,
"CreateTime": "2021-12-16T10:22:08.906291-08:00",
"Hash": "Wda9obh/gvreyTbVhbyJ3ipX0M/apF4kpqowPQQx+u8=",
"Legacy": false,
"Namespace": "default",
"Partition": "default"
},
{
"CreateIndex": 71,
"ModifyIndex": 71,
"AccessorID": "00000000-0000-0000-0000-000000000002",
"SecretID": "anonymous",
"Description": "Anonymous Token",
"Local": false,
"CreateTime": "2021-12-16T10:21:11.996298-08:00",
"Hash": "tgCOyeidw+oaoZXQ9mHy6+EnY7atKoGaBzg2ndTwXl0=",
"Legacy": false,
"Namespace": "default",
"Partition": "default"
}
]
```
Note that the `CreateIndex`, `ModifyIndex`, and `Hash` attributes are also printed. These attributes are printed for all responses and are not specific to ACL tokens.
#### Builtin Tokens
During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `initial_management` token will be
injected.
- **Anonymous Token** - The anonymous token is used when a request is made to Consul without specifying a bearer token.
The anonymous token's description and policies may be updated but Consul will prevent this token's deletion. When created,
it will be assigned `00000000-0000-0000-0000-000000000002` for its Accessor ID and `anonymous` for its Secret ID.
- **Initial Management Token** - When an initial management token is present within the Consul configuration, it is created
and will be linked with the builtin Global Management policy giving it unrestricted privileges. The initial management
token is created with the Secret ID set to the value of the configuration entry.
In Consul 1.4 - 1.10, this was called the `master` token. It was renamed to `initial_management` token in Consul 1.11.
#### Authorization
The token Secret ID is passed along with each RPC request to the servers. Consul's
[HTTP endpoints](/api) can accept tokens via the `token`
query string parameter, the `X-Consul-Token` request header, or an
[RFC6750](https://tools.ietf.org/html/rfc6750) authorization bearer token. Consul's
[CLI commands](/commands) can accept tokens via the
`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. The CLI
commands can also accept token values stored in files with the `token-file`
argument, or the `CONSUL_HTTP_TOKEN_FILE` environment variable.
If no token is provided for an HTTP request then Consul will use the default ACL token
if it has been configured. If no default ACL token was configured then the anonymous
token will be used.
#### ACL Rules and Scope
The rules from all policies, roles, and service identities linked with a token are combined to form that token's
effective rule set. Policy rules can be defined in either 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.
The following table summarizes the ACL resources that are available for constructing
rules:
| Resource | Scope |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`acl`](/docs/security/acl/acl-rules#acl-resource-rules) | Operations for managing the ACL system [ACL API](/api-docs/acl) |
| [`agent`](/docs/security/acl/acl-rules#agent-rules) | Utility operations in the [Agent API](/api/agent), other than service and check registration |
| [`event`](/docs/security/acl/acl-rules#event-rules) | Listing and firing events in the [Event API](/api/event) |
| [`key`](/docs/security/acl/acl-rules#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv) |
| [`keyring`](/docs/security/acl/acl-rules#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring) |
| [`node`](/docs/security/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/security/acl/acl-rules#operator-rules) | Cluster-level operations in the [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring) |
| [`query`](/docs/security/acl/acl-rules#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query) |
| [`service`](/docs/security/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/security/acl/acl-rules#session-rules) | Session operations in the [Session API](/api/session) |
Since Consul snapshots actually contain ACL tokens, the [Snapshot API](/api/snapshot)
requires a token with "write" privileges for the ACL system.
The following resources are not covered by ACL policies:
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/security/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 |
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) |
#### 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/architecture/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
Setup ACLs with the [Bootstrapping the ACL System tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production?utm_source=consul.io&utm_medium=docs) or continue reading about
[ACL rules](/docs/security/acl/acl-rules).

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

@ -0,0 +1,250 @@
---
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 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).
Refer to the [Secure Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production?in=consul/security) tutorial for help getting started with creating tokens. The tutorial includes an interactive sandbox so that you can perform the procedures without configuring your local environment.
## 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 [Token Attributes](#token-attributes) for details.
### 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](/docs/agent/options) 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"
}
```

116
website/content/docs/security/acl/index.mdx
View File

@ -1,70 +1,90 @@
---
layout: docs
page_title: ACL Guides
page_title: Access Control List (ACL) Overview
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.
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 Documentation and Guides
# Access Control List (ACL) Overview
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.
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.
The following documentation and guides will help you understand and implement
ACLs.
Refer to the following tutorials for step-by-step instructions on how to get started using ACLs:
## ACL Documentation
- [Bootstrap and Explore ACLs]
- [Secure Consul with ACLs]
- [Troubleshoot the ACL System](https://learn.hashicorp.com/tutorials/consul/access-control-troubleshoot)
### ACL System
[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
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/security/acl/acl-system) details the functionality
of Consul ACLs.
Refer to the [ACL API reference](/api-docs/acl) and [ACL CLI reference](/commands/acl) for additional usage information.
### ACL Rules
## Workflow Overview
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/security/acl/acl-rules) to learn about rule specifications.
Implementations may vary depending on the needs of the organization, but the following procedure describes the basic workflow for for creating and implementing ACLs:
### ACL Auth Methods
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:
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/security/acl/auth-methods) to learn more about how they
work and why you may want to use them.
![ACL system component relationships](/img/acl-token-policy-rule-relationship.png)
### ACL Legacy System
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.
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/security/acl/acl-legacy).
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.
### ACL Migration
## Tokens
[The migration documentation](/docs/security/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.
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.
## Learn ACL Guide
Refer to the following topics for details about tokens:
~> Note: the following guide is located on HashiCorp Learn. By selecting it,
you will be directed to a new site.
- [Tokens](/docs/security/acl/acl-tokens)
- [ACL token command line](/commands/acl/token)
- [ACL tokens API](/api-docs/acl/tokens)
### Securing Consul with ACLs
## Policies
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).
An ACL policy is a set of rules that 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.
Refer to the following topics for details about policies:
- [Policies](/docs/security/acl/policies)
- [ACL policy command line](/commands/acl/policy)
- [ACL policy API](/api-docs/acl/policies)
## 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.
Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional information.
## Service Identities
Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the service(s) specifed. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh.
Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service.
Refer to the following topics for additional information about service identities:
- [Service Identities](/docs/security/acl/acl-roles#service-identities)
- [API documentation for roles](/api/acl/roles#sample-payload)
## Node Identities
Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the node(s) specifed. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent.
Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each service.
Refer to the following topics for additional information about node identities:
- [Node Identities](/docs/security/acl/acl-roles#node-identities)
- [API documentation for roles](/api/acl/roles#sample-payload)

16
website/data/docs-nav-data.json
View File

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

1
website/lib/consent-manager-services/index.ts
View File

@ -12,4 +12,3 @@ const localConsentManagerServices: ConsentManagerService[] = [
]
export default localConsentManagerServices