ACL Auth Method HTTP API

The /acl/auth-method endpoints create, read, update, list and delete ACL auth methods in Consul.

For more information on how to setup ACLs, refer to the following resources:

• Access control list (ACL) overview
• ACL tutorial

Create an Auth Method

This endpoint creates a new ACL auth method.

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 auth-method create.

Query Parameters

• ns (string: "") EnterpriseEnterprise - Specifies the namespace of the auth method you create. You can also specify the namespace through other methods.

JSON Request Body Schema

• Name (string: <required>) - Specifies a name for the ACL auth method. The name can contain alphanumeric characters, dashes -, and underscores _. This field is immutable and must be unique.

• Type (string: <required>) - The type of auth method being configured. This field is immutable. For allowed values see the auth method documentation.

• Description (string: "") - Free form human readable description of the auth method.

• DisplayName (string: "") - An optional name to use instead of the Name field when displaying information about this auth method. Added in Consul 1.8.0.

• MaxTokenTTL (duration: 0s) - This specifies the maximum life of any token created by this auth method. When set it will initialize the ExpirationTime field on all tokens to a value of Token.CreateTime + AuthMethod.MaxTokenTTL. This field is not persisted beyond its initial use. Can be specified in the form of "60s" or "5m" (i.e., 60 seconds or 5 minutes, respectively). This value must be no smaller than 1 minute and no longer than 24 hours. Added in Consul 1.8.0.

  This must be set to a nonzero value for type=oidc.

• TokenLocality (string: "") - Defines the kind of token that this auth method should produce. This can be either "local" or "global". If empty the value of "local" is assumed. Added in Consul 1.8.0.

• Config (map[string]string: <required>) - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the auth method documentation.

• Namespace (string: "") EnterpriseEnterprise - Specifies the namespace of the auth method you create. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

• NamespaceRules (array<NamespaceRule>) EnterpriseEnterprise - A set of rules that can control which namespace tokens created via this auth method will be created within. Note that assigning namespaces via rules requires the auth method to reside within the default namespace. Unlike binding rules, the first matching namespace rule wins. Added in Consul 1.8.0.

  • Selector (string: "") - Specifies the expression used to match this namespace rule against valid identities returned from an auth method validation. If empty this namespace rule matches all valid identities returned from the auth method. For example:

    serviceaccount.namespace==default and serviceaccount.name!=vault
    

  • BindNamespace (string: <required>) - If the namespace rule's Selector matches then this is used to control the namespace where the token is created. 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}
    

• Partition (string: "") - EnterpriseEnterprise The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Payload

{
  "Name": "minikube",
  "Type": "kubernetes",
  "Description": "dev minikube cluster",
  "Config": {
    "Host": "https://192.0.2.42:8443",
    "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
    "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
  }
}

Sample Request

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

Sample Response

{
  "Name": "minikube",
  "Type": "kubernetes",
  "Description": "dev minikube cluster",
  "Config": {
    "Host": "https://192.0.2.42:8443",
    "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
    "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
  },
  "CreateIndex": 15,
  "ModifyIndex": 15
}

Read an Auth Method

This endpoint reads an ACL auth method with the given name. If no auth method exists with the given name, 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 auth-method read.

Path Parameters

• name (string: <required>) - Specifies the name of the ACL auth method to read.

Query Parameters

• ns (string: "") EnterpriseEnterprise - Specifies the namespace of the auth method you look up. You can also specify the namespace through other methods.

• partition (string: "") EnterpriseEnterprise - The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/auth-method/minikube

Sample Response

{
  "Name": "minikube",
  "Type": "kubernetes",
  "Description": "dev minikube cluster",
  "Config": {
    "Host": "https://192.0.2.42:8443",
    "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
    "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
  },
  "CreateIndex": 15,
  "ModifyIndex": 224
}

Update an Auth Method

This endpoint updates an existing ACL auth method.

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 auth-method update.

Path Parameters

• name (string: <required>) - Specifies the name of the auth method you update.

Query Parameters

• ns (string: "") EnterpriseEnterprise - Specifies the namespace of the auth method you update. You can also specify the namespace through other methods.

JSON Request Body Schema

• Name (string: <optional>) - If specified, this field must be an exact match with the name path parameter.

• Type (string: <required>) - Specifies the type of the auth method being updated. 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.

• Description (string: "") - Free form human readable description of the auth method.

• DisplayName (string: "") - An optional name to use instead of the Name field when displaying information about this auth method. Added in Consul 1.8.0.

• MaxTokenTTL (duration: 0s) - This specifies the maximum life of any token created by this auth method. When set it will initialize the ExpirationTime field on all tokens to a value of Token.CreateTime + AuthMethod.MaxTokenTTL. This field is not persisted beyond its initial use. Can be specified in the form of "60s" or "5m" (i.e., 60 seconds or 5 minutes, respectively). This value must be no smaller than 1 minute and no longer than 24 hours. Added in Consul 1.8.0.

  This must be set to a nonzero value for type=oidc.

• TokenLocality (string: "") - Defines the kind of token that this auth method should produce. This can be either "local" or "global". If empty the value of "local" is assumed. Added in Consul 1.8.0.

• Config (map[string]string: <required>) - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the auth method documentation.

• Namespace (string: "") EnterpriseEnterprise - Specifies the namespace of the auth method you update. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

• NamespaceRules (array<NamespaceRule>) EnterpriseEnterprise - A set of rules that can control which namespace tokens created via this auth method will be created within. Note that assigning namespaces via rules requires the auth method to reside within the default namespace. Unlike binding rules, the first matching namespace rule wins. Added in Consul 1.8.0.

  • Selector (string: "") - Specifies the expression used to match this namespace rule against valid identities returned from an auth method validation. If empty this namespace rule matches all valid identities returned from the auth method. For example:

    serviceaccount.namespace==default and serviceaccount.name!=vault
    

  • BindNamespace (string: <required>) - If the namespace rule's Selector matches then this is used to control the namespace where the token is created. 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}    
    

• Partition (string: "") - EnterpriseEnterprise The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Payload

{
  "Name": "minikube",
  "Description": "updated name",
  "Config": {
    "Host": "https://192.0.2.42:8443",
    "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
    "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
  }
}

Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/auth-method/minikube

Sample Response

{
  "Name": "minikube",
  "Description": "updated name",
  "Type": "kubernetes",
  "Config": {
    "Host": "https://192.0.2.42:8443",
    "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
    "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
  },
  "CreateIndex": 15,
  "ModifyIndex": 224
}

Delete an Auth Method

This endpoint deletes an ACL auth method.

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 auth-method delete.

Path Parameters

• name (string: <required>) - Specifies the name of the ACL auth method to delete.

Query Parameters

• ns (string: "") EnterpriseEnterprise - Specifies the namespace of the auth method you delete. You can also specify the namespace through other methods.

• partition (string: "") EnterpriseEnterprise - The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/auth-method/minikube

Sample Response

true

List Auth Methods

This endpoint lists all the ACL auth methods.

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 auth-method list.

Query Parameters

• ns (string: "") EnterpriseEnterprise - Return only the auth methods 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.

  The namespace may be specified as '*' and then results are returned for all namespaces.

• partition (string: "") EnterpriseEnterprise - The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/auth-methods

Sample Response

[
  {
    "Name": "minikube-1",
    "Type": "kubernetes",
    "Description": "",
    "CreateIndex": 14,
    "ModifyIndex": 14
  },
  {
    "Name": "minikube-2",
    "Type": "kubernetes",
    "Description": "",
    "CreateIndex": 15,
    "ModifyIndex": 15
  }
]

Methods to specify namespace EnterpriseEnterprise

Auth method create, read, update, and delete endpoints support several methods for specifying the namespace of the auth method resource. When multiple methods are used, namespace precedence occurs in the following order:

1. Namespace field of the JSON request body - only applies to create and update endpoints
2. ns query parameter
3. X-Consul-Namespace request header
4. Namespace is inherited from the namespace of the request's ACL token (if any)
5. The default namespace