mirror of https://github.com/hashicorp/consul
419 lines
15 KiB
Markdown
419 lines
15 KiB
Markdown
---
|
|
layout: api
|
|
page_title: ACL Auth Methods - HTTP API
|
|
sidebar_title: Auth Methods
|
|
description: The /acl/auth-method endpoints manage Consul's ACL Auth Methods.
|
|
---
|
|
|
|
# ACL Auth Method HTTP API
|
|
|
|
-> **1.5.0+:** The auth method APIs are available in Consul versions 1.5.0 and newer.
|
|
|
|
The `/acl/auth-method` endpoints [create](#create-an-auth-method),
|
|
[read](#read-an-auth-method), [update](#update-an-auth-method),
|
|
[list](#list-auth-methods) and [delete](#delete-an-auth-method)
|
|
ACL auth methods in Consul.
|
|
|
|
For more information on how to setup ACLs, please see
|
|
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
|
|
|
|
## 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](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| 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.
|
|
This field is immutable. For allowed values see the [auth method
|
|
documentation](/docs/acl/auth-methods).
|
|
|
|
- `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`](/api/acl/tokens.html#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`.
|
|
|
|
- `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](/docs/acl/auth-methods).
|
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - 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.
|
|
|
|
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - 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:
|
|
|
|
```text
|
|
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](https://github.com/hashicorp/hil) to interpolate the
|
|
same values that are usable by the `Selector` syntax. For example:
|
|
|
|
```text
|
|
prefixed-${serviceaccount.name}
|
|
```
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```shell
|
|
$ curl -X PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/auth-method
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| 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: "")` <EnterpriseAlert inline /> - 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
|
|
|
|
```shell
|
|
$ curl -X GET http://127.0.0.1:8500/v1/acl/auth-method/minikube
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| 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.
|
|
|
|
- `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`](/api/acl/tokens.html#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`.
|
|
|
|
- `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](/docs/acl/auth-methods).
|
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - 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.
|
|
|
|
- `NamespaceRules` `(array<NamespaceRule>)` <EnterpriseAlert inline /> - 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:
|
|
|
|
```text
|
|
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](https://github.com/hashicorp/hil) to interpolate the
|
|
same values that are usable by the `Selector` syntax. For example:
|
|
|
|
```text
|
|
prefixed-${serviceaccount.name}
|
|
```
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Name": "minikube",
|
|
"Description": "updated name",
|
|
"Config": {
|
|
"Host": "https://192.0.2.42:8443",
|
|
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
|
|
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell
|
|
$ curl -X PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/auth-method/minikube
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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](/api/acl/binding-rules) as well as any
|
|
outstanding [tokens](/api/acl/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](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| 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: "")` <EnterpriseAlert inline /> - 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
|
|
|
|
```shell
|
|
$ curl -X DELETE \
|
|
http://127.0.0.1:8500/v1/acl/auth-method/minikube
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
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](/api/features/blocking),
|
|
[consistency modes](/api/features/consistency),
|
|
[agent caching](/api/features/caching), and
|
|
[required ACLs](/api#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `YES` | `all` | `none` | `acl:read` |
|
|
|
|
### Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - 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
|
|
|
|
```shell
|
|
$ 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](#read-an-auth-method).
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Name": "minikube-1",
|
|
"Type": "kubernetes",
|
|
"Description": "",
|
|
"CreateIndex": 14,
|
|
"ModifyIndex": 14
|
|
},
|
|
{
|
|
"Name": "minikube-2",
|
|
"Type": "kubernetes",
|
|
"Description": "",
|
|
"CreateIndex": 15,
|
|
"ModifyIndex": 15
|
|
}
|
|
]
|
|
```
|