open-consul/website/content/api-docs/acl/legacy.mdx

301 lines
7.9 KiB
Plaintext
Raw Normal View History

2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Legacy ACLs - HTTP API
sidebar_title: Legacy Tokens
2020-04-07 18:55:19 +00:00
description: >-
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in
Consul.
2017-04-04 16:33:22 +00:00
---
2020-04-07 18:55:19 +00:00
# ACL HTTP API
-> **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
2020-04-09 23:46:54 +00:00
the new ACL [Token](/api/acl/tokens) and [Policy](/api/acl/policies) APIs instead.
The `/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).
2017-04-04 16:33:22 +00:00
## Create ACL Token
This endpoint makes a new ACL token.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------- | ------------------ |
| `PUT` | `/acl/create` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
2017-04-04 16:33:22 +00:00
### 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
2020-04-09 23:46:54 +00:00
`Rules` property is detailed in the [ACL Rule documentation](/docs/acl/acl-rules).
2017-04-04 16:33:22 +00:00
### Sample Payload
```json
{
"Name": "my-app-token",
"Type": "client",
"Rules": ""
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/create
2017-04-04 16:33:22 +00:00
```
### 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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------- | ------------------ |
| `PUT` | `/acl/update` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
2017-04-04 16:33:22 +00:00
### 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",
2020-04-06 20:27:35 +00:00
"Rules": "# New Rules"
2017-04-04 16:33:22 +00:00
}
```
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/update
2017-04-04 16:33:22 +00:00
```
### Sample Response
2020-04-06 20:27:35 +00:00
```json
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
2017-04-04 16:33:22 +00:00
## Delete ACL Token
This endpoint deletes an ACL token with the given ID.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | -------------------- | ------------------ |
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
2017-04-04 16:33:22 +00:00
Even though the return type is application/json, the value is either true or
false, indicating whether the delete succeeded.
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
2017-04-04 16:33:22 +00:00
### 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
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
2017-04-04 16:33:22 +00:00
```
### Sample Response
2020-04-06 20:27:35 +00:00
```json
true
```
2017-04-04 16:33:22 +00:00
## Read ACL Token
This endpoint reads an ACL token with the given ID.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `GET` | `/acl/info/:uuid` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `none` |
2017-04-04 16:33:22 +00:00
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
2017-05-07 00:21:13 +00:00
read. This is required and is specified as part of the URL path.
2017-04-04 16:33:22 +00:00
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
2017-04-04 16:33:22 +00:00
```
### 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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------ | ------------------ |
| `PUT` | `/acl/clone/:uuid` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
2017-04-04 16:33:22 +00:00
### 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.
2017-04-04 16:33:22 +00:00
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
## List ACLs
This endpoint lists all the active ACL tokens.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ----------- | ------------------ |
| `GET` | `/acl/list` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `management` |
2017-04-04 16:33:22 +00:00
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/acl/list
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"CreateIndex": 3,
"ModifyIndex": 3,
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "Client Token",
"Type": "client",
"Rules": "..."
}
]
```
## Check ACL Replication
2020-04-09 23:46:54 +00:00
The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api/acl/acl#check-acl-replication) to learn more about this endpoint.