Roles are a named collection of ACL policies, service identities, and node identities. Learn how roles allow you to reuse and update access control policies without needing to distribute new tokens to users.
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.
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`.
```shell-session
$ consul acl role create -name "crawler" -description "web crawler role" -policy-name "crawler-kv" -policy-name "crawler-key"
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.
- `TemplatedPolicies`: Specifies a list of templated policies that are applicable for the role. See [Templated Policies](#templated-policies) for details.
- `Namespace`: <EnterpriseAlert inline /> The namespace that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See [Namespaces](/consul/docs/enterprise/namespaces) for additional information. Requires Consul Enterprise 1.7.0+
- `Partition`: <EnterpriseAlert inline/> 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](/consul/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.10.0+.
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.
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.
```json
{
"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](/consul/api-docs/acl/roles#sample-payload) 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`:
```hcl
# 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](/consul/docs/security/acl/acl-rules) 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.
<CodeBlockConfig filename="example-role.json">
```json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"TemplatedPolicies": [
{
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "web"
}
}
]
}
```
</CodeBlockConfig>
During the authorization process, Consul generates the following policies for the `web` services and links it to the token:
<CodeBlockConfig filename="web-policy.hcl">
```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.
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](/consul/docs/connect) topic for additional information about Consul service mesh.
-> **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:
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`.
<CodeBlockConfig filename="example-role.json">
```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"
}
]
}
```
</CodeBlockConfig>
During the authorization process, the following policies for the `web` and `db` services will be generated and linked to the token:
<CodeBlockConfig filename="web-policy.hcl">
```hcl
# Allow the service and its sidecar proxy to register into the catalog.
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`](/consul/docs/agent/config/config-files#acl_tokens_agent) field when configuring the agent.
-> **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:
```hcl
# 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.
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`.
