8295d0e516
* acl: add validation to binding rule selector on upsert. * docs: add more information on binding rule selector escaping.
286 lines
8.6 KiB
Plaintext
286 lines
8.6 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: ACL Binding Rules - HTTP API
|
|
description: The /acl/binding-rules endpoints are used to configure and manage ACL binding rules.
|
|
---
|
|
|
|
# ACL Binding Rules HTTP API
|
|
|
|
The `/acl/binding-rules` and `/acl/binding-rule` endpoints are used to manage ACL Binding Rules.
|
|
|
|
## Read Binding Rule by Name
|
|
|
|
This endpoint reads an ACL Binding Rule with the given name. This queries the
|
|
Binding Rule that has been replicated to the region, and may lag behind the
|
|
authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ---------------------------- | ------------------ |
|
|
| `GET` | `/acl/binding-rule/:rule_id` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries),
|
|
[consistency modes](/nomad/api-docs#consistency-modes) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
| ---------------- | ----------------- | ------------ |
|
|
| `YES` | `all` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `:rule_id` `(string: <required>)` - Specifies the ID of the ACL Binding Rule.
|
|
This is specified as part of the path.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AuthMethod": "example-acl-auth-method",
|
|
"BindName": "role",
|
|
"BindType": "role",
|
|
"CreateIndex": 16,
|
|
"CreateTime": "2022-12-16T10:29:07.248465Z",
|
|
"Description": "updated-acl-binding-rule",
|
|
"ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
|
|
"ModifyIndex": 17,
|
|
"ModifyTime": "2022-12-19T16:40:52.602004Z",
|
|
"Selector": "engineering in list.roles"
|
|
}
|
|
```
|
|
|
|
## List Binding Rules
|
|
|
|
This endpoint lists all ACL Binding Rules. This lists the Binding Rules that have
|
|
been replicated to the region, and may lag behind the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------- | ------------------ |
|
|
| `GET` | `/acl/binding-rules` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries),
|
|
[consistency modes](/nomad/api-docs#consistency-modes) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
| ---------------- | ----------------- | ------------ |
|
|
| `YES` | `all` | `management` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
https://localhost:4646/v1/acl/binding-rules
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"AuthMethod": "auth0",
|
|
"CreateIndex": 16,
|
|
"Description": "updated-acl-binding-rule",
|
|
"Hash": "N7aEMsAfl3btWrZSwaWdzcRIAO3uRrRH2yQ8rPsuJ44=",
|
|
"ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
|
|
"ModifyIndex": 17
|
|
}
|
|
]
|
|
```
|
|
|
|
## Create Binding Rule
|
|
|
|
This endpoint creates an ACL Binding Rule. The request is always forwarded to the
|
|
authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------- | ------------------ |
|
|
| `POST` | `/acl/binding-rule` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `Description` `(string: "")` - Human-readable, operator set description that
|
|
can provide additional context about the binding role. This is an operational
|
|
field.
|
|
|
|
- `AuthMethod` `(string: <required>)` - Name of the auth method for which this
|
|
rule applies to. This is a required field and the method must exist within state
|
|
before the cluster administrator can create the rule.
|
|
|
|
- `Selector` `(string: "")` - A boolean expression that matches against verified
|
|
identity attributes returned from the auth method during login. This is
|
|
optional and when not set, provides a catch-all rule. If set, it must be a
|
|
valid [go-bexpr][] expression; for example, a dash in the claim name will
|
|
require it to be encased in quotes and escaped such as
|
|
`"\"project-developer\" in list.roles"`.
|
|
|
|
|
|
- `BindType` `(string: <required>)` - Adjusts how this binding rule is applied
|
|
at login time. Valid values are `role`, `policy`, and `management`.
|
|
|
|
- `BindName` `(string: <required>)` - Target of the binding. Can be lightly
|
|
templated using HIL ${foo} syntax from available field names. If the bind
|
|
type is set to `management`, this should not be set. How it is used depends
|
|
on the BindType.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Description": "example-acl-binding-rule",
|
|
"AuthMethod": "auth0",
|
|
"Selector": "engineering in list.roles",
|
|
"BindType": "role",
|
|
"BindName": "eng-ro",
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/acl/binding-rule
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AuthMethod": "auth0",
|
|
"BindName": "eng-ro",
|
|
"BindType": "role",
|
|
"CreateIndex": 16,
|
|
"CreateTime": "2022-12-16T10:29:07.248465Z",
|
|
"Description": "example-acl-binding-rule",
|
|
"ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
|
|
"ModifyIndex": 16,
|
|
"ModifyTime": "2022-12-16T10:29:07.248465Z",
|
|
"Selector": "engineering in list.roles"
|
|
}
|
|
```
|
|
|
|
## Update Binding Rule
|
|
|
|
This endpoint updates an existing ACL Binding Rule. The request is always
|
|
forwarded to the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------------ | ------------------ |
|
|
| `POST` | `/acl/binding-rule/:rule_id` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking
|
|
queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `Description` `(string: "")` - Human-readable, operator set description that
|
|
can provide additional context about the binding role. This is an operational
|
|
field.
|
|
|
|
- `Selector` `(string: "")` - A boolean expression that matches against verified
|
|
identity attributes returned from the auth method during login. This is
|
|
optional and when not set, provides a catch-all rule. If set, it must be a
|
|
valid [go-bexpr][] expression; for example, a dash in the claim name will
|
|
require it to be encased in quotes and escaped such as
|
|
`"\"project-developer\" in list.roles"`.
|
|
|
|
- `BindType` `(string: "")` - Adjusts how this binding rule is applied at login
|
|
time. Valid values are `role`, `policy`, and `management`.
|
|
|
|
- `BindName` `(string: "")` - Target of the binding. Can be lightly templated
|
|
using HIL ${foo} syntax from available field names. How it is used depends on
|
|
the BindType.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Description": "new description",
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/acl/binding-rule/example-acl-binding-rule
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AuthMethod": "auth0",
|
|
"BindName": "eng-ro",
|
|
"BindType": "role",
|
|
"CreateIndex": 16,
|
|
"CreateTime": "2022-12-16T10:29:07.248465Z",
|
|
"Description": "new description",
|
|
"ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
|
|
"ModifyIndex": 17,
|
|
"ModifyTime": "2022-12-19T16:40:52.602004Z",
|
|
"Selector":"engineering in list.roles"
|
|
}
|
|
```
|
|
|
|
## Delete Binding Rule
|
|
|
|
This endpoint deletes the ACL Binding Rule as identified by its ID. This request
|
|
is always forwarded to the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | ---------------------------- | -------------- |
|
|
| `DELETE` | `/acl/binding-rule/:rule_id` | `(empty body)` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `rule_id` `(string: <required>)` - Specifies the ID of Binding Rule to delete
|
|
and is specified as part of the path.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09
|
|
```
|
|
|
|
[go-bexpr]: https://github.com/hashicorp/go-bexpr
|