Armon Dadgar 0473b40df2 website: Document new ACL upsert behavior

2015-05-05 19:25:27 -07:00

5.3 KiB

Raw Blame History

layout	page_title	sidebar_current	description
docs	ACLs (HTTP)	docs-agent-http-acl	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 following endpoints are supported:

/v1/acl/create: Creates a new token with a given policy
/v1/acl/update: Updates the policy of a token
/v1/acl/destroy/<id>: Destroys a given token
/v1/acl/info/<id>: Queries the policy of a given token
/v1/acl/clone/<id>: Creates a new token by cloning an existing token
/v1/acl/list: Lists all the active tokens

/v1/acl/create

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 to which the request is made.

The create endpoint supports a JSON request body with the PUT. The request body may take the form:

{
  "Name": "my-app-token",
  "Type": "client",
  "Rules": ""
}

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 ID field may be provided, and if omitted a random UUID will be generated. The security of the ACL system depends on the difficulty of guessing the token. Tokens should not be generated in a predictable manner or with too little entropy.

The format of the Rules property is documented here.

A successful response body will return the ID of the newly created ACL, like so:

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}

/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. As with /v1/acl/create, requests to this endpoint must be made with a management token. If the ID does not exist, the ACL will be upserted. In this sense, create and update are identical.

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 to which the request is made.

The update endpoint requires a JSON request body to the PUT. The request body may look like:

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
  "Name": "my-app-token-updated",
  "Type": "client",
  "Rules": "# New Rules",
}

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.

/v1/acl/destroy/<id>

The destroy endpoint must be hit with a PUT. This endpoint destroys the ACL token identified by the id portion of the path.

The request is automatically routed to the authoritative ACL datacenter. Requests to this endpoint must be made with a management token.

/v1/acl/info/<id>

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:

[
  {
    "CreateIndex": 3,
    "ModifyIndex": 3,
    "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
    "Name": "Client Token",
    "Type": "client",
    "Rules": "..."
  }
]

If the ACL is not found, null is returned instead of a JSON list.

/v1/acl/clone/<id>

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.