Skip to content

Latest commit

 

History

History
238 lines (167 loc) · 16.5 KB

acl-tokens.mdx

File metadata and controls

238 lines (167 loc) · 16.5 KB
Raw
layout page_title description
docs
ACL Tokens
Tokens are used to authenticate users, services, and agents and authorize their access to resources in Consul. Learn about token attributes, special-purpose and built-in tokens, and how to pass a token’s SecretID in the CLI and API.

ACL 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 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 and ACL CLI documentation for instructions on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an auth method.

Refer to the Secure Consul with Access Control Lists (ACLs) 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 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:

service = {
  id = "redis"
  name = "redis"
  ...
  namespace = "foo"
  token = "233b604b-b92e-48c8-a253-5f11514e4b50"
}
{
  "service": {
    "id": "redis",
    "name": "redis",
    ...
    "token": "233b604b-b92e-48c8-a253-5f11514e4b50",
    "namespace": "foo"
  }
}

Refer to the service definitions documentation for additional information.

Agent Requests

Consul agents can be configured to hold several ACL tokens (see tokens) 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 REQUIRED REQUIRED Controls whether ACLs are enabled
acl.default_policy OPTIONAL N/A Determines allowlist or denylist mode
acl.down_policy OPTIONAL OPTIONAL Determines what to do when the remote token or policy resolution fails
acl.role_ttl OPTIONAL OPTIONAL Determines time-to-live for cached ACL Roles
acl.policy_ttl OPTIONAL OPTIONAL Determines time-to-live for cached ACL Policies
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:

tokens = {
  default = "233b604b-b92e-48c8-a253-5f11514e4b50"
}
{
  "tokens": {
    "default": "233b604b-b92e-48c8-a253-5f11514e4b50"
  }
}

Refer to the agent configurations documentation for additional information.

Command Line Requests

To make a request on the command line, specify the ACL token with the -token command line flag. In the following example, a token is included to enable the user to create an intention on the command line:

$ 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 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 for details.

The following example shows the header for a GET request to the agent/members endpoint.

$ 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 or command line documentation for all attributes that can be assigned or generated for a token:

Attribute Description Type Default
AccessorID Used for 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 Specifies the name of the admin partition in which the token is valid. See Admin Partitions for additional information. String default
Namespace Specifies the name of the Consul namespace in which the token is valid. See 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.
Set to false to replicate globally across all reachable datacenters.
Setting to true configures the token to functional in the local datacenter only.		 Boolean false
ServiceIdentities Specifies a list of service identities to apply to the token. See Service Identities in the "Roles" topic for additional information. Array none
NodeIdentities Specifies a list of node identities to apply to the token. See 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
Roles List of roles linked to the token, including the role ID and name. String none

Special-purpose Tokens

Your ACL administrator 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 OPTIONAL OPTIONAL Enables access to the Agent API when remote bearer token resolution fails.
Used for setting up the cluster and performing initial join operations.
See ACL Agent Recovery Token for details.
acl.tokens.agent OPTIONAL OPTIONAL Used for internal agent operations. See ACL Agent Token for details.
acl.tokens.initial_management OPTIONAL N/A Used to bootstrap the ACL system. See Initial Management Token.
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.

Snapshot Tokens

Snapshots are artifacts created with the snapshot API for backup and recovery purposes. Snapshots contain ACL tokens and interacting with them requires a token with acl:write privileges.

ACL Agent Token

The 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, 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, including updating its node metadata, tagged addresses, and network coordinates
  2. Performing 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

Here's an example policy sufficient to accomplish the above for a node called mynode:

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, the default, then the key_prefix policy can be omitted.

Built-in Tokens

Consul includes a built-in anonymous token and initial 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 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 for guidance on bootstrapping.

ACL Agent Recovery Token

The 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

agent "<node name of agent>" {
  policy = "write"
}
node_prefix "" {
  policy = "read"
}