Create an agent token

This topic describes how to create a token that you can use to register an agent into the catalog.

Introduction

Consul agents must present a token linked to policies that grant the appropriate set of permissions in order to register into the catalog and to discover services and nodes in the catalog.

Specify the agent token to the Consul agent so that it can present the token when it registers into the catalog.

Node identities versus custom policies

You can create tokens linked to custom policies or to node identities. Node identities are constructs in Consul that enable you to quickly grant permissions for a group of agents, rather than create similar policies for each agent.

We recommend using a node identity to grant permissions to the agent rather than creating a custom policy. This is because node identities automatically grant the node node:write and service:read permission.

Your organization may have requirements or processes for deploying services in a way that is inconsistent with service and node identities. In these cases, you can create custom policies and link them to tokens.

Requirements

Core ACL functionality is available in all versions of Consul.

The agent token must be linked to policies that grant the following permissions:

node:write: Enables the agent to update the catalog.
service:read: Enables the agent to discover other services in the catalog

Authentication

You must provide an ACL token linked to a policy with acl:write permissions to create and modify ACL tokens and policies using the CLI or API.

You can provide the token manually using the -token option on the command line, but we recommend setting the CONSUL_HTTP_TOKEN environment variable to simplify your workflow:

$ export CONSUL_HTTP_TOKEN=<acl-token-secret-id>

The Consul CLI automatically reads the CONSUL_HTTP_TOKEN environment variable so that you do not have to pass the token to every Consul CLI command.

To authenticate calls to the Consul HTTP API, you must provide the token in the X-Consul-Token header for each call:

$ curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" ...

To learn about alternative ways to authenticate, refer to the following documentation:

Node identity in Consul CE

Refer to Node identities for information about node identities that you can link to tokens.

You can manually create tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.

Run the consul acl token create command and specify the policy or node identity to link to create a token. Refer to Consul ACL Token Create for details about the consul acl token create command.

The following command creates an ACL token linked to a node identity for a node named node1 in the datacenter dc1.

$ consul acl token create \
  -description "Agent token for node1" \
  -node-identity "node1:dc1"

Send a PUT request to the /acl/token endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to ACL Token HTTP API for additional information about using the API endpoint.

The following example creates a token linked to a node identity named node1:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "NodeIdentities": [
    {
      "NodeName": "node1",
      "Datacenter": "dc1"
    }
  ]
}'

Node identity in Consul Enterprise

Refer to Node identities for information about node identities that you can link to tokens.

You can manually create tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.

Run the consul acl token create command and specify the policy or node identity to link to create a token. Refer to Consul ACL Token Create for details about the consul acl token create command.

You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in partition ptn1 in datacenter dc1:

$ consul acl token create -partition "ptn1" \
  -description "Agent token for node1" \
  -node-identity "node1:dc1"

You can specify an admin partition when creating a token in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in the partition ptn1 in datacenter dc1:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "NodeIdentities": [
    {
      "NodeName": "node1",
      "Datacenter": "dc1"
    }
  ],
  "Partition": "ptn1"
}'

Custom policy in Consul CE

When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog.

Define a policy

You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to ACL Rules for details about all of the rules you can use in your policies.

The following example policy is defined in a file. The policy grants write permission for node node1 so that the Consul agent can register into the catalog. It grants read permissions to discover services in the catalog.

node "node1" {
  policy = "write"
}
service_prefix "" {
  policy = "read"
}

Register the policy with Consul

After defining the policy, you can register the policy with Consul using the command line or API endpoint.

Run the consul acl policy create command and specify the policy rules to create a policy. The following example registers a policy defined in node1-register.hcl:

$ consul acl policy create \
    -name "node1-register" -rules @node1-register.hcl \
    -description "Custom policy for node1" \

Refer to Consul ACL Policy Create for details about the consul acl policy create command.

Send a PUT request to the /acl/policy endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in node1-register.hcl. You must embed policy rules in the Rules field of the request body.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "node1-register",
  "Description": "Allow node1 to register into the catalog",
  "Rules": "node \"node1\" {\n  policy = \"write\"\n}\nservice_prefix \"\" {\n  policy = \"read\"\n}\n"
}'

Refer to ACL Policy HTTP API for additional information about using the API endpoint.

Link the policy to a token

After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.

Run the consul acl token create command and specify the policy name or ID to create a token linked to the policy. Refer to Consul ACL Token Create for details about the consul acl token create command.

The following command creates the ACL token linked to the policy node1-register.

$ consul acl token create \
    -description "Agent token for node1" \
    -policy-name "node1-register"

Send a PUT request to the /acl/token endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to ACL Token HTTP API for additional information about using the API endpoint.

The following example creates an ACL token that the agent can use to register as node node1 in the catalog:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "node1-register"
    }
  ]
}'

Custom policy in Consul Enterprise

When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog.

Define a policy

You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to ACL Rules for details about all of the rules you can use in your policies.

The following example policy is defined in a file. The policy grants the write permission for node node1 in partition ptn1 so that the Consul agent can register into the catalog. It grants read permissions to discover services in any namespace in the ptn1 partition.

partition "ptn1" {
  node "node1" {
    policy = "write"
  }
  namespace_prefix "" {
    service_prefix "" {
      policy = "read"
    }
  }
}

{
  "partition": {
    "ptn1": [{
      "namespace_prefix": {
        "": [{
          "service_prefix": {
            "": [{
              "policy": "read"
            }]
          }
        }]
      },
      "node": {
        "node1": [{
          "policy": "write"
        }]
      }
    }]
  }
}

Register the policy with Consul

After defining the policy, you can register the policy with Consul using the command line or API endpoint.

Run the consul acl policy create command and specify the policy rules to create a policy. The following example registers a policy defined in node1-register.hcl:

$ consul acl policy create -partition "ptn1" \
  -name "node1-register" -rules @node1-register.hcl \
  -description "Custom policy for node1"

Refer to Consul ACL Policy Create for details about the consul acl policy create command.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "node1-register",
  "Description": "Allow node1 to register into the catalog",
  "Partition": "ptn1",
  "Rules": "partition \"ptn1\" {\n  node \"node1\" {\n    policy = \"write\"\n  }\n  namespace_prefix \"\" {\n    service_prefix \"\" {\n      policy = \"read\"\n    }\n  }\n}\n"
}'

Refer to ACL Policy HTTP API for additional information about using the API endpoint.

Link the policy to a token

After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.

$ consul acl token create -partition "ptn1" \
    -description "Agent token for node1" \
    -policy-name "node1-register"

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "node1-register"
    }
  ],
  "Partition": "ptn1"
}'

Apply the token

Configure the Consul agent to present the token by either specifying the token in the agent configuration file or by using the consul set-agent-token command.

Apply the token in a file

Specify the token in the acl.token.agent field of the agent configuration file so that the agent can present it and register into the catalog on startup.

acl = {
  enabled = true
  tokens = {
    agent = "<token>"
    ...
  }
  ...
}

Apply the token with a command

Set the agent token using the consul set-agent-token command. The following command configures a running Consul agent token with the specified token.

consul acl set-agent-token agent <acl-token-secret-id>