open-nomad/website/content/api-docs/acl/binding-rules.mdx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

290 lines
8.8 KiB
Plaintext
Raw Normal View History

---
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"`.
~> **Caveat:** Selectors that operate on `ClaimMappings` (as opposed to
`ListClaimMappings`), the key that we match against has to be prefixed with
`value.` (e.g. `value.owner == username` for a claim mapping that has `owner`
as its key).
- `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