ACL Binding Rule HTTP API

The /acl/binding-rule endpoints create, read, update, list and delete ACL binding rules in Consul.

For more information on how to setup ACLs, please check the ACL tutorial.

Create a Binding Rule

This endpoint creates a new ACL binding rule.

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

The corresponding CLI command is consul acl binding-rule create.

Parameters

• 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:

  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.

    { ...other fields...
        "ServiceIdentities": [
            { "ServiceName": "<computed BindName>" }
        ]
    }
    

  • BindType=node - The computed bind name value is used as an ACLNodeIdentity.NodeName field in the token that is created.

    { ...other fields...
        "NodeIdentities": [
            { "NodeName": "<computed BindName>", "Datacenter": "<local datacenter>" }
        ]
    }
    

  • 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.

    { ...other fields...
        "Roles": [
            { "Name": "<computed BindName>" }
        ]
    }
    

• 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 to interpolate the same values that are usable by the Selector syntax. For example:

  prefixed-${serviceaccount.name}
  

• Namespace (string: "") EnterpriseEnterprise - Specifies the namespace to create the binding rule. If not provided in the JSON body, the value of the ns URL query parameter or in the X-Consul-Namespace header will be used. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Payload

{
  "Description": "example rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "service",
  "BindName": "{{ serviceaccount.name }}"
}

Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/binding-rule

Sample Response

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

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

The corresponding CLI command is consul acl binding-rule read.

Parameters

• id (string: <required>) - Specifies the UUID of the ACL binding rule to read. This is required and is specified as part of the URL path.

• ns (string: "") EnterpriseEnterprise - Specifies the namespace to lookup the binding rule. This value can be specified as the ns URL query parameter or the X-Consul-Namespace header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

Sample Response

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

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

The corresponding CLI command is consul acl binding-rule update.

Parameters

• ID (string: <required>) - Specifies the ID of the binding rule to update. This is required in the URL path but may also be specified in the JSON body. If specified in both places then they must match exactly.

• 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:

  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.

    { ...other fields...
        "ServiceIdentities": [
            { "ServiceName": "<computed BindName>" }
        ]
    }
    

  • BindType=node - The computed bind name value is used as an ACLNodeIdentity.NodeName field in the token that is created.

    { ...other fields...
        "NodeIdentities": [
            { "NodeName": "<computed BindName>", "Datacenter": "<local datacenter>" }
        ]
    }
    

  • 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.

    { ...other fields...
        "Roles": [
            { "Name": "<computed BindName>" }
        ]
    }
    

• 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 to interpolate the same values that are usable by the Selector syntax. For example:

  prefixed-${serviceaccount.name}
  

• Namespace (string: "") EnterpriseEnterprise - Specifies the namespace of the binding rule to update. If not provided in the JSON body, the value of the ns URL query parameter or in the X-Consul-Namespace header will be used. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Payload

{
  "Description": "updated rule",
  "Selector": "serviceaccount.namespace=dev",
  "BindType": "role",
  "BindName": "{{ serviceaccount.name }}"
}

Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

Sample Response

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

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, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul acl binding-rule delete.

Parameters

• id (string: <required>) - Specifies the UUID of the ACL binding rule to delete. This is required and is specified as part of the URL path.

• ns (string: "") EnterpriseEnterprise - Specifies the namespace of the binding rule to delete. This value can be specified as the ns URL query parameter or the X-Consul-Namespace header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

Sample Response

true

List Binding Rules

This endpoint lists all the ACL binding rules.

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

The corresponding CLI command is consul acl binding-rule list.

Parameters

• authmethod (string: "") - Filters the binding rule list to those binding rules that are linked with the specific named auth method.

• ns (string: "") EnterpriseEnterprise - Specifies the namespace to list the binding rules for. This value can be specified as the ns URL query parameter or the X-Consul-Namespace header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the default namespace. The namespace may be specified as '*' and then results will be returned for all namespaces. Added in Consul 1.7.0.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rules

Sample Response

[
  {
    "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
  }
]