149 lines
5.4 KiB
Plaintext
149 lines
5.4 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: ACL Token Create'
|
|
description: |
|
|
The `consul acl token create` command creates new ACL tokens. Optional arguments can set TTL duration and attach new tokens to existing policies and roles.
|
|
---
|
|
|
|
# Consul ACL Token Create
|
|
|
|
Command: `consul acl token create`
|
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token](/consul/api-docs/acl/tokens#create-a-token)
|
|
|
|
This command creates new tokens. When creating a new token, policies may be linked using
|
|
either the `-policy-id` or the `-policy-name` options. When specifying policies by IDs you
|
|
may use a unique prefix of the UUID as a shortcut for specifying the entire UUID.
|
|
|
|
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
|
|
[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
| ACL Required |
|
|
| ------------ |
|
|
| `acl:write` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul acl token create [options] [args]`
|
|
|
|
#### Command Options
|
|
|
|
- `-accessor=<string>` - Create the token with this Accessor ID. It must be a UUID. If not
|
|
specified one will be auto-generated
|
|
|
|
- `-description=<string>` - A description of the token.
|
|
|
|
- `-expires-ttl=<duration>` - Duration of time this token should be valid for.
|
|
|
|
- `-local` - Create this as a datacenter local token.
|
|
|
|
- `-meta` - Indicates that token metadata such as the content hash and raft indices should be shown
|
|
for each entry.
|
|
|
|
- `-node-identity=<value>` - Name of a node identity to use for this role. May
|
|
be specified multiple times. Format is `NODENAME:DATACENTER`. Added in Consul
|
|
1.8.1.
|
|
|
|
- `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times.
|
|
|
|
- `-policy-name=<value>` - Name of a policy to use for this token. May be specified multiple times.
|
|
|
|
- `-role-id=<value>` - ID of a role to use for this token. May be specified multiple times.
|
|
|
|
- `-role-name=<value>` - Name of a role to use for this token. May be specified multiple times.
|
|
|
|
- `-service-identity=<value>` - Name of a service identity to use for this
|
|
token. May be specified multiple times. Format is the `SERVICENAME` or
|
|
`SERVICENAME:DATACENTER1,DATACENTER2,...`
|
|
|
|
- `-secret=<string>` - Create the token with this Secret ID. It must be a UUID. If not
|
|
specified one will be auto-generated.
|
|
**Note**: The SecretID is used to authorize operations against Consul and should
|
|
be generated from an appropriate cryptographic source.
|
|
|
|
- `-format={pretty|json}` - Command output format. The default value is `pretty`.
|
|
|
|
#### Enterprise Options
|
|
|
|
@include 'http_api_partition_options.mdx'
|
|
|
|
@include 'http_api_namespace_options.mdx'
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
@include 'http_api_options_server.mdx'
|
|
|
|
## Examples
|
|
|
|
The following examples describe how to create ACL tokens for common scenarios.
|
|
|
|
### Create a token with policy by name
|
|
|
|
The following example creates a token that includes a policy by its name.
|
|
|
|
```shell-session
|
|
$ consul acl token create -description "Read Nodes and Services" -policy-name node-services-read
|
|
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
|
|
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
|
|
Description: Read Nodes and Services
|
|
Local: false
|
|
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
|
|
Policies:
|
|
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
|
|
```
|
|
|
|
### Create a token for a service
|
|
|
|
The following example creates a token with the privileges necessary
|
|
for registering a service named `my-api`.
|
|
If `my-api` is in the service mesh, the token also has the privileges necessary
|
|
to register its associated sidecar proxy and must be provided to the proxy when
|
|
launched with [`consul connect envoy`](/consul/commands/connect/envoy#sidecar-proxy-with-acls-enabled).
|
|
|
|
```shell-session
|
|
$ consul acl token create -description 'my-api token' -service-identity 'my-api'
|
|
AccessorID: 0c083aca-6c15-f0cc-c4d9-30578db54cd9
|
|
SecretID: 930dafb6-5c08-040b-23fb-a368a95256f9
|
|
Description: api token
|
|
Local: false
|
|
Create Time: 2019-04-25 16:45:49.337687334 -0500 CDT
|
|
Service Identities:
|
|
my-api (Datacenters: all)
|
|
```
|
|
|
|
### Create a temporary and highly-privileged token
|
|
|
|
The following example creates a token with a lifetime of 15 minutes that
|
|
includes the built-in [`global-management` policy](/consul/docs/security/acl/acl-policies#global-management).
|
|
|
|
```shell-session
|
|
$ consul acl token create -description "Temp Super User" -policy-name global-management -expires-ttl '15m'
|
|
AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa
|
|
SecretID: ada7f751-f654-8872-7f93-498e799158b6
|
|
Description: Temp Super User
|
|
Local: false
|
|
Create Time: 2019-04-25 16:45:49.337687334 -0500 CDT
|
|
Expiration Time: 2019-04-25 17:00:49.337687334 -0500 CDT
|
|
Policies:
|
|
00000000-0000-0000-0000-000000000001 - global-management
|
|
```
|
|
|
|
### Create a local token with policy by ID
|
|
|
|
The following example creates a token that is only valid in this datacenter
|
|
and includes a policy by its UUID.
|
|
|
|
```shell-session
|
|
$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 -local
|
|
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
|
|
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
|
|
Description: Read Nodes and Services
|
|
Local: true
|
|
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
|
|
Policies:
|
|
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
|
|
```
|