open-nomad/website/content/api-docs/acl/tokens.mdx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

506 lines
15 KiB
Plaintext
Raw Normal View History

---
layout: api
page_title: ACL Tokens - HTTP API
2020-02-06 23:45:31 +00:00
description: The /acl/token/ endpoints are used to configure and manage ACL tokens.
---
# ACL Tokens HTTP API
The `/acl/bootstrap`, `/acl/tokens`, and `/acl/token/` endpoints are used to manage ACL tokens.
For more details about ACLs, please see the [ACL Guide](/nomad/tutorials/access-control).
## Bootstrap Token
This endpoint is used to bootstrap the ACL system and provide the initial management token.
An operator created token can be provided in the body of the request to bootstrap the cluster
if required. If no header is provided the cluster will return a generated management token.
The provided token should be presented in a UUID format.
This request is always forwarded to the authoritative region. It can only be invoked once
until a [bootstrap reset](/nomad/tutorials/access-control/access-control-bootstrap#re-bootstrap-acl-system) is performed.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ---------------- | ------------------ |
| `POST` | `/acl/bootstrap` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `none` |
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
--request POST \
https://localhost:4646/v1/acl/bootstrap
```
### Sample Response
```json
{
2020-02-06 23:45:31 +00:00
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
"SecretID": "3f4a0fcd-7c42-773c-25db-2d31ba0c05fe",
"Name": "Bootstrap Token",
"Type": "management",
"Policies": null,
"Global": true,
"CreateTime": "2017-08-23T22:47:14.695408057Z",
"CreateIndex": 7,
"ModifyIndex": 7
}
```
### Sample Operator Payload
```json
{
"BootstrapSecret": "2b778dd9-f5f1-6f29-b4b4-9a5fa948757a"
}
```
### Sample Request With Operator Token
```shell-session
$ curl \
--request POST \
--data @root-token.json \
https://localhost:4646/v1/acl/bootstrap
```
### Sample Response With Operator Token
```json
{
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
"SecretID": "2b778dd9-f5f1-6f29-b4b4-9a5fa948757a",
"Name": "Bootstrap Token",
"Type": "management",
"Policies": null,
"Global": true,
"CreateTime": "2017-08-23T22:47:14.695408057Z",
"CreateIndex": 7,
"ModifyIndex": 7
}
```
## List Tokens
This endpoint lists all ACL tokens. This lists the local tokens and the global
tokens which have been replicated to the region, and may lag behind the authoritative region.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ------------- | ------------------ |
| `GET` | `/acl/tokens` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `management` |
### Parameters
- `global` `(bool: false)` - If true, only return ACL tokens that are
replicated globally to all regions.
- `prefix` `(string: "")` - Specifies a string to filter ACL tokens based on an
accessor ID prefix. Because the value is decoded to bytes, the prefix must
have an even number of hexadecimal characters (0-9a-f). This is specified as
a query string parameter.
- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
parameter accepts a string which identifies the next expected ACL token. This
value can be obtained from the `X-Nomad-NextToken` header from the previous
response.
- `per_page` `(int: 0)` - Specifies a maximum number of ACL tokens to return
for this request. If omitted, the response is not paginated. The value of the
`X-Nomad-NextToken` header of the last response can be used as the
`next_token` of the next request to fetch additional pages.
- `filter` `(string: "")` - Specifies the [expression](/nomad/api-docs#filtering)
used to filter the results. Consider using pagination or a query parameter to
reduce resource used to serve the request.
- `reverse` `(bool: false)` - Specifies the list of returned ACL tokens should
be sorted in the reverse order. By default ACL tokens are returned sorted in
chronological order (older ACL tokens first), or in lexicographical order by
their ID if the `prefix` or `global` query parameters are used.
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
https://localhost:4646/v1/acl/tokens
```
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
--request POST \
https://localhost:4646/v1/acl/tokens?prefix=3da2ed52
```
### Sample Response
```json
[
{
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
"Name": "Bootstrap Token",
"Type": "management",
"Policies": null,
"Global": true,
"CreateTime": "2017-08-23T22:47:14.695408057Z",
"CreateIndex": 7,
"ModifyIndex": 7
}
]
```
## Create Token
This endpoint creates an ACL Token. If the token is a global token, the request
is forwarded to the authoritative region.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ------------ | ------------------ |
| `POST` | `/acl/token` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `Name` `(string: <optional>)` - Specifies the human-readable name of the token.
- `Type` `(string: <required>)` - Specifies the type of token. Must be either
`client` or `management`.
- `Policies` `(array<string>: <required>)` - Must be null or blank for
`management` type tokens, otherwise must specify at least one policy for
`client` type tokens.
- `Global` `(bool: <optional>)` - If true, indicates this token should be
replicated globally to all regions. Otherwise, this token is created local to
the target region.
- `ExpirationTime` `(time: "")` - If set, this represents the point after which
a token should be considered revoked and is eligible for destruction. The
default unset value represents NO expiration.
- `ExpirationTTL` `(duration: 0s)` - This is a convenience field and if set will
initialize the `ExpirationTime` field to a value of `CreateTime` +
`ExpirationTTL`. This value must be between the [`token_min_expiration_ttl`][]
and [`token_max_expiration_ttl`][] ACL configuration parameters.
### Sample Payload
```json
{
2020-02-06 23:45:31 +00:00
"Name": "Readonly token",
"Type": "client",
"Policies": ["readonly"],
"Global": false
}
```
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://localhost:4646/v1/acl/token
```
### Sample Response
```json
{
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
"Name": "Readonly token",
"Type": "client",
2020-02-06 23:45:31 +00:00
"Policies": ["readonly"],
"Global": false,
"CreateTime": "2017-08-23T23:25:41.429154233Z",
"CreateIndex": 52,
"ModifyIndex": 52
}
```
## Update Token
This endpoint updates an existing ACL Token. If the token is a global token, the request
is forwarded to the authoritative region. Note that a token cannot be switched from global
to local or visa versa.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ------------------------- | ------------------ |
| `POST` | `/acl/token/:accessor_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `AccessorID` `(string: <required>)` - Specifies the token (by accessor) that is being updated. Must match payload body and request path.
- `Name` `(string: <optional>)` - Specifies the human readable name of the token.
- `Type` `(string: <required>)` - Specifies the type of token. Must be either `client` or `management`.
- `Policies` `(array<string>: <required>)` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens.
### Sample Payload
```json
{
2020-02-06 23:45:31 +00:00
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
"Name": "Read-write token",
"Type": "client",
"Policies": ["readwrite"]
}
```
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
```
### Sample Response
```json
{
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
"Name": "Read-write token",
"Type": "client",
2020-02-06 23:45:31 +00:00
"Policies": ["readwrite"],
"Global": false,
"CreateTime": "2017-08-23T23:25:41.429154233Z",
"CreateIndex": 52,
"ModifyIndex": 64
}
```
## Read Token
This endpoint reads an ACL token with the given accessor. If the token is a global token
which has been replicated to the region it may lag behind the authoritative region.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ------------------------- | ------------------ |
| `GET` | `/acl/token/:accessor_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------------------------------- |
2017-09-27 20:42:56 +00:00
| `YES` | `all` | `management` or a SecretID matching the AccessorID |
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
```
### Sample Response
2017-10-13 20:10:26 +00:00
```json
{
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
"Name": "Read-write token",
"Type": "client",
2020-02-06 23:45:31 +00:00
"Policies": ["readwrite"],
2017-10-13 20:10:26 +00:00
"Global": false,
"CreateTime": "2017-08-23T23:25:41.429154233Z",
"CreateIndex": 52,
"ModifyIndex": 64
}
```
## Read Self Token
This endpoint reads the ACL token given by the passed SecretID. If the token is a global token
which has been replicated to the region it may lag behind the authoritative region.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `GET` | `/acl/token/self` | `application/json` |
2017-10-13 20:10:26 +00:00
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
2017-10-13 20:10:26 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------- |
2017-10-13 20:10:26 +00:00
| `YES` | `all` | Any valid ACL token |
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
2017-10-13 20:10:26 +00:00
$ curl \
2017-10-16 18:29:08 +00:00
--header "X-Nomad-Token: 8176afd3-772d-0b71-8f85-7fa5d903e9d4" \
https://localhost:4646/v1/acl/token/self
2017-10-13 20:10:26 +00:00
```
### Sample Response
```json
{
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
"Name": "Read-write token",
"Type": "client",
2020-02-06 23:45:31 +00:00
"Policies": ["readwrite"],
"Global": false,
"CreateTime": "2017-08-23T23:25:41.429154233Z",
"CreateIndex": 52,
"ModifyIndex": 64
}
```
## Delete Token
This endpoint deletes the ACL token by accessor. This request is forwarded to the
authoritative region for global tokens.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| -------- | ------------------------- | -------------- |
| `DELETE` | `/acl/token/:accessor_id` | `(empty body)` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `accessor_id` `(string: <required>)` - Specifies the ACL token accessor ID.
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
--request DELETE \
https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
```
## Upsert One-Time Token
This endpoint creates a one-time token for the ACL token provided in the
`X-Nomad-Token` header. Returns 403 if the token header is not set.
| Method | Path | Produces |
| ------ | -------------------- | ------------------ |
| `POST` | `/acl/token/onetime` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `any` |
### Sample Request
```shell-session
$ curl \
--request POST \
-H "X-Nomad-Token: aa534e09-6a07-0a45-2295-a7f77063d429" \
https://localhost:4646/v1/acl/token/onetime
```
### Sample Response
```json
{
"Index": 15,
"OneTimeToken": {
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
"CreateIndex": 7,
"ExpiresAt": "2017-08-23T22:47:14.695408057Z",
"ModifyIndex": 7,
"OneTimeSecretID": "3f4a0fcd-7c42-773c-25db-2d31ba0c05fe"
}
}
```
## Exchange One-Time Token
This endpoint exchanges a one-time token for the original ACL token used to
create it.
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `POST` | `/acl/token/onetime/exchange` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `any` |
### Sample Request
```shell-session
$ curl \
--request POST \
-d '{ "OneTimeSecretID": "aa534e09-6a07-0a45-2295-a7f77063d429" } \
https://localhost:4646/v1/acl/token/onetime/exchange
```
### Sample Response
```json
{
"Index": 17,
"Token": {
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
"CreateIndex": 7,
"CreateTime": "2017-08-23T22:47:14.695408057Z",
"Global": true,
"Hash": "UhZESkSFGFfX7eBgq5Uwph30OctbUbpe8+dlH2i4whA=",
"ModifyIndex": 7,
"Name": "Developer token",
"Policies": ["developer"],
"SecretID": "3f4a0fcd-7c42-773c-25db-2d31ba0c05fe",
"Type": "client"
}
}
```
[`token_min_expiration_ttl`]: /nomad/docs/configuration/acl#token_min_expiration_ttl
[`token_max_expiration_ttl`]: /nomad/docs/configuration/acl#token_max_expiration_ttl