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.

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Parameters

• :rule_id (string: <required>) - Specifies the ID of the ACL Binding Rule. This is specified as part of the path.

Sample Request

$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09

Sample Response

{
  "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.

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Sample Request

$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/binding-rules

Sample Response

[
  {
    "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.

The table below shows this endpoint's support for blocking queries and required ACLs.

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

{
  "Description": "example-acl-binding-rule",
  "AuthMethod": "auth0",
  "Selector": "engineering in list.roles",
  "BindType": "role",
  "BindName": "eng-ro",
}

Sample Request

$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/binding-rule

Sample Response

{
  "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.

The table below shows this endpoint's support for blocking queries and required ACLs.

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

{
  "Description": "new description",
}

Sample Request

$ 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

{
  "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.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• rule_id (string: <required>) - Specifies the ID of Binding Rule to delete and is specified as part of the path.

Sample Request

$ curl \
    --request DELETE \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09