mirror of https://github.com/status-im/consul.git
577 lines
18 KiB
Plaintext
577 lines
18 KiB
Plaintext
---
|
|
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).
|
|
|
|
### 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).
|
|
|
|
### 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).
|
|
|
|
### 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).
|
|
|
|
### 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).
|
|
|
|
## 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
|