github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/api-docs/acl/binding-rules.mdx

500 lines
16 KiB
Markdown
Raw Blame History

---
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, please check
the [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.
- `BindType=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>
- `BindType=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>
- `BindType=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>
- `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}
```
- `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.
- `BindType=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>
- `BindType=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>
- `BindType=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>
- `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}
```
- `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
Reference in New Issue View Git Blame Copy Permalink