mirror of https://github.com/hashicorp/consul
422 lines
12 KiB
Markdown
422 lines
12 KiB
Markdown
---
|
|
layout: api
|
|
page_title: Legacy ACLs - HTTP API
|
|
description: >-
|
|
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in
|
|
Consul.
|
|
---
|
|
|
|
-> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_
|
|
recommended you do not build anything using the legacy system and consider using
|
|
the new ACL [Token](/docs/api/acl-token) and [Policy](/docs/api/acl-policy) APIs instead.
|
|
|
|
# ACL HTTP API
|
|
|
|
These `/acl` endpoints create, update, destroy, and query ACL tokens in Consul. For more information about ACLs, please check the
|
|
[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
|
|
## Bootstrap ACLs
|
|
|
|
This endpoint does a special one-time bootstrap of the ACL system, making the first
|
|
management token if the [`acl_master_token`](/docs/agent/options#acl_master_token)
|
|
is not specified in the Consul server configuration, and if the cluster has not been
|
|
bootstrapped previously. This is available in Consul 0.9.1 and later, and requires all
|
|
Consul servers to be upgraded in order to operate.
|
|
|
|
This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's
|
|
configuration files.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ---------------- | ------------------ |
|
|
| `PUT` | `/acl/bootstrap` | `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` | `none` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
http://127.0.0.1:8500/v1/acl/bootstrap
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
}
|
|
```
|
|
|
|
You can detect if something has interfered with the ACL bootstrapping process by
|
|
checking the response code. A 200 response means that the bootstrap was a success, and
|
|
a 403 means that the cluster has already been bootstrapped, at which point you should
|
|
consider the cluster in a potentially compromised state.
|
|
|
|
The returned token will be a management token which can be used to further configure the
|
|
ACL system. Please check the
|
|
[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details.
|
|
|
|
## Create ACL Token
|
|
|
|
This endpoint makes a new ACL token.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------- | ------------------ |
|
|
| `PUT` | `/acl/create` | `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` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `ID` `(string: "")` - Specifies the ID of the ACL. If not provided, a UUID is
|
|
generated.
|
|
|
|
- `Name` `(string: "")` - Specifies a human-friendly name for the ACL token.
|
|
|
|
- `Type` `(string: "client")` - Specifies the type of ACL token. Valid values
|
|
are: `client` and `management`.
|
|
|
|
- `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the
|
|
`Rules` property is documented in the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Name": "my-app-token",
|
|
"Type": "client",
|
|
"Rules": ""
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/create
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
}
|
|
```
|
|
|
|
## Update ACL Token
|
|
|
|
This endpoint is used to modify the policy for a given ACL token. Instead of
|
|
generating a new token ID, the `ID` field must be provided.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------- | ------------------ |
|
|
| `PUT` | `/acl/update` | `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` | `management` |
|
|
|
|
### Parameters
|
|
|
|
The parameters are the same as the _create_ endpoint, except the `ID` field is
|
|
required.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
|
"Name": "my-app-token-updated",
|
|
"Type": "client",
|
|
"Rules": "# New Rules"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/update
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
}
|
|
```
|
|
|
|
## Delete ACL Token
|
|
|
|
This endpoint deletes an ACL token with the given ID.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------- | ------------------ |
|
|
| `PUT` | `/acl/destroy/:uuid` | `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` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
|
|
destroy. This is required and is specified as part of the URL path.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
http://127.0.0.1:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
true
|
|
```
|
|
|
|
## Read ACL Token
|
|
|
|
This endpoint reads an ACL token with the given ID.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------------- | ------------------ |
|
|
| `GET` | `/acl/info/:uuid` | `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` | `none` |
|
|
|
|
Note: No ACL is required because the ACL is specified in the URL path.
|
|
|
|
### Parameters
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
|
|
read. This is required and is specified as part of the URL path.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"CreateIndex": 3,
|
|
"ModifyIndex": 3,
|
|
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
|
"Name": "Client Token",
|
|
"Type": "client",
|
|
"Rules": "..."
|
|
}
|
|
]
|
|
```
|
|
|
|
## Clone ACL Token
|
|
|
|
This endpoint clones an ACL and returns a new token `ID`. This allows a token to
|
|
serve as a template for others, making it simple to generate new tokens without
|
|
complex rule management.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------ | ------------------ |
|
|
| `PUT` | `/acl/clone/:uuid` | `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` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
|
|
be cloned. This is required and is specified as part of the URL path.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
http://127.0.0.1:8500/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
}
|
|
```
|
|
|
|
## List ACLs
|
|
|
|
This endpoint lists all the active ACL tokens.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------- | ------------------ |
|
|
| `GET` | `/acl/list` | `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` | `management` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/acl/list
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"CreateIndex": 3,
|
|
"ModifyIndex": 3,
|
|
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
|
"Name": "Client Token",
|
|
"Type": "client",
|
|
"Rules": "..."
|
|
}
|
|
]
|
|
```
|
|
|
|
## Check ACL Replication
|
|
|
|
This endpoint returns the status of the ACL replication process in the
|
|
datacenter. This is intended to be used by operators, or by automation checking
|
|
the health of ACL replication.
|
|
|
|
Please check the [ACL Replication tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters)
|
|
for more details.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------ | ------------------ |
|
|
| `GET` | `/acl/replication` | `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` | `consistent` | `none` | `none` |
|
|
|
|
### Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
the datacenter of the agent being queried. This is specified as part of the
|
|
URL as a query parameter.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
http://127.0.0.1:8500/v1/acl/replication
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Enabled": true,
|
|
"Running": true,
|
|
"SourceDatacenter": "dc1",
|
|
"ReplicatedIndex": 1976,
|
|
"LastSuccess": "2016-08-05T06:28:58Z",
|
|
"LastError": "2016-08-05T06:28:28Z"
|
|
}
|
|
```
|
|
|
|
- `Enabled` reports whether ACL replication is enabled for the datacenter.
|
|
|
|
- `Running` reports whether the ACL replication process is running. The process
|
|
may take approximately 60 seconds to begin running after a leader election
|
|
occurs.
|
|
|
|
- `SourceDatacenter` is the authoritative ACL datacenter that ACLs are being
|
|
replicated from, and will match the
|
|
[`primary_datacenter`](/docs/agent/options#primary_datacenter) configuration.
|
|
|
|
- `ReplicatedIndex` is the last index that was successfully replicated. You can
|
|
compare this to the `X-Consul-Index` header returned by the
|
|
[`/v1/acl/list`](#list-acls) endpoint to determine if the replication process
|
|
has gotten all available ACLs. Replication runs as a background process
|
|
approximately every 30 seconds, and that local updates are rate limited to 100
|
|
updates/second, so so it may take several minutes to perform the initial sync
|
|
of a large set of ACLs. After the initial sync, replica lag should be on the
|
|
order of about 30 seconds.
|
|
|
|
- `LastSuccess` is the UTC time of the last successful sync operation. Since ACL
|
|
replication is done with a blocking query, this may not update for up to 5
|
|
minutes if there have been no ACL changes to replicate. A zero value of
|
|
"0001-01-01T00:00:00Z" will be present if no sync has been successful.
|
|
|
|
- `LastError` is the UTC time of the last error encountered during a sync
|
|
operation. If this time is later than `LastSuccess`, you can assume the
|
|
replication process is not in a good state. A zero value of
|
|
"0001-01-01T00:00:00Z" will be present if no sync has resulted in an error.
|