luxolus/open-consul
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-consul/website/content/api-docs/acl/auth-methods.mdx
Jared Kirschner daf5e3ea10 docs: split HTTP API params into sections by type 
Path parameters, query parameters, and request body parameters are now shown in
separate sections rather than combined into one general parameters section.
This makes it much easier to understand quickly where a parameter should be
provided.
2022-05-25 14:45:47 -07:00

453 lines
16 KiB
Plaintext
Raw Blame History

---
layout: api
page_title: ACL Auth Methods - HTTP API
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 check
the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
## 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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
The corresponding CLI command is [`consul acl auth-method create`](/commands/acl/auth-method/create).
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you create.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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](/docs/security/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-docs/acl/tokens#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](/docs/security/acl/auth-methods).
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-namespace).
- `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-session
$ curl --request 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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
The corresponding CLI command is [`consul acl auth-method read`](/commands/acl/auth-method/read).
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to read.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl --request 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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
The corresponding CLI command is [`consul acl auth-method update`](/commands/acl/auth-method/update).
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the auth method you update.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### 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`](/api-docs/acl/tokens#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](/docs/security/acl/auth-methods).
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-namespace).
- `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-session
$ curl --request 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-docs/acl/binding-rules) as well as any
outstanding [tokens](/api-docs/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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
The corresponding CLI command is [`consul acl auth-method delete`](/commands/acl/auth-method/delete).
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to delete.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl --request 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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
The corresponding CLI command is [`consul acl auth-method list`](/commands/acl/auth-method/list).
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-namespace).
The namespace may be specified as '\*' and then
results will be returned for all namespaces.
## Sample Request
```shell-session
$ curl --request 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
}
]
```
## Methods to Specify Namespace <EnterpriseAlert inline />
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](#create-an-auth-method) and [update](#update-an-auth-method) endpoints
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace
Reference in a new issue View git blame Copy permalink