luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/content/api-docs/acl/legacy.mdx

300 lines
8.1 KiB
Plaintext
Raw Normal View History

Update API docs
2017-04-04 16:33:22 +00:00
---
layout: api
Adds documentation for the new ACL APIs (#4851) * Update the ACL API docs * Add a CreateTime to the anon token Also require acl:read permissions at least to perform rule translation. Don’t want someone DoSing the system with an open endpoint that actually does a bit of work. * Fix one place where I was referring to id instead of AccessorID * Add godocs for the API package additions. * Minor updates: removed some extra commas and updated the acl intro paragraph * minor tweaks * Updated the language to be clearer * Updated the language to be clearer for policy page * I was also confused by that! Your updates are much clearer. Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Sounds much better. Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Updated sidebar layout and deprecated warning
2018-10-31 22:11:51 +00:00
page_title: Legacy ACLs - HTTP API
intro and api navigation converted
2020-04-07 18:55:19 +00:00
description: >-
docs: add notice that legacy ACLs have been removed. Add changelog Also remove a metric that is no longer emitted that was missed in a previous step.
2021-10-05 18:28:51 +00:00
The legacy /acl endpoints to create, update, destroy, and query legacy ACL tokens in
intro and api navigation converted
2020-04-07 18:55:19 +00:00
Consul.
Update API docs
2017-04-04 16:33:22 +00:00
---
intro and api navigation converted
2020-04-07 18:55:19 +00:00
# ACL HTTP API
docs: add notice that legacy ACLs have been removed. Add changelog Also remove a metric that is no longer emitted that was missed in a previous step.
2021-10-05 18:28:51 +00:00
-> **The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0.** It's _strongly_
recommended you do not build anything using the legacy system and use
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
the new ACL [Token](/api-docs/acl/tokens) and [Policy](/api-docs/acl/policies) APIs instead.
Adds a new /v1/acl/bootstrap API (#3349)
2017-08-03 00:05:18 +00:00
docs: add notice that legacy ACLs have been removed. Add changelog Also remove a metric that is no longer emitted that was missed in a previous step.
2021-10-05 18:28:51 +00:00
The legacy `/acl` endpoints to create, update, destroy, and query legacy ACL tokens in Consul.
docs: add documentation for all secure acl introduction work (#5640)
2019-05-01 21:11:23 +00:00
Refactor api-docs links to learn (#8488)
2020-08-17 16:20:02 +00:00
For more information about ACLs, please check the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
Adds a new /v1/acl/bootstrap API (#3349)
2017-08-03 00:05:18 +00:00
Update API docs
2017-04-04 16:33:22 +00:00
## Create ACL Token
This endpoint makes a new ACL token.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------- | ------------------ |
| `PUT` | `/acl/create` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
website: content updates for developer (#14419) Co-authored-by: Ashlee Boyer <ashlee.boyer@hashicorp.com> Co-authored-by: Ashlee M Boyer <43934258+ashleemboyer@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: HashiBot <62622282+hashibot-web@users.noreply.github.com> Co-authored-by: Kevin Wang <kwangsan@gmail.com>
2022-09-14 22:45:42 +00:00
[required ACLs](/api-docs#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
Update API docs
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
docs: Avoid redirects by pointing links to new URLs Avoid HTTP redirects for internal site links by updating old URLs to point to the new location for the target content.
2022-01-10 23:36:16 +00:00
`Rules` property is detailed in the [ACL Rule documentation](/docs/security/acl/acl-rules).
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Payload
```json
{
"Name": "my-app-token",
"Type": "client",
"Rules": ""
}
```
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/acl/create
Update API docs
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.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------- | ------------------ |
| `PUT` | `/acl/update` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
website: content updates for developer (#14419) Co-authored-by: Ashlee Boyer <ashlee.boyer@hashicorp.com> Co-authored-by: Ashlee M Boyer <43934258+ashleemboyer@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: HashiBot <62622282+hashibot-web@users.noreply.github.com> Co-authored-by: Kevin Wang <kwangsan@gmail.com>
2022-09-14 22:45:42 +00:00
[required ACLs](/api-docs#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
Update API docs
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",
initial
2020-04-06 20:27:35 +00:00
"Rules": "# New Rules"
Update API docs
2017-04-04 16:33:22 +00:00
}
```
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload.json \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/acl/update
Update API docs
2017-04-04 16:33:22 +00:00
```
docs: add return info for update and delete acl-token apis (#4584) * Update Token API returns the ID of the token updated. * Delete Token API returns a raw text which is true for successful deletions
2018-10-24 15:11:51 +00:00
### Sample Response
initial
2020-04-06 20:27:35 +00:00
docs: add return info for update and delete acl-token apis (#4584) * Update Token API returns the ID of the token updated. * Delete Token API returns a raw text which is true for successful deletions
2018-10-24 15:11:51 +00:00
```json
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
Update API docs
2017-04-04 16:33:22 +00:00
## Delete ACL Token
This endpoint deletes an ACL token with the given ID.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | -------------------- | ------------------ |
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
Adds documentation for the new ACL APIs (#4851) * Update the ACL API docs * Add a CreateTime to the anon token Also require acl:read permissions at least to perform rule translation. Don’t want someone DoSing the system with an open endpoint that actually does a bit of work. * Fix one place where I was referring to id instead of AccessorID * Add godocs for the API package additions. * Minor updates: removed some extra commas and updated the acl intro paragraph * minor tweaks * Updated the language to be clearer * Updated the language to be clearer for policy page * I was also confused by that! Your updates are much clearer. Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Sounds much better. Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Updated sidebar layout and deprecated warning
2018-10-31 22:11:51 +00:00
Even though the return type is application/json, the value is either true or
false, indicating whether the delete succeeded.
docs: add return info for update and delete acl-token apis (#4584) * Update Token API returns the ID of the token updated. * Delete Token API returns a raw text which is true for successful deletions
2018-10-24 15:11:51 +00:00
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
website: content updates for developer (#14419) Co-authored-by: Ashlee Boyer <ashlee.boyer@hashicorp.com> Co-authored-by: Ashlee M Boyer <43934258+ashleemboyer@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: HashiBot <62622282+hashibot-web@users.noreply.github.com> Co-authored-by: Kevin Wang <kwangsan@gmail.com>
2022-09-14 22:45:42 +00:00
[required ACLs](/api-docs#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
Update API docs
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
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
Update API docs
2017-04-04 16:33:22 +00:00
```
docs: add return info for update and delete acl-token apis (#4584) * Update Token API returns the ID of the token updated. * Delete Token API returns a raw text which is true for successful deletions
2018-10-24 15:11:51 +00:00
### Sample Response
initial
2020-04-06 20:27:35 +00:00
docs: add return info for update and delete acl-token apis (#4584) * Update Token API returns the ID of the token updated. * Delete Token API returns a raw text which is true for successful deletions
2018-10-24 15:11:51 +00:00
```json
true
```
Update API docs
2017-04-04 16:33:22 +00:00
## Read ACL Token
This endpoint reads an ACL token with the given ID.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `GET` | `/acl/info/:uuid` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
website: content updates for developer (#14419) Co-authored-by: Ashlee Boyer <ashlee.boyer@hashicorp.com> Co-authored-by: Ashlee M Boyer <43934258+ashleemboyer@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: HashiBot <62622282+hashibot-web@users.noreply.github.com> Co-authored-by: Kevin Wang <kwangsan@gmail.com>
2022-09-14 22:45:42 +00:00
[required ACLs](/api-docs#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `none` |
Update API docs
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
Fixup ACL docs
2017-05-07 00:21:13 +00:00
read. This is required and is specified as part of the URL path.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
Update API docs
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.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------ | ------------------ |
| `PUT` | `/acl/clone/:uuid` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
website: content updates for developer (#14419) Co-authored-by: Ashlee Boyer <ashlee.boyer@hashicorp.com> Co-authored-by: Ashlee M Boyer <43934258+ashleemboyer@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: HashiBot <62622282+hashibot-web@users.noreply.github.com> Co-authored-by: Kevin Wang <kwangsan@gmail.com>
2022-09-14 22:45:42 +00:00
[required ACLs](/api-docs#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `management` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
Fix bad copy/paste (#3139) Description was probably originally copied from the "delete" request.
2017-06-10 21:46:25 +00:00
be cloned. This is required and is specified as part of the URL path.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
Update API docs
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.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ----------- | ------------------ |
| `GET` | `/acl/list` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
website: redirect /api to /api-docs (#12660)
2022-03-30 21:16:26 +00:00
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
website: content updates for developer (#14419) Co-authored-by: Ashlee Boyer <ashlee.boyer@hashicorp.com> Co-authored-by: Ashlee M Boyer <43934258+ashleemboyer@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> Co-authored-by: HashiBot <62622282+hashibot-web@users.noreply.github.com> Co-authored-by: Kevin Wang <kwangsan@gmail.com>
2022-09-14 22:45:42 +00:00
[required ACLs](/api-docs#authentication).
Update API docs
2017-04-04 16:33:22 +00:00
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `management` |
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
Update API docs
2017-04-04 16:33:22 +00:00
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/acl/list
Update API docs
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": "..."
}
]
docs: add documentation for all secure acl introduction work (#5640)
2019-05-01 21:11:23 +00:00
```
[docs] ACL Legacy Docs (#5625) * updating the acl legacy doc * Updatine ACLs based on PR #5002
2019-05-07 19:27:30 +00:00
## Check ACL Replication
docs: Avoid redirects by pointing links to new URLs Avoid HTTP redirects for internal site links by updating old URLs to point to the new location for the target content.
2022-01-10 23:36:16 +00:00
The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api-docs/acl#check-acl-replication) to learn more about this endpoint.