Introduction

This article is intended for Consul Access Control List (ACL) administrators to consider the implications of setting a default token and how it relates to the anonymous token. 

What are these tokens?

• default - The default token is what the agent will use for both internal agent operations and operations initiated by the HTTP (Hypertext Transfer Protocol) and DNS (Domain Name System) interfaces when no specific token is provided. If the default token is not configured on the Consul Client agent, the client-initiated operation will use the anonymous token.

  • It can be set to any token by the administrator.

• anonymous - The anonymous token is only used when client-initiated operations to HTTP and DNS interfaces when no specific token is specified.
  • This is a built-in token upon enabling ACLs by Consul and cannot be deleted.
  • This token gets applied when there are no matching tokens and/or policies.
  • By default, the token has an implicit deny-all as no policies are associated with it.
    • However, an administrator can customize the behavior by attaching policies to it.

The below table describes the uses of each token in descending order by precedence.

• The commonality between the default and anonymous tokens is that they handle client operations.

Configuration Example

Take, for example, the following Consul client configuration

primary_datacenter = "dc1"  
acl {
  enabled = true
  default_policy = "deny"
  down_policy = "extend-cache"
  tokens {
    agent = "cf5940bf-72bd-b794-966a-83bc9efd5fc2"
    }
  }

• At a glance, we can infer that ACLs are enabled = true (with default_policy = "deny") and a agent token that is set.
  • As referenced in the table above, the agent token will handle internal agent operations such as registering into the catalog and discovering services and nodes in the catalog
    • You will also notice that the agent token does not handle client operations which is the common similarity between the default and anonymous tokens.
• Since no default token is set in the configuration, we can infer that any client operations would use the anonymous token.
• You could expect to see similar messages to the error below in the Consul logs with the above example for client operation requests without a token specified. 
  
  

  Error example

  Failed to retrieve the policy list: Unexpected response code: 403 (Permission denied: anonymous token lacks permission 'acl:read'. The anonymous token is used implicitly when a request does not specify a token.)

Use cases

When would you use the default token versus the anonymous token?

Since these tokens only get used when some operations/requests do not specify a token. It is important to consider the environment and if there are any use cases where an application, such as an Elastic Load Balancer (ELB), cannot pass an HTTP token when making requests to Consul.

• Default token - Policies associated with DNS
• Anonymous token - Policies associated with Specific KV values

Although policies can be associated with both tokens. The main consideration is having them associated with one Consul client agent (default token) or across the entire cluster (anonymous token).

Testing the Default Token

• The Consul CLI is typically used to test the default token behavior on an agent.
  

  consul acl set-agent-token default <your new token id>

• If the messages in the Error example above go away then whatever was making the requests was doing so without a token being set.
• Afterward, you may want to unset that default token with:
  

  consul acl set-agent-token default ""

How to set the Default Token

• If you need to configure the default token for the Consul agent and are only responding to client operations on the loopback interface (this is the default and is overridden with -client <addr> CLI parameter), then you can configure the default token within the configuration like so.
  
  

  acl {
   tokens {
     default = <token secret id linked to your policies>
   }
  }

  Or

  acl { 
    enable_token_persistence = true 
  }

• Followed by the consul acl set-agent-token default <token secret>.

Setting the Client Network Interface

• It is important to consider the network interface that Consul will be listening on to respond to client operations.
• By default, without explicitly setting the interface, this is "127.0.0.1"
  • Which allows only loopback connections. 
• It is most secure to limit client requests to the local host, but if it needs to be changed, there are two options below.

1. This is configurable via the command-line flag when starting consul via the CLI
   • -client - The address to which Consul will bind client interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1", allowing only loopback connections.
     • Example - Bind consul client interfaces to private IP addresses and loopback

       • $ consul agent -dev -client '{{ GetPrivateInterfaces | join "address" " " }} {{ GetAllInterfaces | include "flags" "loopback" | join "address" " " }}'
         

2. Additionally, there is an agent config equivalent
   • client_addr Equivalent to the -client command-line flag.
     • Example - consul.hcl

       • client_addr = "<IP of private interface>"

     • Omitting client_addr or commenting out the line will default to a loopback connection

Security Considerations

• Consul Web UI and API is accessible remotely if not configured properly

Conclusion

• We hope that this helps explain the subtle differences and nuances between the two tokens. It is best practice to require an ACL token for any interaction with Consul. However, there will be some cases where that may not be possible. Therefore, this article should better equip an administrator to plan for a client-initiated operation that does not include a token in a request to Consul.
• The best approach would be to use the default_policy = "deny" as it will control the behavior when there is no matching token and/or policy. This setting would be paired with using the anonymous token.
• If using a default token on a Consul Client Agent, it should be only used in conjunction with client_addr set to the default local host. 

Additional Information

• ACL Parameters | token

• Consul ACL Set Agent Token | Usage
• Agents Configuration File Reference | General parameters