github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token...

509 lines
16 KiB
Plaintext
Raw Normal View History

NET-1825: New ACL token creation docs (#16465) Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com>
2023-06-14 14:17:30 +00:00
---
layout: docs
page_title: Create a token for mesh gateway registration
description: >-
Learn how to create ACL tokens that your mesh gateway can present to Consul servers so that they
can register with the Consul catalog.
---
# Create a mesh gateway token
This topic describes how to create a token for a mesh gateway.
## Introduction
Mesh gateways enable service-to-service traffic between Consul datacenters or between Consul admin
partitions. They also enable datacenters to be federated across wide area networks. Refer to [Mesh
Gateways](/consul/docs/connect/gateways#mesh-gateways) for additional information.
Gateways must present a token linked to policies that grant the appropriate set of permissions in
order to be discoverable and to route to other services in a mesh.
## Requiremements
Core ACL functionality is available in all versions of Consul.
The mesh gateway must present a token linked to a policy that grants the following permissions:
* `mesh:write` to obtain leaf certificates for terminating TLS connections
* `peering:read` for Consul cluster peering through mesh gateways. If you are not using cluster
peering or if the mesh gateway is not in the `default` partition, then you can omit the
`peering:read` permission.
* `service:write` to allow the mesh gateway to register into the catalog
* `service:read` for all services and `node:read` for all nodes in order to discover and route to services
* `agent:read` to enable the `consul connect envoy` CLI command to automatically discover gRPC
settings from the Consul agent. If this command is not used to start the gateway or if the Consul
agent uses the default gRPC settings, then you can omit the `agent:read` permission.
@include 'create-token-requirements.mdx'
## Consul OSS
To create a token for the mesh gateway, you must define a policy, register the policy with Consul, and 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 grants the appropriate permissions to register as a service named `mesh-gateway` and to operate as a mesh gateway.
<CodeTabs>
```hcl
mesh = "write"
peering = "read"
service "mesh-gateway" {
policy = "write"
}
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
agent_prefix "" {
policy = "read"
}
```
```json
{
"mesh": "write",
"peering": "read",
"service": {
"mesh-gateway": [{
"policy": "write"
}]
},
"service_prefix": {
"": [{
"policy": "read"
}]
},
"node_prefix": {
"": [{
"policy": "read"
}]
},
"agent_prefix": {
"": [{
"policy": "read"
}]
}
}
```
</CodeTabs>
### Register the policy with Consul
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
The following commands create the ACL policy and token.
<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 `mgw-register.hcl`:
```shell-session
$ consul acl policy create \
-name "mgw-register" -rules @mgw-register.hcl \
-description "Mesh gateway policy"
```
</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 `mgw-register.hcl`. You must embed 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": "mgw-register",
"Description": "Mesh gateway policy",
"Rules": "mesh = \"write\"\npeering = \"read\"\nservice \"mesh-gateway\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nagent_prefix \"\" {\n policy = \"read\"\n}\n"
}'
```
Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
</Tab>
</Tabs>
### Link the policy to a token
After registering the policy 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 `mgw-register`.
```shell-session
$ consul acl token create \
-description "Mesh gateway token" \
-policy-name "mgw-register"
```
</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.
```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
–-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"Policies": [
{
"Name": "mgw-register"
}
]
}'
```
</Tab>
</Tabs>
## Consul Enterprise in default partition
To create a token for the mesh gateway, you must define a policy, register the policy with Consul, and 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.
You can specify an admin partition and namespace when using Consul Enterprise. Mesh gateways must register into the `default` namespace.
The following example policy is defined in a file. The policy grants the appropriate permissions to register as a service named `mesh-gateway` and to operate as a mesh gateway in the default partition.
<CodeTabs>
```hcl
mesh = "write"
partition_prefix "" {
peering = "read"
}
partition "default" {
namespace "default" {
service "mesh-gateway" {
policy = "write"
}
agent_prefix "" {
policy = "read"
}
}
namespace_prefix "" {
node_prefix "" {
policy = "read"
}
service_prefix "" {
policy = "read"
}
}
}
```
```json
{
"mesh": "write",
"partition": {
"default": [{
"namespace": {
"default": [{
"service": {
"mesh-gateway": [{
"policy": "write"
}]
},
"agent_prefix": {
"": [{
"policy": "read"
}]
}
}]
},
"namespace_prefix": {
"": [{
"node_prefix": {
"": [{
"policy": "read"
}]
},
"service_prefix": {
"": [{
"policy": "read"
}]
}
}]
}
}]
},
"partition_prefix": {
"": [{
"peering": "read"
}]
}
}
```
</CodeTabs>
### Register the policy with Consul
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
The following commands create the ACL policy and token.
<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 `mgw-register.hcl`:
You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. You must create the policy in the partition where the mesh gateway registers. The following example creates the policy in the `default` partition.
```shell-session
$ consul acl policy create -partition "default" \
-name mgw-register -rules @mgw-register.hcl \
-description "Mesh gateway policy"
```
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 `mgw-register.hcl`. You must embed 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": "mgw-register",
"Description": "Mesh gateway policy",
"Partition": "default",
"Rules": "mesh = \"write\"\npeering = \"read\"\npartition_prefix \"\" {\n peering = \"read\"\n}\nnamespace \"default\" {\n service \"mesh-gateway\" {\n policy = \"write\"\n }\n agent_prefix \"\" {\n policy = \"read\"\n }\n}\nnamespace_prefix \"\" {\n node_prefix \"\" {\n \tpolicy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n}\n"
}'
```
Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
</Tab>
</Tabs>
### Link the policy to a token
After registering the policy 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.
You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
```shell-session
$ consul acl token create -partition "default" \
-description "Mesh gateway token" \
-policy-name "mgw-register"
```
</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 when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
–-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"Policies": [
{
"Name": "mgw-register"
}
],
"Partition": "default"
}'
```
</Tab>
</Tabs>
## Consul Enterprise in non-default partition
To create a token for the mesh gateway, you must define a policy, register the policy with Consul, and 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.
You can specify an admin partition and namespace when using Consul Enterprise. Mesh gateways must register into the `default` namespace. To register a mesh gateway in a non-default partition, create the ACL policy and token in the partition where the mesh gateway registers.
The following example policy is defined in a file. The policy grants the appropriate permissions to register as a service named `mesh-gateway` and to operate as a mesh gateway in a non-default partition.
<CodeTabs>
```hcl
mesh = "write"
namespace "default" {
service "mesh-gateway" {
policy = "write"
}
agent_prefix "" {
policy = "read"
}
}
namespace_prefix "" {
node_prefix "" {
policy = "read"
}
service_prefix "" {
policy = "read"
}
}
```
```json
{
"mesh": "write",
"namespace": {
"default": [{
"service": {
"mesh-gateway": [{
"policy": "write"
}]
},
"agent_prefix": {
"": [{
"policy": "read"
}]
}
}]
},
"namespace_prefix": {
"": [{
"node_prefix": {
"": [{
"policy": "read"
}]
},
"service_prefix": {
"": [{
"policy": "read"
}]
}
}]
}
}
```
</CodeTabs>
### Register the policy with Consul
After defining the policy, you can register the policy with Consul using the command line or API endpoint.
The following commands create the ACL policy and token.
<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 `mgw-register.hcl`:
You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. You must create the policy in the partition where the mesh gateway registers. The following example creates the policy in the partition `ptn1`.
```shell-session
$ consul acl policy create -partition "ptn1" \
-name mgw-register -rules @mgw-register.hcl \
-description "Mesh gateway policy"
```
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 `mgw-register.hcl`. You must embed 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": "mgw-register",
"Description": "Mesh gateway policy",
"Partition": "ptn1",
"Rules": "mesh = \"write\"\npeering = \"read\"\nnamespace \"default\" {\n service \"mesh-gateway\" {\n policy = \"write\"\n }\n agent_prefix \"\" {\n policy = \"read\"\n }\n}\nnamespace_prefix \"\" {\n node_prefix \"\" {\n \tpolicy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n}\n"
}'
```
Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
</Tab>
</Tabs>
### Link the policy to a token
After registering the policy 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.
You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
```shell-session
$ consul acl token create -partition "ptn1" \
-description "Mesh gateway token" \
-policy-name "mgw-register"
```
</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 when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
–-header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"Policies": [
{
"Name": "mgw-register"
}
],
"Partition": "ptn1"
}'
```
</Tab>
</Tabs>