From 8c5ae92fa78d068cce43facafb448af1abf227b4 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Mon, 18 Aug 2014 12:16:17 -0700 Subject: [PATCH] website: Documenting ACL endpoints --- website/source/docs/agent/http.html.markdown | 151 ++++++++++++++++++- 1 file changed, 150 insertions(+), 1 deletion(-) diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index 980dd807f..feff6bfb2 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -17,6 +17,7 @@ All endpoints fall into one of several categories: * catalog - Manages nodes and services * health - Manages health checks * session - Session manipulation +* acl - ACL creations and management * status - Consul system status * internal - Internal APIs. Purposely undocumented, subject to change. @@ -85,6 +86,14 @@ By default, the output of all HTTP API requests return minimized JSON with all whitespace removed. By adding "?pretty" to the HTTP request URL, formatted JSON will be returned. +## ACLs + +Several endpoints in Consul use or require ACL tokens to operate. An agent +can be configured to use a default token in requests using the `acl_token` +configuration option. However, the token can also be specified per-request +by using the "?token=" query parameter. This will take precedence over the +default token. + ## KV The KV endpoint is used to expose a simple key/value store. This can be used @@ -99,7 +108,8 @@ are all supported. It is important to note that each datacenter has its own K/V store, and that there is no replication between datacenters. By default the datacenter of the agent is queried, however the dc can be provided using the "?dc=" query parameter. If a client wants to write -to all Datacenters, one request per datacenter must be made. +to all Datacenters, one request per datacenter must be made. The KV endpoint +supports the use of ACL tokens. ### GET Method @@ -1039,6 +1049,145 @@ It returns a JSON body like this: This endpoint supports blocking queries and all consistency modes. +## ACL + +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 policy +* /v1/acl/update: Update the policy of a token +* /v1/acl/destroy/\: Destroys a given token +* /v1/acl/info/\: Queries the policy of a given token +* /v1/acl/clone/\: 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, +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. + +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. + +The create endpoint expects a JSON request body to be PUT. The request +body must look like: + + { + "Name": "my-app-token", + "Type": "client", + "Rules": "", + } + +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](). + +The return code is 200 on success, along with a body like: + + {"ID":"adf4238a-882b-9ddc-4a9d-5b6758e4159e"} + +This is used to provide the ID of the newly created ACL token. + +### /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 +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. + +The update endpoint expects a JSON request body to be PUT. The request +body must 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` default to being blank, and the `Type` defaults to "client". +The format of `Rules` is [documented here](). + +The return code is 200 on success. + +### /v1/acl/destroy/\ + +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 return code is 200 on success. + +### /v1/acl/info/\ + +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. + +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 session is not found, null is returned instead of a JSON list. + +### /v1/acl/clone/\ + +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 return code is 200 on success, along with a body like: + + {"ID":"adf4238a-882b-9ddc-4a9d-5b6758e4159e"} + +This is used to provide the ID of the newly created ACL token. + +### /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 +management token. + +It returns a JSON body like this: + + [ + { + "CreateIndex":3, + "ModifyIndex":3, + "ID":"8f246b77-f3e1-ff88-5b48-8ec93abf3e05", + "Name":"Client Token", + "Type":"client", + "Rules":"..." + }, + ... + ] + ## Status The Status endpoints are used to get information about the status