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 workflow overview for information about tokens' role in the ACL system.

Create tokens

The ACLs administrator can use the HTTP API or CLI to create and link tokens to entities that enable permissions to resources.

$ consul acl token create -description "Read nodes and services" -policy-name node-services-read

$ curl --request PUT --data @payload.json http://127.0.0.1:8500/v1/acl/token

Refer to the ACL API and ACL CLI documentation for more details on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an auth method.

Pass tokens

Users performing Consul operations or deploying their services into the network need to include an ACL token with the necessary policies to perform the action. ACL token is the value of the token's SecretID attribute. This token is an opaque string that identifies the requester so that the ACL system can determine whether it should grant or deny access to the requested resource.

Refer to ACL token reference for a full list of token attributes.

Perform Consul operations

When ACLs are enabled, you must pass an ACLs token with your request to interact with Consul.

$ curl --header "X-Consul-Token: <token>" "http://127.0.0.1:8500/v1/agent/members"

Configure services with ACLs

Specify the value of the SecretID attribute with the token parameter when configuring your services. The following example service configuration includes a sample ACL token to the redis service. This ACL token must have read and write rules to interact with Consul catalog.

service = {
  id = "redis"
  name = "redis"
  namespace = "foo"
  token = "<SecretID>"
}

{
  "service": {
    "id": "redis",
    "name": "redis",
    "namespace": "foo",
    "token": "<SecretID>"
  }
}

Refer to service definition reference for more information.

Configure agents with ACLs

You can configure Consul agents to hold several ACL tokens (acl.tokens) to accommodate several use cases, such as bootstrapping the ACL system or accessing Consul under specific conditions.

In the following example, the agent is configured to use a default token:

acls {
  tokens = {
    default = "00000000-0000-0000-0000-000000000000"
  }
}

{
  "acls": {
    "tokens": {
      "default": "00000000-0000-0000-0000-000000000000"
    }
  }
}

Refer to the agent configuration reference for more information.

Rotate token

We recommend rotating tokens on a regular basis to ensure the security of your deployment.

To rotate a token, you must create a new token, update any configuration that references the old token with the new token, and then delete the old token. You can rotate tokens used to register services and agents, query DNS, and access Consul data.

To keep the same privileges as the previous token, use the clone command with the existing token's AccessorID.

$ consul acl token clone -description "Clone of <token_you_are_cloning>" -id <accessor_id_you_are_cloning>
Token cloned successfully.
AccessorID:   dcfa52ed-9288-b3ff-056d-255ef69d2d88
SecretID:     0005d17e-5bb2-7e8b-7bfa-15f2eee9ad14
Description:  Clone of Super User
Local:        false
Create Time:  2018-10-22 16:26:02.909096 -0400 EDT
Policies:
   00000000-0000-0000-0000-000000000001 - global-management

Apply tokens to the agent or to the services as needed.

Finally, delete the old token from Consul. Alternatively, you can delete ACL tokens using the acl endpoint on the HTTP API.

$ consul acl token delete -id 6a1253d2-1785-24fd-91c2-f8e78c745511

Special-purpose tokens

The following table describes a subset of special purpose tokens. Refer to acl.tokens) for a full set of special purpose tokens you can configure.

You can use the /v1/agent/token endpoint to create or update all reserved tokens except the initial_management token.

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 agent token (acl.tokens.agent) is a special token that Consul uses for internal agent operations. Consul does not use this token directly for any user-initiated operations like the default ACL token (acl.tokens.default. However, if you do not define the ACL agent token, Consul will use the default ACL token for internal agent operations. Consul uses the ACL agent token for the following agent operations:

1. Updating the agent's node entry using the Catalog API. This includes 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.

The following example is the minimum policy required to perform the internal agent operations for a node called mynode. The service_prefix policy needs read access to any services that can be registered on the agent. If remote execution is disabled (default behavior), you can omit the key_prefix policy.

node "mynode" {
  policy = "write"
}
service_prefix "" {
  policy = "read"
}
key_prefix "_rexec" {
  policy = "write"
}

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. Refer to the Token reference docs for more information about each attribute.

You may update the anonymous token's description and policies, however you cannot delete the token.

Initial management token

There are two ways for you to create an initial management token.

1. Bootstrap the ACL system with consul acl bootstrap. Consul automatically generates a token for you. Refer to Bootstrap ACLs for more details.
2. Define an initial management token in the Consul agent configuration (acl.token.initial_management). This method lets ACL administrators to bootstrap the ACL system with a known value.

Consul links the management token to the built-in global management policy. This token has unrestricted privileges to resources and APIs.

ACL agent recovery token

You can use the ACL agent recovery token (acl.tokens.agent_recovery) when your Consul servers are unavailable. 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"
}