mirror of https://github.com/hashicorp/consul
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
646 lines
18 KiB
646 lines
18 KiB
--- |
|
layout: api |
|
page_title: ACL Roles - HTTP API |
|
description: The /acl/role endpoints manage Consul's ACL Roles. |
|
--- |
|
|
|
# ACL Role HTTP API |
|
|
|
-> **1.5.0+:** The role APIs are available in Consul versions 1.5.0 and newer. |
|
|
|
The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role), |
|
[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul. |
|
|
|
For more information on how to setup ACLs, refer to the following resources: |
|
|
|
- [Access control list (ACL) overview](/consul/docs/security/acl) |
|
- [ACL tutorial](/consul/tutorials/security/access-control-setup-production) |
|
|
|
## Create a Role |
|
|
|
This endpoint creates a new ACL role. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ----------- | ------------------ | |
|
| `PUT` | `/acl/role` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `NO` | `none` | `none` | `acl:write` | |
|
|
|
The corresponding CLI command is [`consul acl role create`](/consul/commands/acl/role/create). |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you create. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### JSON Request Body Schema |
|
|
|
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name |
|
can contain alphanumeric characters, dashes `-`, and underscores `_`. |
|
This name must be unique. |
|
|
|
- `Description` `(string: "")` - Free form human readable description of the role. |
|
|
|
- `Policies` `(array<PolicyLink>)` - The list of policies that should be |
|
applied to the role. A PolicyLink is an object with an "ID" and/or "Name" |
|
field to specify a policy. With the PolicyLink, roles can be linked to |
|
policies either by the policy name or by the policy ID. When policies are |
|
linked by name they will be internally resolved to the policy ID. With |
|
linking roles internally by IDs, Consul enables policy renaming without |
|
breaking tokens. |
|
|
|
- `TemplatedPolicies` `(list of maps)` - The list of [templated policies](/consul/docs/security/acl#templated-policies) |
|
that should be applied to the role. |
|
|
|
- `TemplateName` `(string: <required>)` - The templated policy name. |
|
|
|
- `TemplateVariables` `(map of strings|maps: <optional>)` - The templated policy variables. Not all templated policies |
|
require variables. |
|
|
|
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service |
|
identities](/consul/docs/security/acl#service-identities) that should be |
|
applied to the role. |
|
|
|
- `ServiceName` `(string: <required>)` - The name of the service. The name |
|
must be no longer than 256 characters, must start and end with a lowercase |
|
alphanumeric character, and can only contain lowercase alphanumeric |
|
characters as well as `-` and `_`. |
|
|
|
- `Datacenters` `(array<string>)` - Specifies the datacenters the effective |
|
policy is valid within. When no datacenters are provided the effective |
|
policy is valid in all datacenters including those which do not yet exist |
|
but may in the future. |
|
|
|
- `NodeIdentities` `(array<NodeIdentity>)` - The list of [node |
|
identities](/consul/docs/security/acl#node-identities) that should be |
|
applied to the role. |
|
|
|
- `NodeName` `(string: <required>)` - The name of the node. The name |
|
must be no longer than 256 characters, must start and end with a lowercase |
|
alphanumeric character, and can only contain lowercase alphanumeric |
|
characters as well as `-` and `_`. |
|
|
|
- `Datacenter` `(string: <required>)` - Specifies the nodes datacenter. This |
|
will result in effective policy only being valid in that datacenter. |
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you create. |
|
This field takes precedence over the `ns` query parameter, |
|
one of several [other methods to specify the namespace](#methods-to-specify-namespace). |
|
|
|
@include 'http-api-body-options-partition.mdx' |
|
|
|
### Sample Payload |
|
|
|
```json |
|
{ |
|
"Name": "example-role", |
|
"Description": "Showcases all input parameters", |
|
"Policies": [ |
|
{ |
|
"ID": "783beef3-783f-f41f-7422-7087dc272765" |
|
}, |
|
{ |
|
"Name": "node-read" |
|
} |
|
], |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateName": "builtin/service", |
|
"TemplateVariables": { |
|
"Name": "api" |
|
} |
|
}, |
|
{ |
|
"TemplateName": "builtin/dns" |
|
} |
|
], |
|
"ServiceIdentities": [ |
|
{ |
|
"ServiceName": "web" |
|
}, |
|
{ |
|
"ServiceName": "db", |
|
"Datacenters": ["dc1"] |
|
} |
|
], |
|
"NodeIdentities": [ |
|
{ |
|
"NodeName": "node-1", |
|
"Datacenter": "dc2" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request PUT \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/acl/role |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4", |
|
"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" |
|
} |
|
], |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateID": "00000000-0000-0000-0000-000000000003", |
|
"TemplateName": "builtin/service", |
|
"TemplateVariables": { |
|
"Name": "api" |
|
} |
|
}, |
|
{ |
|
"TemplateID": "00000000-0000-0000-0000-000000000005", |
|
"TemplateName": "builtin/dns" |
|
} |
|
], |
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=", |
|
"CreateIndex": 57, |
|
"ModifyIndex": 57 |
|
} |
|
``` |
|
|
|
## Read a Role |
|
|
|
This endpoint reads an ACL role with the given ID. If no role exists with the |
|
given ID, a 404 is returned instead of a 200 response. |
|
|
|
| Method | Path | Produces | |
|
| ------ | --------------- | ------------------ | |
|
| `GET` | `/acl/role/:id` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `YES` | `all` | `none` | `acl:read` | |
|
|
|
The corresponding CLI command is [`consul acl role read`](/consul/commands/acl/role/read). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the role you lookup. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
@include 'http-api-query-parms-partition.mdx' |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4 |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4", |
|
"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" |
|
} |
|
], |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateID": "00000000-0000-0000-0000-000000000003", |
|
"TemplateName": "builtin/service", |
|
"TemplateVariables": { |
|
"Name": "api" |
|
} |
|
}, |
|
{ |
|
"TemplateID": "00000000-0000-0000-0000-000000000005", |
|
"TemplateName": "builtin/dns" |
|
} |
|
], |
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=", |
|
"CreateIndex": 57, |
|
"ModifyIndex": 57 |
|
} |
|
``` |
|
|
|
## Read a Role by Name |
|
|
|
This endpoint reads an ACL role with the given name. If no role exists with the |
|
given name, a 404 is returned instead of a 200 response. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ---------------------- | ------------------ | |
|
| `GET` | `/acl/role/name/:name` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `YES` | `all` | `none` | `acl:read` | |
|
|
|
The corresponding CLI command is [`consul acl role read -name=<string>`](/consul/commands/acl/role/read#name). |
|
|
|
### Path Parameters |
|
|
|
- `name` `(string: <required>)` - Specifies the name of the ACL role to read. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
@include 'http-api-query-parms-partition.mdx' |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/role/name/example-role |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4", |
|
"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" |
|
} |
|
], |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateID": "00000000-0000-0000-0000-000000000003", |
|
"TemplateName": "builtin/service", |
|
"TemplateVariables": { |
|
"Name": "api" |
|
} |
|
}, |
|
{ |
|
"TemplateID": "00000000-0000-0000-0000-000000000005", |
|
"TemplateName": "builtin/dns" |
|
} |
|
], |
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=", |
|
"CreateIndex": 57, |
|
"ModifyIndex": 57 |
|
} |
|
``` |
|
|
|
## Update a Role |
|
|
|
This endpoint updates an existing ACL role. |
|
|
|
| Method | Path | Produces | |
|
| ------ | --------------- | ------------------ | |
|
| `PUT` | `/acl/role/:id` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `NO` | `none` | `none` | `acl:write` | |
|
|
|
The corresponding CLI command is [`consul acl role update`](/consul/commands/acl/role/update). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the role you update. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you update. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### JSON Request Body Schema |
|
|
|
- `ID` `(string: <optional>)` - If specified, this field must be an exact match |
|
with the `id` path parameter. |
|
|
|
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name |
|
can only contain alphanumeric characters as well as `-` and `_` and must be |
|
unique. |
|
- `Description` `(string: "")` - Free form human readable description of the role. |
|
|
|
- `Policies` `(array<PolicyLink>)` - The list of policies that should be |
|
applied to the role. A PolicyLink is an object with an "ID" and/or "Name" |
|
field to specify a policy. With the PolicyLink, roles can be linked to |
|
policies either by the policy name or by the policy ID. When policies are |
|
linked by name they will be internally resolved to the policy ID. With |
|
linking roles internally by IDs, Consul enables policy renaming without |
|
breaking tokens. |
|
|
|
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service |
|
identities](/consul/docs/security/acl#service-identities) that should be |
|
applied to the role. Added in Consul 1.5.0. |
|
|
|
- `NodeIdentities` `(array<NodeIdentity>)` - The list of [node |
|
identities](/consul/docs/security/acl#node-identities) that should be |
|
applied to the role. Added in Consul 1.8.1. |
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you update. |
|
This field takes precedence over the `ns` query parameter, |
|
one of several [other methods to specify the namespace](#methods-to-specify-namespace). |
|
|
|
@include 'http-api-body-options-partition.mdx' |
|
|
|
### Sample Payload |
|
|
|
```json |
|
{ |
|
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb", |
|
"Name": "example-two", |
|
"Policies": [ |
|
{ |
|
"Name": "node-read" |
|
} |
|
], |
|
"ServiceIdentities": [ |
|
{ |
|
"ServiceName": "db" |
|
} |
|
], |
|
"NodeIdentities": [ |
|
{ |
|
"NodeName": "node-1", |
|
"Datacenter": "dc2" |
|
} |
|
], |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateName": "builtin/dns" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request PUT \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/acl/role/8bec74a4-5ced-45ed-9c9d-bca6153490bb |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb", |
|
"Name": "example-two", |
|
"Policies": [ |
|
{ |
|
"ID": "783beef3-783f-f41f-7422-7087dc272765", |
|
"Name": "node-read" |
|
} |
|
], |
|
"ServiceIdentities": [ |
|
{ |
|
"ServiceName": "db" |
|
} |
|
], |
|
"NodeIdentities": [ |
|
{ |
|
"NodeName": "node-1", |
|
"Datacenter": "dc2" |
|
} |
|
], |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateID": "00000000-0000-0000-0000-000000000005", |
|
"TemplateName": "builtin/dns" |
|
} |
|
], |
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", |
|
"CreateIndex": 14, |
|
"ModifyIndex": 28 |
|
} |
|
``` |
|
|
|
## Delete a Role |
|
|
|
This endpoint deletes an ACL role. |
|
|
|
| Method | Path | Produces | |
|
| -------- | --------------- | ------------------ | |
|
| `DELETE` | `/acl/role/:id` | `application/json` | |
|
|
|
Even though the return type is application/json, the value is either true or |
|
false indicating whether the delete succeeded. |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `NO` | `none` | `none` | `acl:write` | |
|
|
|
The corresponding CLI command is [`consul acl role delete`](/consul/commands/acl/role/delete). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the role you delete. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you delete. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
@include 'http-api-query-parms-partition.mdx' |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request DELETE \ |
|
http://127.0.0.1:8500/v1/acl/role/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
true |
|
``` |
|
|
|
## List Roles |
|
|
|
This endpoint lists all the ACL roles. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ------------ | ------------------ | |
|
| `GET` | `/acl/roles` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `YES` | `all` | `none` | `acl:read` | |
|
|
|
The corresponding CLI command is [`consul acl role list`](/consul/commands/acl/role/list). |
|
|
|
### Query Parameters |
|
|
|
- `policy` `(string: "")` - Filters the role list to those roles that are |
|
linked with this specific policy ID. |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the roles in the specified namespace. |
|
The namespace may be specified as '\*' to return results for all namespaces. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
@include 'http-api-query-parms-partition.mdx' |
|
|
|
## Sample Request |
|
|
|
```shell-session |
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/roles |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
[ |
|
{ |
|
"ID": "5e52a099-4c90-c067-5478-980f06be9af5", |
|
"Name": "node-read", |
|
"Description": "", |
|
"Policies": [ |
|
{ |
|
"ID": "783beef3-783f-f41f-7422-7087dc272765", |
|
"Name": "node-read" |
|
} |
|
], |
|
"Hash": "K6AbfofgiZ1BEaKORBloZf7WPdg45J/PipHxQiBlK1U=", |
|
"CreateIndex": 50, |
|
"ModifyIndex": 50 |
|
}, |
|
{ |
|
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4", |
|
"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" |
|
} |
|
], |
|
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=", |
|
"CreateIndex": 57, |
|
"ModifyIndex": 57 |
|
} |
|
] |
|
``` |
|
|
|
## Methods to specify namespace <EnterpriseAlert inline /> |
|
|
|
ACL role endpoints |
|
support several methods for specifying the namespace of the ACL role resources |
|
with the following order of precedence: |
|
1. `Namespace` field of the JSON request body - |
|
only applies to [create](#create-a-role) and [update](#update-a-role) endpoints |
|
1. `ns` query parameter |
|
1. `X-Consul-Namespace` request header |
|
1. Namespace is inherited from the namespace of the request's ACL token (if any) |
|
1. The `default` namespace
|
|
|