mirror of https://github.com/status-im/consul.git
558 lines
19 KiB
Plaintext
558 lines
19 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Create tokens for agent registration
|
|
description: >-
|
|
Learn how to create ACL tokens that your Consul agents can present to Consul servers so that they can join the Consul cluster.
|
|
---
|
|
|
|
# Create a UI token
|
|
|
|
This topic describes how to create a token that you can use to view resources in the Consul UI.
|
|
|
|
## Introduction
|
|
|
|
To navigate the Consul UI when ACLs are enabled, log into the UI with a token linked to policies that grant an appropriate set of permissions. The UI is unable to display resources that the token does not have permission to access.
|
|
|
|
## Requirements
|
|
|
|
Core ACL functionality is available in all versions of Consul.
|
|
|
|
@include 'create-token-requirements.mdx'
|
|
|
|
## View catalog in Consul CE
|
|
|
|
This section describes how to create a token that grants read-only access to the catalog. This token allows users to view the catalog without the ability to make changes. To create the ACL token, define a policy, create the policy, and then link the policy to a token.
|
|
|
|
### Define a policy
|
|
|
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
|
|
|
The following example policy is defined in a file. The policy allows users that login with the token to view all services and nodes in the catalog.
|
|
|
|
<CodeTabs>
|
|
|
|
```hcl
|
|
service_prefix "" {
|
|
policy = "read"
|
|
}
|
|
node_prefix "" {
|
|
policy = "read"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"node_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
},
|
|
"service_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
### Register the policy with Consul
|
|
|
|
After defining the policies, you can register them with Consul using the command line or API endpoint.
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-catalog.hcl`.
|
|
|
|
```shell-session
|
|
$ consul acl policy create \
|
|
-name "ui-view-catalog" -rules @ui-view-catalog.hcl \
|
|
-description "Allow viewing the catalog"
|
|
```
|
|
|
|
Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in `view-catalog.hcl`. You must embed the policy rules in the `Rules` field of the request body.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Name": "ui-view-catalog",
|
|
"Description": "Allow viewing the catalog",
|
|
"Rules": "service_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\n"
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
### Link the policy to a token
|
|
|
|
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
|
|
|
The following command creates the ACL token linked to the policy `ui-view-catalog`.
|
|
|
|
```shell-session
|
|
$ consul acl token create \
|
|
-description "UI token to view the catalog" \
|
|
-policy-name "ui-view-catalog"
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
|
|
|
The following example creates an ACL token that you can use to login to the UI and view the catalog.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Policies": [
|
|
{
|
|
"Name": "ui-view-catalog"
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
## View catalog in Consul Enterprise
|
|
|
|
This section describes how to create a token that grants read-only access to the catalog. This token allows users to view the catalog without the ability to make changes. To create the ACL token, define a policy, create the policy, and then link the policy to a token.
|
|
|
|
### Define a policy
|
|
|
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
|
|
|
The following example policy is defined in a file. The following policy allows users that log in with the token to view services and nodes in the catalog in any partition and in any namespace. The `operator:read` permission is needed to list partitions. Without this permission, you can still view resources within a partition but cannot easily navigate to other partitions in the Consul UI.
|
|
|
|
<CodeTabs>
|
|
|
|
```hcl
|
|
operator = "read"
|
|
partition_prefix "" {
|
|
namespace_prefix "" {
|
|
service_prefix "" {
|
|
policy = "read"
|
|
}
|
|
node_prefix "" {
|
|
policy = "read"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"partition_prefix": {
|
|
"": [{
|
|
"namespace_prefix": {
|
|
"": [{
|
|
"node_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
},
|
|
"service_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
}
|
|
}]
|
|
}
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
### Register the policy with Consul
|
|
|
|
After defining the policies, you can register them with Consul using the command line or API endpoint.
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-catalog.hcl`.
|
|
|
|
You can specify an admin partition and namespace when registering policies in Consul Enterprise. Policies are only valid in the scopes specified during registration, but you can grant tokens registered in the `default` partition permission to access resources in a different partition than where the token was registered. Refer to the [admin partition documentation](/consul/docs/enterprise/admin-partitions#default-admin-partition) for additional information.
|
|
|
|
The following example registers the policy in the `default` partition and the `default` namespace because the policy grants cross-partition and cross-namespace access.
|
|
|
|
```shell-session
|
|
$ consul acl policy create -partition "default" -namespace "default" \
|
|
-name "ui-view-catalog" -rules @ui-view-catalog.hcl \
|
|
-description "Allow viewing the catalog"
|
|
```
|
|
|
|
Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in `view-catalog.hcl`. You must embed the policy rules in the `Rules` field of the request body.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Name": "ui-view-catalog",
|
|
"Description": "Allow viewing the catalog",
|
|
"Partition": "default",
|
|
"Namespace": "default",
|
|
"Rules": "partition_prefix \"\" {\n namespace_prefix \"\" {\n service_prefix \"\" {\n policy = \"read\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n"
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
### Link the policy to a token
|
|
|
|
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
|
|
|
```shell-session
|
|
$ consul acl token create -partition "default" -namespace "default" \
|
|
-description "UI token to view the catalog" \
|
|
-policy-name "ui-view-catalog"
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
|
|
|
You can specify an admin partition and namespace when registering policies in Consul Enterprise. Policies are only valid in the scopes specified during registration, but you can grant tokens registered in the `default` partition permission to access resources in a different partition than where the token was registered. Refer to the [admin partition documentation](/consul/docs/enterprise/admin-partitions#default-admin-partition) for additional information.
|
|
|
|
The following example registers the policy in the `default` partition and the `default` namespace because the policy grants cross-partition and cross-namespace access.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Policies": [
|
|
{
|
|
"Name": "ui-view-catalog"
|
|
}
|
|
],
|
|
"Partition": "default",
|
|
"Namespace": "default"
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
## View all resources in Consul CE
|
|
|
|
This section describes how to create a token with read-only access to all resources in the Consul UI. This token allows users to view any resources without the ability to make changes. To create the ACL token, define a policy, create the policy, and then link the policy to a token.
|
|
|
|
### Define a policy
|
|
|
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
|
|
|
The following example policy is defined in a file. The policy allows users that log in with the token to view all services and nodes in the catalog, all objects in the key/value store, all intentions, and all ACL resources. The `acl:read` permission does not allow viewing the token secret ids.
|
|
|
|
<CodeTabs>
|
|
|
|
```hcl
|
|
acl = "read"
|
|
key_prefix "" {
|
|
policy = "read"
|
|
}
|
|
node_prefix "" {
|
|
policy = "read"
|
|
}
|
|
operator = "read"
|
|
service_prefix "" {
|
|
policy = "read"
|
|
intentions = "read"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"acl": "read",
|
|
"key_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
},
|
|
"node_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
},
|
|
"operator": "read",
|
|
"service_prefix": {
|
|
"": [{
|
|
"intentions": "read",
|
|
"policy": "read"
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
### Register the policy with Consul
|
|
|
|
After defining the policies, you can register them with Consul using the command line or API endpoint.
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-all.hcl`.
|
|
|
|
```shell-session
|
|
$ consul acl policy create \
|
|
-name "ui-view-all" -rules @ui-view-all.hcl \
|
|
-description "Allow viewing all resources"
|
|
```
|
|
|
|
Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in `ui-view-all.hcl`. You must embed the policy rules in the `Rules` field of the request body.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Name": "ui-view-all",
|
|
"Description": "Allow viewing all resources",
|
|
"Rules": "acl = \"read\"\nkey_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\noperator = \"read\"\nservice_prefix \"\" {\n policy = \"read\"\n intentions = \"read\"\n}\n"
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
### Link the policy to a token
|
|
|
|
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
|
|
|
The following command creates the ACL token linked to the policy `ui-view-all`.
|
|
|
|
```shell-session
|
|
$ consul acl token create \
|
|
-description "UI token to view all resources" \
|
|
-policy-name "ui-view-all"
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
|
|
|
The following example creates an ACL token that you can use to login to the UI and view the catalog.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Policies": [
|
|
{
|
|
"Name": "ui-view-all"
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
## View all resources in Consul Enterprise
|
|
|
|
This section describes how to create a token with read-only access to all resources in the Consul UI. This token allows users to view any resources without the ability to make changes. To create the ACL token, define a policy, create the policy, and then link the policy to a token.
|
|
|
|
### Define a policy
|
|
|
|
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
|
|
|
|
The following example policy is defined in a file. The policy allows users that log in with the token to view all services and nodes in the catalog, all objects in the key-value store, all intentions, and all ACL resources in any namespace and any partition. The `acl:read` permission does not allow viewing the token secret ids.
|
|
|
|
<CodeTabs>
|
|
|
|
```hcl
|
|
operator = "read"
|
|
partition_prefix "" {
|
|
namespace_prefix "" {
|
|
acl = "read"
|
|
key_prefix "" {
|
|
policy = "read"
|
|
}
|
|
node_prefix "" {
|
|
policy = "read"
|
|
}
|
|
service_prefix "" {
|
|
policy = "read"
|
|
intentions = "read"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"operator": "read",
|
|
"partition_prefix": {
|
|
"": [{
|
|
"namespace_prefix": {
|
|
"": [{
|
|
"acl": "read",
|
|
"key_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
},
|
|
"node_prefix": {
|
|
"": [{
|
|
"policy": "read"
|
|
}]
|
|
},
|
|
"service_prefix": {
|
|
"": [{
|
|
"intentions": "read",
|
|
"policy": "read"
|
|
}]
|
|
}
|
|
}]
|
|
}
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
### Register the policy with Consul
|
|
|
|
After defining the policies, you can register them with Consul using the command line or API endpoint.
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-all.hcl`.
|
|
|
|
You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes. Because the policy grants cross-partition and cross-namespace access, the policy must be created in the `default` partition and the `default` namespace.
|
|
|
|
```shell-session
|
|
$ consul acl policy create -partition "default" -namespace "default" \
|
|
-name "ui-view-all" -rules @ui-view-all.hcl \
|
|
-description "Allow viewing all resources"
|
|
```
|
|
|
|
Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in `ui-view-all.hcl`. You must embed the policy rules in the `Rules` field of the request body.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Name": "ui-view-all",
|
|
"Description": "Allow viewing all resources",
|
|
"Partition": "default",
|
|
"Namespace": "default",
|
|
"Rules": "operator = \"read\"\npartition_prefix \"\" {\n namespace_prefix \"\" {\n acl = \"read\"\n key_prefix \"\" {\n policy = \"read\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n intentions = \"read\"\n }\n }\n}\n"
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
### Link the policy to a token
|
|
|
|
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
|
|
|
|
<Tabs>
|
|
|
|
<Tab heading="CLI" group="CLI">
|
|
|
|
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
|
|
|
|
```shell-session
|
|
$ consul acl token create -partition "default" -namespace "default" \
|
|
-description "UI token to view all resources" \
|
|
-policy-name "ui-view-all"
|
|
```
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="API" group="API">
|
|
|
|
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
|
|
|
|
You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. Because the policy was created in the `default` partition and `default` namespace, the token must also be created in the `default` partition and `default` namespace.
|
|
|
|
```shell-session
|
|
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
|
|
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
|
|
--data '{
|
|
"Policies": [
|
|
{
|
|
"Name": "ui-view-all"
|
|
}
|
|
],
|
|
"Partition": "default",
|
|
"Namespace": "default"
|
|
}'
|
|
```
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|