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.
586 lines
18 KiB
586 lines
18 KiB
--- |
|
layout: api |
|
page_title: ACL Binding Rules - HTTP API |
|
description: The /acl/binding-rule endpoints manage Consul's ACL Binding Rules. |
|
--- |
|
|
|
# ACL Binding Rule HTTP API |
|
|
|
-> **1.5.0+:** The binding rule APIs are available in Consul versions 1.5.0 and newer. |
|
|
|
The `/acl/binding-rule` endpoints [create](#create-a-binding-rule), |
|
[read](#read-a-binding-rule), [update](#update-a-binding-rule), |
|
[list](#list-binding-rules) and [delete](#delete-a-binding-rule) ACL binding |
|
rules 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 Binding Rule |
|
|
|
This endpoint creates a new ACL binding rule. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ------------------- | ------------------ | |
|
| `PUT` | `/acl/binding-rule` | `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 binding-rule create`](/consul/commands/acl/binding-rule/create). |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you create. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### JSON Request Body Schema |
|
|
|
- `Description` `(string: "")` - Free form human readable description of the binding rule. |
|
|
|
- `AuthMethod` `(string: <required>)` - The name of the auth method that this |
|
rule applies to. This field is immutable. |
|
|
|
- `Selector` `(string: "")` - Specifies the expression used to match this rule |
|
against valid identities returned from an auth method validation. If empty |
|
this binding rule matches all valid identities returned from the auth method. For example: |
|
|
|
```text |
|
serviceaccount.namespace==default and serviceaccount.name!=vault |
|
``` |
|
|
|
- `BindType` `(string: <required>)` - Specifies the way the binding rule |
|
affects a token created at login. You can specify one of the following: |
|
|
|
- `service` - The computed bind name value is used as an |
|
`ACLServiceIdentity.ServiceName` field in the token that is created. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"ServiceIdentities": [ |
|
{ |
|
"ServiceName": "<computed BindName>" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `node` - The computed bind name value is used as an |
|
`ACLNodeIdentity.NodeName` field in the token that is created. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"NodeIdentities": [ |
|
{ |
|
"NodeName": "<computed BindName>", |
|
"Datacenter": "<local datacenter>" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `role` - The computed bind name value is used as a `RoleLink.Name` |
|
field in the token that is created. This binding rule will only apply if a |
|
role with the given name exists at login-time. If it does not then this |
|
rule is ignored. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"Roles": [ |
|
{ |
|
"Name": "<computed BindName>" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `templated-policy` - The bind name value is used as an |
|
`ACLTemplatedPolicy.TemplateName` field in the token that is created. The computed |
|
`BindVars` values are used in the `ACLTemplatedPolicy.TemplateVariables` field. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateName": "<template name>", |
|
"TemplateVariables": { |
|
"Name": "<name>" |
|
} |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `BindName` `(string: <required>)` - The name to bind to a token at |
|
login-time. What it binds to can be adjusted with different values of the |
|
`BindType` field. This can either be a plain string or lightly templated |
|
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same |
|
values that are usable by the `Selector` syntax. For example: |
|
|
|
```text |
|
prefixed-${serviceaccount.name} |
|
``` |
|
|
|
- `BindVars` `(<ACLTemplatedPolicyVariables>)` - Specifies the templated policy |
|
variables when `BindType` field is set to `templated-policy`. Consul populates |
|
the `TemplatedPolicies.TemplateVariables` field with the computed `BindVars` values |
|
in the token it creates. You can specify either a plain text string or templated |
|
string using [HIL syntax](https://github.com/hashicorp/hil). |
|
Consul interpolates templated strings with values that are usable by the `Selector` syntax. |
|
For example: |
|
|
|
``` |
|
"BindVars": { |
|
"Name": "prefixed-${serviceaccount.name}" |
|
} |
|
``` |
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule 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 |
|
{ |
|
"Description": "example rule", |
|
"AuthMethod": "minikube", |
|
"Selector": "serviceaccount.namespace==default", |
|
"BindType": "service", |
|
"BindName": "{{ serviceaccount.name }}" |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request PUT \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/acl/binding-rule |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", |
|
"Description": "example rule", |
|
"AuthMethod": "minikube", |
|
"Selector": "serviceaccount.namespace==default", |
|
"BindType": "service", |
|
"BindName": "{{ serviceaccount.name }}", |
|
"CreateIndex": 17, |
|
"ModifyIndex": 17 |
|
} |
|
``` |
|
|
|
## Read a Binding Rule |
|
|
|
This endpoint reads an ACL binding rule with the given ID. If no |
|
binding rule exists with the given ID, a 404 is returned instead of a 200 |
|
response. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ----------------------- | ------------------ | |
|
| `GET` | `/acl/binding-rule/: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 binding-rule read`](/consul/commands/acl/binding-rule/read). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to read. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule 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/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", |
|
"Description": "example rule", |
|
"AuthMethod": "minikube", |
|
"Selector": "serviceaccount.namespace==default", |
|
"BindType": "service", |
|
"BindName": "{{ serviceaccount.name }}", |
|
"CreateIndex": 17, |
|
"ModifyIndex": 17 |
|
} |
|
``` |
|
|
|
## Update a Binding Rule |
|
|
|
This endpoint updates an existing ACL binding rule. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ----------------------- | ------------------ | |
|
| `PUT` | `/acl/binding-rule/: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 binding-rule update`](/consul/commands/acl/binding-rule/update). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule you update. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule 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. |
|
|
|
- `Description` `(string: "")` - Free form human readable description of the binding rule. |
|
|
|
- `AuthMethod` `(string: <required>)` - Specifies the name of the auth |
|
method that this rule applies to. This field is immutable so if present in |
|
the body then it must match the existing value. If not present then the value |
|
will be filled in by Consul. |
|
|
|
- `Selector` `(string: "")` - Specifies the expression used to match this rule |
|
against valid identities returned from an auth method validation. If empty |
|
this binding rule matches all valid identities returned from the auth method. For example: |
|
|
|
```text |
|
serviceaccount.namespace==default and serviceaccount.name!=vault |
|
``` |
|
|
|
- `BindType` `(string: <required>)` - Specifies the way the binding rule |
|
affects a token created at login. You can specify one of the following: |
|
|
|
- `service` - The computed bind name value is used as an |
|
`ACLServiceIdentity.ServiceName` field in the token that is created. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"ServiceIdentities": [ |
|
{ |
|
"ServiceName": "<computed BindName>" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `node` - The computed bind name value is used as an |
|
`ACLNodeIdentity.NodeName` field in the token that is created. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"NodeIdentities": [ |
|
{ |
|
"NodeName": "<computed BindName>", |
|
"Datacenter": "<local datacenter>" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `role` - The computed bind name value is used as a `RoleLink.Name` |
|
field in the token that is created. This binding rule will only apply if a |
|
role with the given name exists at login-time. If it does not then this |
|
rule is ignored. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"Roles": [ |
|
{ |
|
"Name": "<computed BindName>" |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `templated-policy` - Consul populates the `TemplatedPolicies.TemplateName` with |
|
the value specified in the `BindName` field in the token that is created. Consul |
|
also populates the `TemplatedPolicies.TemplateVariables` field with the computed |
|
`BindVars` values. |
|
|
|
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint"> |
|
|
|
```json |
|
{ |
|
"AccessorID": "<token accessor ID>", |
|
"SecretID": "<token secret ID>", |
|
"TemplatedPolicies": [ |
|
{ |
|
"TemplateName": "<template name>", |
|
"TemplateVariables": { |
|
"Name": "<name>" |
|
} |
|
} |
|
] |
|
} |
|
``` |
|
|
|
</CodeBlockConfig> |
|
|
|
- `BindName` `(string: <required>)` - The name to bind to a token at |
|
login-time. What it binds to can be adjusted with different values of the |
|
`BindType` field. This can either be a plain string or lightly templated |
|
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same |
|
values that are usable by the `Selector` syntax. For example: |
|
|
|
```text |
|
prefixed-${serviceaccount.name} |
|
``` |
|
|
|
- `BindVars` `(<ACLTemplatedPolicyVariables>)` - Specifies the templated policy |
|
variables when the `BindType` field is set to `templated-policy`. Consul |
|
populates the `TemplatedPolicies.TemplateVariables` field with the computed |
|
`BindVars` values in the token it creates. You can specify either a plain text |
|
string or templated string using [HIL syntax](https://github.com/hashicorp/hil). |
|
Consul interpolates templated strings with values that are usable by the `Selector` |
|
syntax. For example: |
|
|
|
``` |
|
"BindVars": { |
|
"Name": "prefixed-${serviceaccount.name}" |
|
} |
|
``` |
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule 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 |
|
{ |
|
"Description": "updated rule", |
|
"Selector": "serviceaccount.namespace=dev", |
|
"BindType": "role", |
|
"BindName": "{{ serviceaccount.name }}" |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request PUT \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", |
|
"Description": "updated rule", |
|
"AuthMethod": "minikube", |
|
"Selector": "serviceaccount.namespace=dev", |
|
"BindType": "role", |
|
"BindName": "{{ serviceaccount.name }}", |
|
"CreateIndex": 17, |
|
"ModifyIndex": 18 |
|
} |
|
``` |
|
|
|
## Delete a Binding Rule |
|
|
|
This endpoint deletes an ACL binding rule. |
|
|
|
| Method | Path | Produces | |
|
| -------- | ----------------------- | ------------------ | |
|
| `DELETE` | `/acl/binding-rule/: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 binding-rule delete`](/consul/commands/acl/binding-rule/delete). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the binding rule you delete. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule 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/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
true |
|
``` |
|
|
|
## List Binding Rules |
|
|
|
This endpoint lists all the ACL binding rules. |
|
|
|
| Method | Path | Produces | |
|
| ------ | -------------------- | ------------------ | |
|
| `GET` | `/acl/binding-rules` | `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 binding-rule list`](/consul/commands/acl/binding-rule/list). |
|
|
|
### Query Parameters |
|
|
|
- `authmethod` `(string: "")` - Filters the binding rule list to those binding |
|
rules that are linked with the specific named auth method. |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the binding rules 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/binding-rules |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
[ |
|
{ |
|
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", |
|
"Description": "example 1", |
|
"AuthMethod": "minikube-1", |
|
"BindType": "service", |
|
"BindName": "k8s-{{ serviceaccount.name }}", |
|
"CreateIndex": 17, |
|
"ModifyIndex": 17 |
|
}, |
|
{ |
|
"ID": "b4f0a0a3-69f2-7a4f-6bef-326034ace9fa", |
|
"Description": "example 2", |
|
"AuthMethod": "minikube-2", |
|
"BindType": "service", |
|
"Selector": "serviceaccount.namespace==default", |
|
"BindName": "k8s-{{ serviceaccount.name }}", |
|
"CreateIndex": 18, |
|
"ModifyIndex": 18 |
|
} |
|
] |
|
``` |
|
|
|
## Methods to specify namespace <EnterpriseAlert inline /> |
|
|
|
Binding rule create, read, update, and delete endpoints |
|
support several methods for specifying the namespace of the auth method resource |
|
with the following order of precedence: |
|
1. `Namespace` field of the JSON request body - |
|
only applies to [create](#create-a-binding-rule) and [update](#update-a-binding-rule) 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
|
|
|