open-consul/website/source/api/acl/auth-methods.html.md

layout	page_title	sidebar_current	description
api	ACL Auth Methods - HTTP API	api-acl-auth-methods	The /acl/auth-method endpoints manage Consul's ACL Auth Methods.

-> 1.5.0+: The auth method APIs are available in Consul versions 1.5.0 and newer.

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, please see the ACL Guide.

Create an Auth Method

This endpoint creates a new ACL auth method.

Method	Path	Produces
PUT	/acl/auth-method	application/json

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

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
NO	none	none	acl:write

Payload Fields

• 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. The only allowed value in Consul 1.5.0 is "kubernetes". This field is immutable.

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

• 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: "") - (Enterprise Only) Specifies the namespace to create the auth method within. 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 at all, 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

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

Method	Path	Produces
GET	/acl/auth-method/:name	application/json

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

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
YES	all	none	acl:read

Parameters

• name (string: <required>) - Specifies the name of the ACL auth method to read. This is required and is specified as part of the URL path.

• ns (string: "") - (Enterprise Only) Specifies the namespace to lookup the auth method within. This value can be specified as the ns URL query parameter or in 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 -X 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.

Method	Path	Produces
PUT	/acl/auth-method/:name	application/json

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

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
NO	none	none	acl:write

Parameters

• Name (string: <required>) - Specifies the name of the auth method 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.

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

• 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: "") - (Enterprise Only) Specifies the namespace of the auth method 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 at all, 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

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

~> Deleting an auth method will also immediately delete all associated binding rules as well as any outstanding tokens created from this auth method.

Method	Path	Produces
DELETE	/acl/auth-method/:name	application/json

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.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
NO	none	none	acl:write

Parameters

• name (string: <required>) - Specifies the name of the ACL auth method to delete. This is required and is specified as part of the URL path.

• ns (string: "") - (Enterprise Only) Specifies the namespace of the Auth Method to delete. This value can be specified as the ns URL query parameter or in 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 -X 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.

Method	Path	Produces
GET	/acl/auth-methods	application/json

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

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
YES	all	none	acl:read

Parameters

• ns (string: "") - (Enterprise Only) Specifies the namespace to list the auth methods for. This value can be specified as the ns URL query parameter or in 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 -X GET http://127.0.0.1:8500/v1/acl/auth-methods

Sample Response

-> Note - The contents of the Config field are not included in the listing and must be retrieved by the auth method reading endpoint.

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