mirror of https://github.com/status-im/consul.git
Merge pull request #674 from ryanbreen/acl
Cleanups to docs/agent/http/acl
This commit is contained in:
Armon Dadgar
commit
7caedac17a
|
|
@ -3,16 +3,16 @@ layout: "docs"
|
|||
page_title: "ACLs (HTTP)"
|
||||
sidebar_current: "docs-agent-http-acl"
|
||||
description: >
|
||||
The ACL endpoints are used to create, update, destroy and query ACL tokens.
|
||||
The ACL endpoints are used to create, update, destroy, and query ACL tokens.
|
||||
---
|
||||
|
||||
# ACL HTTP Endpoint
|
||||
|
||||
The ACL endpoints are used to create, update, destroy and query ACL tokens.
|
||||
The ACL endpoints are used to create, update, destroy, and query ACL tokens.
|
||||
The following endpoints are supported:
|
||||
|
||||
* [`/v1/acl/create`](#acl_create): Creates a new token with policy
|
||||
* [`/v1/acl/update`](#acl_update): Update the policy of a token
|
||||
* [`/v1/acl/create`](#acl_create): Creates a new token with a given policy
|
||||
* [`/v1/acl/update`](#acl_update): Updates the policy of a token
|
||||
* [`/v1/acl/destroy/<id>`](#acl_destroy): Destroys a given token
|
||||
* [`/v1/acl/info/<id>`](#acl_info): Queries the policy of a given token
|
||||
* [`/v1/acl/clone/<id>`](#acl_clone): Creates a new token by cloning an existing token
|
||||
|
|
@ -20,21 +20,27 @@ The following endpoints are supported:
|
|||
|
||||
### <a name="acl_create"></a> /v1/acl/create
|
||||
|
||||
The create endpoint is used to make a new token. A token has a name,
|
||||
type, and a set of ACL rules. The name is opaque to Consul, and type
|
||||
is either "client" or "management". A management token is effectively
|
||||
like a root user, and has the ability to perform any action including
|
||||
creating, modifying, and deleting ACLs. A client token can only perform
|
||||
actions as permitted by the rules associated, and may never manage ACLs.
|
||||
This means the request to this endpoint must be made with a management
|
||||
token.
|
||||
The `create` endpoint is used to make a new token. A token has a name,
|
||||
a type, and a set of ACL rules.
|
||||
|
||||
The `Name` property is opaque to Consul. To aid human operators, it should
|
||||
be a meaningful indicator of the ACL's purpose.
|
||||
|
||||
Type is either `client` or `management`. A management token is comparable
|
||||
to a root user and has the ability to perform any action including
|
||||
creating, modifying, and deleting ACLs.
|
||||
|
||||
By constrast, a client token can only perform actions as permitted by the
|
||||
rules associated. Client tokens can never manage ACLs. Given this limitation,
|
||||
only a management token can be used to make requests to the `/v1/acl/create`
|
||||
endpoint.
|
||||
|
||||
In any Consul cluster, only a single datacenter is authoritative for ACLs, so
|
||||
all requests are automatically routed to that datacenter regardless
|
||||
of the agent that the request is made to.
|
||||
of the agent to which the request is made.
|
||||
|
||||
The create endpoint expects a JSON request body to be PUT. The request
|
||||
body must look like:
|
||||
The create endpoint supports a JSON request body with the PUT. The request
|
||||
body may take the form:
|
||||
|
||||
```javascript
|
||||
{
|
||||
|
|
@ -44,12 +50,13 @@ body must look like:
|
|||
}
|
||||
```
|
||||
|
||||
None of the fields are mandatory, and in fact no body needs to be PUT
|
||||
if the defaults are to be used. The `Name` and `Rules` default to being
|
||||
blank, and the `Type` defaults to "client". The format of `Rules` is
|
||||
[documented here](/docs/internals/acl.html).
|
||||
None of the fields are mandatory. In fact, no body needs to be PUT if the
|
||||
defaults are to be used. The `Name` and `Rules` fields default to being
|
||||
blank, and the `Type` defaults to "client".
|
||||
|
||||
The return code is 200 on success, along with a body like:
|
||||
The format of the `Rules` property is [documented here](/docs/internals/acl.html).
|
||||
|
||||
A successful response body will return the `ID` of the newly created ACL, like so:
|
||||
|
||||
```javascript
|
||||
{
|
||||
|
|
@ -57,22 +64,20 @@ The return code is 200 on success, along with a body like:
|
|||
}
|
||||
```
|
||||
|
||||
This is used to provide the ID of the newly created ACL token.
|
||||
|
||||
### <a name="acl_update"></a> /v1/acl/update
|
||||
|
||||
The update endpoint is used to modify the policy for a given
|
||||
ACL token. It is very similar to the create endpoint, however
|
||||
instead of generating a new token ID, the `ID` field must be
|
||||
provided. Requests to this endpoint must be made with a management
|
||||
The update endpoint is used to modify the policy for a given ACL token. It
|
||||
is very similar to the create endpoint; however, instead of generating a new
|
||||
token ID, the `ID` field must be provided. As with [`/v1/acl/create`](#acl_create),
|
||||
requests to this endpoint must be made with a management
|
||||
token.
|
||||
|
||||
In any Consul cluster, only a single datacenter is authoritative for ACLs, so
|
||||
all requests are automatically routed to that datacenter regardless
|
||||
of the agent that the request is made to.
|
||||
of the agent to which the request is made.
|
||||
|
||||
The update endpoint expects a JSON request body to be PUT. The request
|
||||
body must look like:
|
||||
The update endpoint requires a JSON request body to the PUT. The request
|
||||
body may look like:
|
||||
|
||||
```javascript
|
||||
{
|
||||
|
|
@ -83,26 +88,22 @@ body must look like:
|
|||
}
|
||||
```
|
||||
|
||||
Only the `ID` field is mandatory, the other fields provide defaults.
|
||||
The `Name` and `Rules` default to being blank, and the `Type` defaults to "client".
|
||||
Only the `ID` field is mandatory. The other fields provide defaults: the
|
||||
`Name` and `Rules` fields default to being blank, and `Type` defaults to "client".
|
||||
The format of `Rules` is [documented here](/docs/internals/acl.html).
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
### <a name="acl_destroy"></a> /v1/acl/destroy/\<id\>
|
||||
|
||||
The destroy endpoint is hit with a PUT and destroys the given ACL token.
|
||||
The request is automatically routed to the authoritative ACL datacenter.
|
||||
The token being destroyed must be provided after the slash, and requests
|
||||
to the endpoint must be made with a management token.
|
||||
The destroy endpoint must be hit with a PUT. This endpoint destroys the ACL
|
||||
token identified by the `id` portion of the path.
|
||||
|
||||
The return code is 200 on success.
|
||||
The request is automatically routed to the authoritative ACL datacenter.
|
||||
Requests to this endpoint must be made with a management token.
|
||||
|
||||
### <a name="acl_info"></a> /v1/acl/info/\<id\>
|
||||
|
||||
This endpoint is hit with a GET and returns the token information
|
||||
by ID. All requests are routed to the authoritative ACL datacenter
|
||||
The token being queried must be provided after the slash.
|
||||
The info endpoint must be hit with a GET. This endpoint returns the ACL
|
||||
token information identified by the `id` portion of the path.
|
||||
|
||||
It returns a JSON body like this:
|
||||
|
||||
|
|
@ -119,17 +120,20 @@ It returns a JSON body like this:
|
|||
]
|
||||
```
|
||||
|
||||
If the session is not found, null is returned instead of a JSON list.
|
||||
If the ACL is not found, null is returned instead of a JSON list.
|
||||
|
||||
### <a name="acl_clone"></a> /v1/acl/clone/\<id\>
|
||||
|
||||
The clone endpoint is hit with a PUT and returns a token ID that
|
||||
is cloned from an existing token. This allows a token to serve
|
||||
as a template for others, making it simple to generate new tokens
|
||||
without complex rule management. The source token must be provided
|
||||
after the slash. Requests to this endpoint require a management token.
|
||||
The clone endpoint must be hit with a PUT. It clones the ACL identified
|
||||
by the `id` portion of the path 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.
|
||||
|
||||
The return code is 200 on success, along with a body like:
|
||||
The request is automatically routed to the authoritative ACL datacenter.
|
||||
Requests to this endpoint must be made with a management token.
|
||||
|
||||
As with `create`, a successful response body will return the `ID` of the newly
|
||||
created ACL, like so:
|
||||
|
||||
```javascript
|
||||
{
|
||||
|
|
@ -137,12 +141,10 @@ The return code is 200 on success, along with a body like:
|
|||
}
|
||||
```
|
||||
|
||||
This is used to provide the ID of the newly created ACL token.
|
||||
|
||||
### <a name="acl_list"></a> /v1/acl/list
|
||||
|
||||
The list endpoint is hit with a GET and lists all the active
|
||||
ACL tokens. This is a privileged endpoint, and requires a
|
||||
The list endpoint must be hit with a GET. It lists all the active
|
||||
ACL tokens. This is a privileged endpoint and requires a
|
||||
management token.
|
||||
|
||||
It returns a JSON body like this:
|
||||
|
|
|
|||
Loading…
Reference in New Issue