ACL Roles

A role is a collection of policies that your ACL administrator can link to a token. They enable you to reuse policies by decoupling the policies from the token distributed to team members. Instead, the token is linked to the role, which is able to hold several policies that can be updated asynchronously without distributing new tokens to users. As a result, roles can provide a more convenient authentication infrastructure than creating unique policies and tokens for each requester.

Workflow overview

Roles are configurations linking several policies to a token. The following procedure describes the workflow for implementing roles.

Assemble rules into policies (see Policies) and register them in Consul.
Define a role and include the policy IDs or names.
Register the role in Consul and link it to a token.
Distribute the tokens to users for implementation.

Creating roles

Creating roles is commonly the responsibility of the Consul ACLs administrator. Roles have several attributes, including service identities and node identities. Refer to the following documentation for details:

Use the Consul command line or API endpoint to create roles.

Command line

Issue the consul acl role create command to create roles. In the following example, a role named crawler is created that contains a policy named crawler-kv and a policy named crawler-key.

$ consul acl role create -name "crawler" -description "web crawler role" -policy-name "crawler-kv" -policy-name "crawler-key"

Refer to the command line documentation for details.

API

Make a PUT call to the acl/role endpoint and specify the role configuration in the payload to create roles. You can save the role definition in a JSON file or use escaped JSON in the call. In the following example call, the payload is defined externally.

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

Refer to the API documentation for details.

Role attributes

Roles may contain the following attributes:

ID: The ID is an auto-generated public identifier. You can specify the role ID when linking it to tokens.
Name: A unique meaningful name for the role. You can specify the role Name when linking it to tokens.
Description: (Optional) A human-readable description of the role.
Policies: Specifies a the list of policies that are applicable for the role. The object can reference the policy ID or Name attribute.
TemplatedPolicies: Specifies a list of templated policies that are applicable for the role. See Templated Policies for details.
ServiceIdentities: Specifies a list of services that are applicable for the role. See Service Identities for details.
NodeIdentities: Specifies a list of nodes that are applicable for the role. See Node Identities for details.
Namespace: Enterprise The namespace that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See Namespaces for additional information. Requires Consul Enterprise 1.7.0+
Partition: Enterprise The admin partition that the policy resides in. Roles can only be linked to policies that are defined in the same admin partition. See Admin Partitions for additional information. Requires Consul Enterprise 1.10.0+.

Templated policies

You can specify a templated policy when configuring roles or linking tokens to policies. Templated policies enable you to quickly construct policies for common Consul use cases, rather than creating identical policies for each use cases.

Consul uses templated policies during the authorization process to automatically generate a policy for the use case specified. Consul links the generated policy to the role or token so that it will have permission for the specific use case.

Templated policy specification

The following templated policy example configuration uses the builtin/service templated policy to give a service named api and its sidecar proxy the required permissions to register into the catalog.

{
  "TemplatedPolicies": [
    {
      "TemplateName": "builtin/service",
      "TemplateVariables": {
        "Name": "api"
      }
    }
  ]
}

TemplatedPolicies: Declares a templated policy block.
TemplatedPolicies.TemplateName: String value that specifies the name of the templated policy you want to use.
TemplatedPolicies.TemplateVariables: Map that specifies the required variables for the templated policies. This field is optional as not all templated policies require variables.

Refer to the API documentation for roles for additional information and examples.

In Consul Enterprise, templated policies inherit the namespace or admin partition scope of the corresponding ACL token or role.

The builtin/service sample templated policy generates the following policy for a service named api:

# Allow the service and its sidecar proxy to register into the catalog.
service "api" {
    policy = "write"
}
service "api-sidecar-proxy" {
    policy = "write"
}

# Allow for any potential upstreams to be resolved.
service_prefix "" {
    policy = "read"
}
node_prefix "" {
    policy = "read"
}

Refer to the rules reference for information about the rules in the policy.

Example

The following role configuration contains a templated policy that gives the role required permission for a service named web to register itself and its sidecar into the catalog.

example-role.json

{
  "Name": "example-role",
  "Description": "Showcases all input parameters",
  "TemplatedPolicies": [
    {
      "TemplateName": "builtin/service",
      "TemplateVariables": {
        "Name": "web"
      }
    }
  ]
}

During the authorization process, Consul generates the following policies for the web services and links it to the token:

web-policy.hcl

# Allow the service and its sidecar proxy to register into the catalog.
service "web" {
    policy = "write"
}
service "web-sidecar-proxy" {
    policy = "write"
}

# Allow for any potential upstreams to be resolved.
service_prefix "" {
    policy = "read"
}
node_prefix "" {
    policy = "read"
}

Service Identities

You can specify a service identity when configuring roles or linking tokens to policies. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service.

Service identities are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can be discovered and discover other healthy service instances in a service mesh. Refer to the service mesh topic for additional information about Consul service mesh.

Service identity specification

Use the following syntax to define a service identity:

{
  "ServiceIdentities": [
    {
      "ServiceName": "<service name>",
      "Datacenters": ["<datacenter name>"]
    }
  ]
}

ServiceIdentities: Declares a service identity block.
ServiceIdentities.ServiceName: String value that specifies the name of the service you want to associate with the policy.
ServiceIdentities.Datacenters: Array that specifies the names of datacenters in which the service identity applies. This field is optional.

Refer to the API documentation for roles for additional information and examples.

Scope for Namespace and Admin Partition - In Consul Enterprise, service identities inherit the namespace or admin partition scope of the corresponding ACL token or role.

The following policy is generated for each service when a service identity is declared:

# Allow the service and its sidecar proxy to register into the catalog.
service "<service name>" {
    policy = "write"
}
service "<service name>-sidecar-proxy" {
    policy = "write"
}

# Allow for any potential upstreams to be resolved.
service_prefix "" {
    policy = "read"
}
node_prefix "" {
    policy = "read"
}

Refer to the rules reference for information about the rules in the policy.

Example

The following role configuration contains service identities for the web and db services. Note that the db service is also scoped to the dc1 datacenter so that the policy will only be applied to instances of db in dc1.

example-role.json

{
  "Name": "example-role",
  "Description": "Showcases all input parameters",
  "Policies": [
    {
      "ID": "783beef3-783f-f41f-7422-7087dc272765"
    },
    {
      "Name": "node-read"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "web"
    },
    {
      "ServiceName": "db",
      "Datacenters": ["dc1"]
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ]
}

During the authorization process, the following policies for the web and db services will be generated and linked to the token:

web-policy.hcl

# Allow the service and its sidecar proxy to register into the catalog.
service "web" {
    policy = "write"
}
service "web-sidecar-proxy" {
    policy = "write"
}

# Allow for any potential upstreams to be resolved.
service_prefix "" {
    policy = "read"
}
node_prefix "" {
    policy = "read"
}

Per the ServiceIdentities.Datacenters configuration, the db policy is scoped to resources in the dc1 datacenter.

db-policy.hcl

# Allow the service and its sidecar proxy to register into the catalog.
service "db" {
    policy = "write"
}
service "db-sidecar-proxy" {
    policy = "write"
}

# Allow for any potential upstreams to be resolved.
service_prefix "" {
    policy = "read"
}
node_prefix "" {
    policy = "read"
}

Node Identities

You can specify a node identity when configuring roles or linking tokens to policies. Node commonly refers to a Consul agent, but a node can also be a physical server, cloud instance, virtual machine, or container.

Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the acl_tokens_agent field when configuring the agent.

Node identity specification

Use the following syntax to define a node identity:

{
  "NodeIdentities": [
    {
      "NodeName": "<node name>",
      "Datacenter": "<datacenter name>"
    }
  ]
}

NodeIdentities: Declares a node identity block.
NodeIdentities.NodeName: String value that specifies the name of the node you want to associate with the policy.
NodeIdentities.Datacenter: String value that specifies the name of the datacenter in which the node identity applies.

Refer to the API documentation for roles for additional information and examples.

Consul Enterprise Namespacing - Node Identities can only be applied to tokens and roles in the default namespace. The generated policy rules allow for service:read permissions on all services in all namespaces.

The following policy is generated for each node when a node identity is declared:

# Allow the agent to register its own node in the Catalog and update its network coordinates
node "<node name>" {
  policy = "write"
}

# Allows the agent to detect and diff services registered to itself. This is used during
# anti-entropy to reconcile difference between the agents knowledge of registered
# services and checks in comparison with what is known in the Catalog.
service_prefix "" {
  policy = "read"
}

Refer to the rules reference for information about the rules in the policy.

Example

The following role configuration contains a node identity for node-1. Note that the node identity is also scoped to the dc2 datacenter. As a result, the policy will only be applied to nodes named node-1 in dc2.

example-role.json

{
  "Name": "example-role",
  "Description": "Showcases all input parameters",
  "Policies": [
    {
      "ID": "783beef3-783f-f41f-7422-7087dc272765"
    },
    {
      "Name": "node-read"
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ]
}

During the authorization process, the following policy will be generated and linked to the token:

node-1-policy.hcl

# Allow the agent to register its own node in the Catalog and update its network coordinates
node "node-1" {
  policy = "write"
}

# Allows the agent to detect and diff services registered to itself. This is used during
# anti-entropy to reconcile differences between the agent's knowledge of registered
# services and checks in comparison with what is known in the Catalog.
service_prefix "" {
  policy = "read"
}