Understand Access Control Privileges
This tutorial is for Operators with the responsibility of creating and managing ACL tokens. It includes several recommendations on how to discover the minimum privileges required to complete operations. Throughout the tutorial we'll provide examples and use cases that you can adapt to your environment, however, it does not include environment specific recommendations. After completing this tutorial, you will have a better understanding of how to effectively manage ACL policies and tokens.
We expect operators to automate the policy and token generation process in production environments. Additionally, if you are using a container orchestrator, the process will vary even though the concepts in this tutorial will still be applicable. If you are using the official Consul-Kubernetes Helm chart to deploy Consul, use the authentication method documentation instead of generating policies manually or automating the methods here.
Prerequisites
We provide high-level recommendations in this tutorial, however, we will not describe the command by command token generation process. To learn how to create tokens, read the ACL bootstrapping tutorial.
This tutorial assumes the default_policy
of deny
is set on all agents, in
accordance to the security model documentation.
Security and usability
The examples in this tutorial illustrate how to create multiple policies that can be used to accomplish the same task. For example, using an exact match resource rule, is the most secure. It grants the least privileges necessary to accomplish the task. Generally, creating policies and tokens with the least privileges will result in more policy definitions. Alternatively, for a simplified process, the prefix resources rules can apply to zero-to-many objects. The trade-off of a less complicated token creation process is wider potential blast radius on token or workload compromise.
Discover required privileges
After bootstrapping the ACL system and configuring Consul agents with tokens, you will need to create tokens to complete any additional task within the datacenter including registering services.
Before discovering the minimum acceptable privileges, it's important to understand the basic components of a token. A rule is a specific privilege and the basic unit of a token. Rules are combined to create policies. There are two main parts of a rule: the resource and policy disposition. The resource is the object that the rule applies to and the policy dispositions dictates privileges. The example below applies to any service object named "web". The policy disposition grants read privileges.
To discover the minimum privileges required for a specific operation, we have three recommendations.
First, focus on the data in your environment that needs to be secured. Ensure your sensitive data has policies that are specific and limited. Since policies can be combined to create tokens, you will usually write more policies for sensitive data. Sensitive data could be a specific application or a set of values in the key-value store.
Second, reference the Consul docs, both the rules page and # API pages, often to understand the required privileges for any given operation.
The rules documentation explains all of the rule resources. The following four resource types are critical for any operating datacenter with ACLs enabled.
Rule | Summary |
---|---|
acl | ACL rules grant privileges for ACL operations including to create,update, or view tokens and policies. |
node and node_prefix | Node rules grant privileges for node-level registration, including adding agents to the datacenter and catalog. |
service and service_prefix | Service rules grant privileges for service-level registration, including adding services to the catalog. |
operator | The operator grants privileges for datacenter operations, including interacting with Raft. |
On the API pages, each endpoint will have a table that includes required ACLs. The node health endpoint, shown below, requires node and service read to view all checks for the specified node.
Finally, before using a token in production, you should test that it has the correct privileges. If the token being used is missing a privilege, then Consul will issue a permission denied error.
Depending on the the operation and type of data, you will see either a 404 or 403.
Operations example: listing Consul agents
To view all Consul agents in the datacenter, you can use the consul members
CLI command.
For this command to succeed, you will need at least read privileges for every agent in the datacenter. Depending on your threat model you could have either of the following policies.
If you have a dynamic or very large environment, you may want to consider creating one policy that can apply to all agents, to reduce the Operation Team’s workload.
Note, the empty ""
allows this rule to apply to any agent in the datacenter.
In the example above, this rule will apply to: server.one, client.one,
client.two, and client.three.
If you have a static environment or for maximum security, you many want to create an individual rule for each agent. This could require you to to create a new token every time a new agent is added to the datacenter.
Secure access control: operator-only access
The most secure access control implementation restricts tokens with
acl = "write"
policies to only one or a few trusted operators. Tokens with the
policy acl = "write"
grant the holder unlimited privileges, because they can
generate tokens with any other resource and policy. The operators are
responsible for creating all other policies and tokens that grant limited access
to the datacenter. We refer to this implementation as the operator-only
implementation. This implementation type is the most secure, and most complex to
manage.
For this implementation type operators are responsible for managing policies and tokens for:
- service and Connect proxy registration
- intention management
- agent management
- API, CLI, and UI access
Warning
If you need to share token generation responsibilities with other teams,
anyone with the ability to create tokens (acl = "write"
) effectively has
unrestricted access to the datacenter. That individual will have the ability to
deregister agents and services, and delete data from Consul KV.
Operator-only implementation example
In the following example, Operators retain responsibility for service token management, but delegate access control between Connect-enabled services to the Security Team.
Tip
The service registration example in this tutorial describes the token generation process for per-service tokens.
Initially, the Operator creates a single token with intention management privileges for the Security Team. Developers will be given separate tokens to enable them to register their applications without having access to manage Intentions.
The Security Team's token must include the intention
policy disposition in the
service rule for any services they are allowed to manage the intentions.
Creating an intention enables the security team to allow the wordpress
service
to open new connections to the upstream mysql
service.
First, create a file for a config entry definition named intention-config.hcl
.
From the same directory where you saved this file, run the following command on your terminal to initialize these intention rules.
Note
To learn more about intentions, feel free to check out the Service Intentions Docs.
The Security Team responsible for managing intentions would need to create allow
intentions when the default_policy
is set to deny
, since deny all will be
inherited from the ACL configuration.
In this implementation type, Developers are responsible for requesting a token for their service. For a Connect enabled service, the Operator would need to create a policy that provides write privileges for the service and proxy, and read privileges for all services and nodes to enable discovery of other upstream dependencies.
With the token the Developer can then register the service with Consul using the
register
command.
The Operator example above illustrates creating policies on the security spectrum. The first example, using an exact match resource rule, is the most secure. It grants the least privileges necessary to accomplish the task. Generally, creating policies and tokens with the least privileges will result in more policy definitions. However, this will help you create the most secure environment. Alternatively, the prefix rule can apply to zero-to-many objects. The trade-off of a less complicated token creation process is security. Note, this applies to all rules not just for agents.
Required privileges for datacenter operations
Below is a table with the minimum required privileges for a set of common operations. You can also use exact match rules when creating specific policies that are less flexible.
CLI Operation | Required Privilege |
---|---|
consul reload | agent_prefix "": policy = "write" |
consul monitor | agent_prefix "": policy = "read" |
consul leave | agent_prefix "": policy = "write" |
consul members | node_prefix "": policy = "read" |
consul acl | acl = "write" |
consul catalog services | service_prefix "": policy = "read" |
consul catalog nodes | node_prefix "": policy = "read" |
consul services register | service_prefix "": policy = "write" |
consul services register (Connect proxy) | service_prefix "": policy = "write", node_prefix "": policy = "read" |
consul connect intention | service_prefix "": intention = "write" |
consul kv get | key_prefix "": policy = "read" |
consul kv put | key_prefix "": policy = "write" |
Next steps
After setting up access control processes, you will need to implement a token rotation policy. If you are using third-party tool to generate tokens, such as Vault, Consul ACL tokens will adhere to the TTLs set in that third party tool. If you are manually rotating tokens or need to revoke access, you can delete a token at any time with the API. Note, token rotation requires re-registration with the new token.