Introduction

This article explains the roles of the default and anonymous tokens in Consul ACLs and how they affect client operations.

What are these tokens?

• default - Used by the agent for internal operations and client operations when no specific token is provided.

• anonymous - Used for client-initiated operations to HTTP and DNS interfaces when no specific token is set. It has no associated policies by default, but administrators can customize it.

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

• The default and anonymous tokens both 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"
    }
  }

• In this case, the agent token handles internal operations, but client operations will use the anonymous token since no default token is set. If no token is specified in requests, you might see a 403 error.
  
  

  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

• Default token - Useful for associating policies with DNS
• Anonymous token - Useful for policies tied to specific KV values.

The default token applies to a specific Consul agent, while the anonymous token applies cluster-wide.

Setting Default Token

Via Config file

• You can set the default token in the configuration file
  

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

  Or

  acl { 
    enable_token_persistence = true 
  }

 Via CLI

• To set the default token.
  

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

• To unset it:
  

  consul acl set-agent-token default ""

Security Considerations

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

Conclusion

• Use the default_policy = "deny" setting with the anonymous token to handle requests without a matching token or policy. Use the default token for specific client agents, particularly with the loopback interface.

Additional Information

• ACL Parameters | token

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