From 71269daff83e237670b67bed5886da48f3e654ac Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Tue, 28 Feb 2023 13:52:10 -0600 Subject: [PATCH 01/10] NET-1825: New ACL token creation docs --- .../create/create-a-mesh-gateway-token.mdx | 364 ++++++++++++++ .../tokens/create/create-a-service-token.mdx | 341 +++++++++++++ .../create-a-terminating-gateway-token.mdx | 443 +++++++++++++++++ .../acl/tokens/create/create-a-ui-token.mdx | 468 ++++++++++++++++++ .../tokens/create/create-an-agent-token.mdx | 333 +++++++++++++ .../create-an-ingress-gateway-token.mdx | 272 ++++++++++ .../acl/{acl-tokens.mdx => tokens/index.mdx} | 0 .../partials/create-token-auth-methods.mdx | 3 + .../partials/create-token-requirements.mdx | 26 + website/data/docs-nav-data.json | 36 +- 10 files changed, 2285 insertions(+), 1 deletion(-) create mode 100644 website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx create mode 100644 website/content/docs/security/acl/tokens/create/create-a-service-token.mdx create mode 100644 website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx create mode 100644 website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx create mode 100644 website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx create mode 100644 website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx rename website/content/docs/security/acl/{acl-tokens.mdx => tokens/index.mdx} (100%) create mode 100644 website/content/partials/create-token-auth-methods.mdx create mode 100644 website/content/partials/create-token-requirements.mdx diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx new file mode 100644 index 000000000000..dda33e706789 --- /dev/null +++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx @@ -0,0 +1,364 @@ +--- +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 to enable a mesh gateway to register. + +## Introduction + +Gateways must present a token linked to policies that grant the appropriate set of permissions. For a mesh gateway to be discoverable and to route to other services in a mesh, the token must be linked to policies that grant the following permissions: + +* `mesh:write` to obtain leaf certificates for terminating TLS connections +* `peering:read` for Consul cluster peering. If you are not using Consul cluster peering, 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' + +## Create a token linked to a policy + +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 custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. + +#### Consul OSS + +The following example policy grants the mesh gateway the appropriate permissions for the mesh gateway to register as a service named `mesh-gateway`. + + + +```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" + }] + } +} +``` + + + + +#### Consul Enterprise using `default` partition + +You can specify an admin partition and namespace when using Consul Enterprise. Mesh gateways must register into the `default` namespace. The following policy allows a mesh gateway to register as a service named `mesh-gateway` in the default partition. + + + +```hcl +mesh = "write" +peering = "read" +partition_prefix "" { + peering = "read" +} +namespace "default" { + service "mesh-gateway" { + policy = "write" + } + agent_prefix "" { + policy = "read" + } +} +namespace_prefix "" { + node_prefix "" { + policy = "read" + } + service_prefix "" { + policy = "read" + } +} +``` + +```json +{ + "mesh": "write", + "peering": "read", + "partition_prefix": { + "": [{ + "peering": "read" + }] + }, + "namespace": { + "default": [{ + "agent_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "mesh-gateway": [{ + "policy": "write" + }] + } + }] + }, + "namespace_prefix": { + "": [{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } + }] + } +} +``` + + + + +#### Consul Enterprise using non-`default` partition + +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 ACL policy rules allow a mesh gateway to register as the `mesh-gateway` service in a non-default partition. + + + +```hcl +mesh = "write" +peering = "read" +namespace "default" { + service "mesh-gateway" { + policy = "write" + } + agent_prefix "" { + policy = "read" + } +} +namespace_prefix "" { + node_prefix "" { + policy = "read" + } + service_prefix "" { + policy = "read" + } +} +``` + +```json +{ + "mesh": "write", + "peering": "read", + "namespace": { + "default": [{ + "agent_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "mesh-gateway": [{ + "policy": "write" + }] + } + }] + }, + "namespace_prefix": { + "": [{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } + }] + } +} +``` + + + + +### 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. + +#### CLI + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`: + +##### Consul OSS + +```shell-session +$ consul acl policy create \ + -name "mgw-register" -rules @mgw-register.hcl \ + -description "Mesh gateway policy" +``` + +##### Consul Enterprise + +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 \ + -name mgw-register -rules @mgw-register.hcl \ + -description "Mesh gateway policy" \ + -partition ptn1 +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + +#### 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 custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. + +##### Consul OSS + + +```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" +}' +``` + +##### Consul Enterprise (Default Partition) + + +```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" +}' +``` + +##### Consul Enterprise (Non-default Partition) + +```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. + +### 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. + +#### 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. + +##### Consul OSS + +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" +``` + +##### Consul Enterprise + +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" +``` + +#### 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. + +##### Consul OSS + + +```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" + } + ] +}' +``` + +##### Consul Enterprise + +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" +}' +``` + +@include 'create-token-auth-methods.mdx' diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx new file mode 100644 index 000000000000..8098bb832496 --- /dev/null +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -0,0 +1,341 @@ +--- +layout: docs +page_title: Create tokens for service registration +Description: >- + Learn how to create ACL tokens that your services can present to Consul servers so that they can register with the Consul catalog. +--- + +# Create a service token + +This topic describes how to create a token that you can use to discover services and to register services into the Consul catalog. If you are using Consul service mesh, this token can be used by a sidecar proxy to discover and route to other services. + +## Introduction + +Services must present a token linked to policies that grant the appropriate set of permissions. For a service to be discoverable or to interact with other services in a mesh, the token must be linked to policies that grant the following permissions: + +* `service:write`: Enables the service to update the catalog. If service mesh is enabled, the service's sidecar proxy can also update the catalog.Note that this permission implicitly grants `intention:read` permission to sidecar proxies so that they can read and enforce intentions. Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for details. +* `service:read`: Enables the service to learn about other services in the network. If service mesh is enabled, the service's sidecar proxy can also learn about other services in the network. +* `node:read`: Enables the sidecar proxy to discover and route traffic to other services in the catalog if service mesh is enabled. + +### Service identities versus custom policies + +You can create tokens linked to custom policies or to service identities. [Service identities](/consul/docs/security/acl#service-identities) are constructs in Consul that enable you to quickly grant permissions for a group of services, rather than creating similar policies for each service. + +We recommend using a service identity to grant permissions for service discovery and service mesh use cases rather than creating a custom policy. This is because service identities automatically grant the service and its sidecar proxy `service:write`, `service:read`, and `node:read`. + +Your organization may have requirements or processes for deploying services in a way that is inconsistent with service and node identities. In these cases, you can create custom policies and link them to tokens. + +@include 'create-token-requirements.mdx' + +## Create tokens linked to service identities + +Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. + +You can manually create 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. + +### CLI + +Run the `consul acl token create` command and specify the policy or service identity to link to create a token. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command. + +The following example creates an ACL token linked to a service identity for a service named `svc1`. + +#### Consul OSS + +```shell-session +$ consul acl token create \ + -description "Service token for svc1" \ + -service-identity "svc1" +``` + +#### Consul Enterprise + +You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: + +```shell-session +$ consul acl token create -partition "ptn1" -namespace "ns1" \ + -description "Service token for svc1" \ + -service-identity "svc1" +``` + +### API + +Send a PUT request to the `/acl/token` endpoint and specify a service identity in the request body to create a token linked to the service identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. + +The following example creates a token linked to a service identity named `svc1`: + +#### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "ServiceIdentities": [ + { + "ServiceName": "svc1", + "Datacenters": ["dc1"] + } + ] +}' + +``` + +#### Consul Enterprise + +You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "ServiceIdentities": [ + { + "ServiceName": "svc1", + "Datacenters": ["dc1"] + } + ], + "Namespace": "ns1", + "Partition": "ptn1" +}' +``` + +@include 'create-token-auth-methods.mdx' + +## Create tokens linked to custom policies + +When you are unable to link tokens to a service identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. + +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. + +#### Consul OSS + +The following example policy grants the `svc1` service `write` permissions so that it can register into the catalog. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. + + + +```hcl +service "svc1" { + policy = "write" +} +service "svc1-sidecar-proxy" { + policy = "write" +} +service_prefix "" { + policy = "read" +} +node_prefix "" { + policy = "read" +} +``` + +```json +{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "svc1": [{ + "policy": "write" + }], + "svc1-sidecar-proxy": [{ + "policy": "write" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } +} +``` + + + +#### Consul Enterprise + +You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example policy allows the `svc1` service to register in the `ns1` namespace of partition `ptn1`. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. + + + +```hcl +partition "ptn1" { + namespace "ns1" { + service "svc1" { + policy = "write" + } + service "svc1-sidecar-proxy" { + policy = "write" + } + service_prefix "" { + policy = "read" + } + node_prefix "" { + policy = "read" + } + } +} +``` + +```json +{ + "partition": { + "ptn1": [{ + "namespace": { + "ns1": [{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "svc1": [{ + "policy": "write" + }], + "svc1-sidecar-proxy": [{ + "policy": "write" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } + }] + } + }] + } +} +``` + + + +### Register policies with Consul + +After defining the custom policies, you can register them with Consul using the command line or API endpoint. + +#### CLI + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `svc1-register.hcl`: + +##### Consul OSS + +```shell-session +$ consul acl policy create \ + -name "svc1-register" -rules @svc1-register.hcl \ + -description "Allow svc1 to register into the catalog" +``` + +##### Consul Enterprise + +```shell-session +$ consul acl policy create -partition "ptn1" -namespace "ns1" \ + -name "svc1-register" -rules @svc1-register.hcl \ + -description "Custom policy for service svc1" +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl token create` command. + +#### 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 custom policy defined in `svc1-register.hcl`. You must embed policy rules in the `Rules` field of the request body + +##### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "svc1-register", + "Description": "Allow svc1 to register into the catalog", + "Rules": "service \"svc1\" {\n policy = \"write\"\n}\nservice \"svc1-sidecar-proxy\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\n" +}' +``` + +##### Consul Enterprise + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "svc1-register", + "Description": "Allow svc1 to register into the catalog", + "Namespace": "ns1", + "Partition": "ptn1", + "Rules": "partition \"ptn1\" {\n namespace \"ns1\" {\n service \"svc1\" {\n policy = \"write\"\n }\n service \"svc1-sidecar-proxy\" {\n policy = \"write\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n" +}' +``` + +Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. + +### Link custom policies to tokens + +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. + +#### 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. + +##### Consul OSS + +The following commands create the ACL token linked to the policy `svc1-register`. + +```shell-session +$ consul acl token create \ + -description "Service token for svc1" \ + -policy-name "svc1-register" +``` + +##### Consul Enterprise + +You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: + +The following commands create the ACL token linked to the policy `svc1-register`. + +```shell-session +$ consul acl token create -partition "ptn1" -namespace "ns1" \ + -description "Service token for svc1" \ + -policy-name "svc1-register" +``` + +#### 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. + +##### Consul OSS + +The following example creates an ACL token that the `svc1` service can use to register in the `ns1` namespaces of 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": "svc1-register" + } + ] +}' +``` + +##### Consul Enterprise + +You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of 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": "svc1-register" + } + ], + "Namespace": "ns1", + "Partition": "ptn1" +}' +``` + +@include 'create-token-auth-methods.mdx' diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx new file mode 100644 index 000000000000..777efc634081 --- /dev/null +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -0,0 +1,443 @@ +--- +layout: docs +page_title: Create a token for terminating gateway registration +Description: >- + Learn how to create ACL tokens that your terminating gateway can present to Consul servers so that they can register with the Consul catalog. +--- + +# Create a terminating gateway token + +This topic describes how to create an ACL token that enables a terminating gateway to register with Consul. + +## Introduction + +Gateways must present a token linked to policies that grant the appropriate set of permissions. For a terminating gateway to be discoverable and to forward traffic out of the mesh, the token must be linked to policies that grant the following permissions: + +* `service:write` to allow the terminating gateway to register into the catalog +* `service:write` for each service that it forwards traffic for +* `node:read` for the nodes of each service that it forwards traffic for +* `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. + +### External services + +Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to services and destinations outside the mesh. + +The following policy examples assume the terminating gateway only needs to forward traffic to two external services named `external-service-1` and `external-service-2`. The policy examples include `service:write` permissions for these two services. If you have additional services, `service:write` permissions for those services also need to be included in the policy rules. + +To learn how to configure terminating gateways, refer to the [Terminating Gateways](/consul/docs/connect/gateways/terminating-gateway#terminating-gateway-configuration) documentation and the [Understand Terminating Gateways](/consul/tutorials/developer-mesh/service-mesh-terminating-gateways) tutorial. + +@include 'create-token-requirements.mdx' + +## Create a token linked to a policy + +To create a token for the terminating gateway, you must define a policy, register the policy with Consul, and link the policy to a token. + +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. + +#### Consul OSS + +The following example policy allows a terminating gateway to register as a service named `terminating-gateway`. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. + + + +```hcl +service "terminating-gateway" { + policy = "write" +} +service "external-service-1" { + policy = "write" +} +service "external-service-2" { + policy = "write" +} +node_prefix "" { + policy = "read" +} +agent_prefix "" { + policy = "read" +} +``` + +```json +{ + "service": { + "terminating-gateway": [{ + "policy": "write" + }], + "external-service-1": [{ + "policy": "write" + }], + "external-service-2": [{ + "policy": "write" + }] + }, + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "agent_prefix": { + "": [{ + "policy": "read" + }] + } +} +``` + + + + +#### Consul Enterprise using `default` partition and `default` namespace + +You can specify an admin partition and namespace when using Consul Enterprise. The following example policy allows a terminating gateway to register as a service named `terminating-gateway` in the `default` partition and `default` namespace. + +For this example, the terminating gateway forwards traffic for the following two services: + +* `external-service-1` in the `default` namespace +* `external-service-2` in the `ns1` namespace + + + +```hcl +partition "default" { + namespace "default" { + service "terminating-gateway" { + policy = "write" + } + service "external-service-1" { + policy = "write" + } + node_prefix "" { + policy = "read" + } + agent_prefix "" { + policy = "read" + } + } + namespace "ns1" { + service "external-service-2" { + policy = "write" + } + node_prefix "" { + policy = "read" + } + } +} +``` + +```json +{ + "partition": { + "default": [{ + "namespace": { + "default": [{ + "agent_prefix": { + "": [{ + "policy": "read" + }] + }, + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "external-service-1": [{ + "policy": "write" + }], + "terminating-gateway": [{ + "policy": "write" + }] + } + }], + "ns1": [{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "external-service-2": [{ + "policy": "write" + }] + } + }] + } + }] + } +} +``` + + + +#### Consul Enterprise using a non-`default` partition and non-`default` namespace + +You can specify an admin partition and namespace when using Consul Enterprise. The following example policy allows a terminating gateway to register as a service named `terminating-gateway` in namespace `ns1` in partition `ptn1`. + +For this example, the terminating gateway forwards traffic for the following two services: + +* `external-service-1` in the `default` namespace +* `external-service-2` in the `ns1` namespace + +The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. + + + +```hcl +partition "ptn1" { + namespace "ns1" { + service "terminating-gateway" { + policy = "write" + } + node_prefix "" { + policy = "read" + } + service "external-service-2" { + policy = "write" + } + } + namespace "default" { + service "external-service-1" { + policy = "write" + } + node_prefix "" { + policy = "read" + } + agent_prefix "" { + policy = "read" + } + } +} +``` + +```json +{ + "partition": { + "ptn1": [{ + "namespace": { + "default": [{ + "agent_prefix": { + "": [{ + "policy": "read" + }] + }, + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "external-service-1": [{ + "policy": "write" + }] + } + }], + "ns1": [{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "external-service-2": [{ + "policy": "write" + }], + "terminating-gateway": [{ + "policy": "write" + }] + } + }] + } + }] + } +} +``` + + + +### 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. + +#### CLI + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `tgw-register.hcl`: + +##### Consul OSS + +```shell-session +$ consul acl policy create \ + -name "tgw-register" -rules @tgw-register.hcl \ + -description "Terminating gateway policy" +``` + +##### Consul Enterprise using `default` partition and `default` namespace + +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. The policy must be created in the partition where the terminating gateway will register. The following example creates the policy in the `default` partition. + +```shell-session +$ consul acl policy create -partition "default" -namespace "default" \ + -name "tgw-register" -rules @tgw-register.hcl \ + -description "Terminating gateway policy" +``` + +##### Consul Enterprise using a non-`default` partition and non-`default` namespace + +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the policy must be created in the `default` namespace. The following example creates the policy in the partition `ptn1` and `default` namespace because the example policy contains permissions for multiple namespaces. + +```shell-session +$ consul acl policy create -partition "ptn1" -namespace "default" \ + -name "tgw-register" -rules @tgw-register.hcl \ + -description "Terminating gateway policy" +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + +#### 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 custom policy defined in `tgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. + +##### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "tgw-register", + "Description": "Terminating gateway policy", + "Rules": "service \"terminating-gateway\" {\n policy = \"write\"\n}\nservice \"external-service-1\" {\n policy = \"write\"\n}\nservice \"external-service-2\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nagent_prefix \"\" {\n policy = \"read\"\n}\n" +}' +``` + +##### Consul Enterprise using `default` partition and `default` namespace + +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway are registered. The following example creates the policy in the `default` partition. + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "tgw-register", + "Description": "Terminating gateway policy", + "Partition": "default", + "Namespace": "default", + "Rules": "partition \"default\" {\n namespace \"default\" {\n service \"terminating-gateway\" {\n policy = \"write\"\n }\n service \"external-service-1\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n agent_prefix \"\" {\n policy = \"read\"\n }\n }\n namespace \"ns1\" {\n service \"external-service-2\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n" +}' +``` + +##### Consul Enterprise using a non-`default` partition and non-`default` namespace + +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the policy must be created in the default namespace. The following example creates the policy in the partition `ptn1` and `default` namespace because the example policy contains permissions for multiple namespaces. + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "tgw-register", + "Description": "Terminating gateway policy", + "Partition": "ptn1", + "Namespace": "default", + "Rules": "partition \"ptn1\" {\n namespace \"ns1\" {\n service \"terminating-gateway\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n service \"external-service-2\" {\n policy = \"write\"\n }\n }\n namespace \"default\" {\n service \"external-service-1\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n agent_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n" +}' +``` + +Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. + +### 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. + +#### 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. + +##### Consul OSS + +The following command creates the ACL token linked to the policy `tgw-register`. + +```shell-session +$ consul acl token create \ + -description "Terminating gateway token" \ + -policy-name "tgw-register" +``` + +##### Consul Enterprise using the `default` partition and `default` namespace + +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the same partition where the terminating gateway is registered. The following example creates the token in the partition `default` and namespace `default`. + +```shell-session +$ consul acl token create -partition "default" -namespace "default" \ + -description "Terminating gateway token" \ + -policy-name "tgw-register" +``` + +##### Consul Enterprise using a non-`default` partition and non-`default` namespace + +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the same partition where the terminating gateway is registered. The following example creates the token in the partition `ptn1` and namespace `default`. + +```shell-session +$ consul acl token create -partition "ptn1" -namespace "default" \ + -description "Terminating gateway token" \ + -policy-name "tgw-register" +``` + +#### 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. + +##### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Policies": [ + { + "Name": "tgw-register" + } + ] +}' +``` + +##### Consul Enterprise using the `default` partition and `default` namespace + +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. The following example creates the token in the partition `ptn1` and namespace `default`. + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Policies": [ + { + "Name": "tgw-register" + } + ], + "Partition": "default", + "Namespace": "default" +}' +``` + +##### Consul Enterprise using a non-`default` partition and non-`default` namespace + +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the token must be created in the `default` namespace. The following example creates the token in the `default` namespace in the `ptn1` partition because the example policy contains permissions for multiple namespaces. + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Policies": [ + { + "Name": "tgw-register" + } + ], + "Partition": "ptn1", + "Namespace": "default" +}' +``` + +@include 'create-token-auth-methods.mdx' diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx new file mode 100644 index 000000000000..61355a39a7d0 --- /dev/null +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -0,0 +1,468 @@ +--- +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. + +@include 'create-token-requirements.mdx' + +## Create a token with read-only access to the catalog + +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 custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. + +#### Consul OSS + +The following policy allows you to view all services and nodes in the catalog. + + + +```hcl +service_prefix "" { + policy = "read" +} +node_prefix "" { + policy = "read" +} +``` + +```json +{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } +} +``` + + + +#### Consul Enterprise + +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. + + + +```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" + }] + } + }] + } + }] + } +} +``` + + + +### Register policies with Consul + +After defining the policies, you can register them with Consul using the command line or API endpoint. + +#### CLI + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-catalog.hcl`. + +##### Consul OSS + +```shell-session +$ consul acl policy create \ + -name "ui-view-catalog" -rules @ui-view-catalog.hcl \ + -description "Allow viewing the catalog" +``` + +##### Consul Enterprise + +You can specify an admin partition, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the network areas 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. + +#### 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 custom policy defined in `view-catalog.hcl`. You must embed the policy rules in the `Rules` field of the request body. + +##### Consul OSS + +```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" +}' +``` + +##### Consul Enterprise + +```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" +}' +``` + +### Link custom policies to tokens + +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. + +#### 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. + +##### Consul OSS + +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" +``` + +##### Consul Enterprise + +```shell-session +$ consul acl token create -partition "default" -namespace "default" \ + -description "UI token to view the catalog" \ + -policy-name "ui-view-catalog" +``` + +#### 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. + +##### Consul OSS + +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" + } + ] +}' +``` + +##### Consul Enterprise + +You can specify an admin partition, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the network areas 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" +}' +``` + +@include 'create-token-auth-methods.mdx' + +## Create a token with read-only access to all resources + +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 custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. + +#### Consul OSS + +The following policy allows viewing 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. + + + +```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" + }] + } +} +``` + + + +#### Consul Enterprise + +The following 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. + + + +```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" + }] + } + }] + } + }] + } +} +``` + + + +### Register policies with Consul + +After defining the policies, you can register them with Consul using the command line or API endpoint. + +#### CLI + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-all.hcl`. + +##### Consul OSS + +```shell-session +$ consul acl policy create \ + -name "ui-view-all" -rules @ui-view-all.hcl \ + -description "Allow viewing all resources" +``` + +##### Consul Enterprise + +You can specify an admin partition, namespace, or both when creating policies in Consul Enterprise. The policy is only valid in the specified network areas. 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. + +#### 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 custom policy defined in `ui-view-all.hcl`. You must embed the policy rules in the `Rules` field of the request body. + +##### Consul OSS + +```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" +}' +``` + +##### Consul Enterprise + +```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" +}' +``` + +### Link custom policies to tokens + +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. + +#### 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. + +##### Consul OSS + +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" +``` + +##### Consul Enterprise + +```shell-session +$ consul acl token create -partition "default" -namespace "default" \ + -description "UI token to view all resources" \ + -policy-name "ui-view-all" +``` + +#### 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. + +##### Consul OSS + +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" + } + ] +}' +``` + +##### Consul Enterprise + +You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. 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" +}' +``` + +@include 'create-token-auth-methods.mdx' diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx new file mode 100644 index 000000000000..41cd23041401 --- /dev/null +++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx @@ -0,0 +1,333 @@ +--- +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 an agent token + +This topic describes how to create a token that you can use to register an agent into the catalog. + +## Introduction + +Consul agents must present a token linked to policies that grant the appropriate set of permissions. For an agent to register into the catalog, the token must be linked to policies that grant the following permissions: + +* `node:write`: Enables the agent to update the catalog. +* `service:read`: Enables the agent to discover other services in the catalog + +Specify the [`agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) token to the Consul agent so that it can present the token when it registers into the catalog. + +### Node identities versus custom policies + +You can create tokens linked to custom policies or to node identities. [Node identities](/consul/docs/security/acl#node-identities) are constructs in Consul that enable you to quickly grant permissions for a group of agents, rather than create similar policies for each agent. + +We recommend using a node identity to grant permissions to the agent rather than creating a custom policy. This is because node identities automatically grant the node `node:write` and `service:read` permission. + +Your organization may have requirements or processes for deploying services in a way that is inconsistent with service and node identities. In these cases, you can create custom policies and link them to tokens. + +@include 'create-token-requirements.mdx' + +## Create tokens linked to node identities + +Refer to [Node identities](/consul/docs/security/acl#node-identities) for information about node identities that you can link to tokens. + +You can manually create 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. + +### CLI + +Run the `consul acl token create` command and specify the policy or node identity to link to create a token. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command. + +#### Consul OSS + +The following command creates an ACL token linked to a node identity for a node named `node1` in the datacenter `dc1`. + +```shell-session +$ consul acl token create \ + -description "Agent token for node1" \ + -node-identity "node1:dc1" +``` + +#### Consul Enterprise + +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in partition `ptn1` in datacenter `dc1`: + +```shell-session +$ consul acl token create -partition "ptn1" \ + -description "Agent token for node1" \ + -node-identity "node1:dc1" +``` + +### API + +Send a PUT request to the `/acl/token` endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. + +The following example creates a token linked to a node identity named `node1`: + +#### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "NodeIdentities": [ + { + "NodeName": "node1", + "Datacenter": "dc1" + } + ] +}' +``` + +#### Consul Enterprise + +You can specify an admin partition when creating a token in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in the partition `ptn1` in datacenter `dc1`: + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "NodeIdentities": [ + { + "NodeName": "node1", + "Datacenter": "dc1" + } + ], + "Partition": "ptn1" +}' +``` + +@include 'create-token-auth-methods.mdx' + +## Create tokens linked to custom policies + +When you are unable to link tokens to a node identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog. + +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. + +#### Consul OSS + +The following example policy grants the agent node `write` permission for node `node1` so that it can register into the catalog. It grants service `read` permissions to discover services in the catalog. + + + +```hcl +node "node1" { + policy = "write" +} +service_prefix "" { + policy = "read" +} +``` + +```json +{ + "node": { + "node1": [{ + "policy": "write" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } +} +``` + + + +#### Consul Enterprise + +The following example policy grants the `node1` node `write` permission to register in the partition `ptn1`. It grants service `read` permissions for any service in any namespace in the `ptn1` partition. + + + +```hcl +partition "ptn1" { + node "node1" { + policy = "write" + } + namespace_prefix "" { + service_prefix "" { + policy = "read" + } + } +} +``` + +```json +{ + "partition": { + "ptn1": [{ + "namespace_prefix": { + "": [{ + "service_prefix": { + "": [{ + "policy": "read" + }] + } + }] + }, + "node": { + "node1": [{ + "policy": "write" + }] + } + }] + } +} +``` + + + +### Register policies with Consul + +After defining the custom policies, you can register them with Consul using the command line or API endpoint. + +#### CLI + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `node1-register.hcl`: + +##### Consul OSS + +```shell-session +$ consul acl policy create \ + -name "node1-register" -rules @node1-register.hcl \ + -description "Custom policy for node1" \ +``` + +##### Consul Enterprise + +```shell-session +$ consul acl policy create -partition "ptn1" \ + -name "node1-register" -rules @node1-register.hcl \ + -description "Custom policy for node1" +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + +#### 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 custom policy defined in `node1-register.hcl`. You must embed policy rules in the `Rules` field of the request body. + +##### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "node1-register", + "Description": "Allow node1 to register into the catalog", + "Rules": "node \"node1\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\n" +}' +``` + +##### Consul Enterprise + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "node1-register", + "Description": "Allow node1 to register into the catalog", + "Partition": "ptn1", + "Rules": "partition \"ptn1\" {\n node \"node1\" {\n policy = \"write\"\n }\n namespace_prefix \"\" {\n service_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n" +}' +``` + +Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. + +### Link custom policies to tokens + +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. + +#### 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. + +##### Consul OSS + +The following command creates the ACL token linked to the policy `node1-register`. + +```shell-session +$ consul acl token create \ + -description "Agent token for node1" \ + -policy-name "node1-register" +``` + +##### Consul Enterprise + +```shell-session +$ consul acl token create -partition "ptn1" \ + -description "Agent token for node1" \ + -policy-name "node1-register" +``` + +#### 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. + +##### Consul OSS + +The following example creates an ACL token that the agent can use to register as node `node1` in 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": "node1-register" + } + ] +}' +``` + +##### Consul Enterprise + +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register as the node `node1` 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": "node1-register" + } + ], + "Partition": "ptn1" +}' +``` + +@include 'create-token-auth-methods.mdx' + +## Apply the token + +Configure the Consul agent to present the token by either specifying the token in the agent configuration file or by using the `consul set-agent-token` command. + +### Apply the token in a file + +Specify the token in the [`acl.token.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) field of the agent configuration file so that the agent can present it and register into the catalog on startup. + +```hcl +acl = { + enabled = true + tokens = { + agent = "" + ... + } + ... +} +``` + +### Apply the token with a command + +Set the `agent` token using the [`consul set-agent-token`](/consul/commands/acl/set-agent-token) command. The following command configures a running Consul agent token with the specified token. + +```shell-session +consul acl set-agent-token agent +``` diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx new file mode 100644 index 000000000000..70a1974cfc39 --- /dev/null +++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx @@ -0,0 +1,272 @@ +--- +layout: docs +page_title: Create a token for ingress gateway registration +Description: >- + Learn how to create ACL tokens that your ingress gateway can present to Consul servers so that they can register with the Consul catalog. +--- + +# Create an ingress gateway token + +This topic describes how to create a token to enable an ingress gateway to register. + +## Introduction + +Gateways must present a token linked to policies that grant the appropriate set of permissions. For an ingress gateway to register and to route to other services in a mesh, the token must be linked to policies that grant the following permissions: + +* `service:write` to allow the ingress 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' + +## Create a token linked to a policy + +To create a token for the ingress gateway, you must define a policy, register the policy with Consul, and link the policy to a token. + +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. + +#### Consul OSS + +The following example policy grants the ingress gateway the appropriate permissions to register as a service named `ingress-gateway`. + + + +```hcl +service "ingress-gateway" { + policy = "write" +} +node_prefix "" { + policy = "read" +} +service_prefix "" { + policy = "read" +} +agent_prefix "" { + policy = "read" +} +``` + +```json +{ + "agent_prefix": { + "": [{ + "policy": "read" + }] + }, + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "ingress-gateway": [{ + "policy": "write" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } +} +``` + + + +#### Consul Enterprise + +You can specify an admin partition and namespace when using Consul Enterprise. The following policy allows an ingress gateway to register as a service named `ingress-gateway` in the `ptn1` partition and `ns1` namespace. + +The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. + + + +```hcl +partition "ptn1" { + namespace "ns1" { + service "ingress-gateway" { + policy = "write" + } + node_prefix "" { + policy = "read" + } + service_prefix "" { + policy = "read" + } + } + namespace "default" { + agent_prefix "" { + policy = "read" + } + } +} +``` + +```json +{ + "partition": { + "ptn1": [{ + "namespace": { + "default": [{ + "agent_prefix": { + "": [{ + "policy": "read" + }] + } + }], + "ns1": [{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service": { + "ingress-gateway": [{ + "policy": "write" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } + }] + } + }] + } +} +``` + + + +### 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. + +#### CLI + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `igw-register.hcl`: + +##### Consul OSS + +```shell-session +$ consul acl policy create \ + -name "igw-register" -rules @igw-register.hcl \ + -description "Ingress gateway policy" +``` + +##### Consul Enterprise + +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. The following example creates the policy in the `default` namespace in the `ptn1` partition. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. + +```shell-session +$ consul acl policy create -partition "ptn1" -namespace "default" \ + -name "igw-register" -rules @igw-register.hcl \ + -description "Ingress gateway policy" +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + +#### 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 custom policy defined in `igw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. + +##### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "igw-register", + "Description": "Ingress gateway policy", + "Rules": "service \"ingress-gateway\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nagent_prefix \"\" {\n policy = \"read\"\n}\n" +}' +``` + +##### Consul Enterprise + +You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition `ptn1` and namespace `ns1`. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Name": "igw-register", + "Description": "Ingress gateway policy", + "Partition": "ptn1", + "Namespace": "default", + "Rules": "partition \"ptn1\" {\n namespace \"ns1\" {\n service \"ingress-gateway\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n }\n namespace \"default\" {\n agent_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n" +}' +``` + +Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. + +### 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. + +#### 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. + +##### Consul OSS + +The following command creates the ACL token linked to the policy `igw-register`. + +```shell-session +$ consul acl token create \ + -description "Ingress gateway token" \ + -policy-name "igw-register" +``` + +##### Consul Enterprise + +You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition `ptn1` and namespace `default`. The example policy contains permissions for resources in multiple namespaces. You must create ACL tokens linked to policies that grant permissions for multiple namespaces in the `default` namespace. + +```shell-session +$ consul acl token create -partition "ptn1" -namespace "default" \ + -description "Ingress gateway token" \ + -policy-name "igw-register" +``` + +#### 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. + +##### Consul OSS + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Policies": [ + { + "Name": "igw-register" + } + ] +}' +``` + +##### Consul Enterprise + +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the ingress gateway is registered. The following example creates the token in the partition `ptn1` and namespace `default`. + +```shell-session +$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ + --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ + --data '{ + "Policies": [ + { + "Name": "igw-register" + } + ], + "Partition": "ptn1", + "Namespace": "default" +}' +``` + +@include 'create-token-auth-methods.mdx' diff --git a/website/content/docs/security/acl/acl-tokens.mdx b/website/content/docs/security/acl/tokens/index.mdx similarity index 100% rename from website/content/docs/security/acl/acl-tokens.mdx rename to website/content/docs/security/acl/tokens/index.mdx diff --git a/website/content/partials/create-token-auth-methods.mdx b/website/content/partials/create-token-auth-methods.mdx new file mode 100644 index 000000000000..912870728503 --- /dev/null +++ b/website/content/partials/create-token-auth-methods.mdx @@ -0,0 +1,3 @@ +### Auth methods + +Auth methods are components that perform authentication against a trusted external party to authorize the creation of ACL tokens for use within the local datacenter. Refer to the [auth methods documentation](/consul/docs/security/acl/auth-methods) for details about how to leverage auth methods in your network. diff --git a/website/content/partials/create-token-requirements.mdx b/website/content/partials/create-token-requirements.mdx new file mode 100644 index 000000000000..8b55f500517a --- /dev/null +++ b/website/content/partials/create-token-requirements.mdx @@ -0,0 +1,26 @@ +## Requirements + +Core ACL functionality is available in all versions of Consul. + +### Authentication + +You must provide an ACL token linked to a policy with `acl:write` permissions to create and modify ACL tokens and policies using the CLI or API. + +You can provide the token manually using the `-token` option on the command line, but we recommend setting the `CONSUL_HTTP_TOKEN` environment variable to simplify your workflow: + +```shell-session +$ export CONSUL_HTTP_TOKEN= +``` + +The Consul CLI automatically reads the `CONSUL_HTTP_TOKEN` environment variable so that you do not have to pass the token to every Consul CLI command. + +To authenticate calls to the Consul HTTP API, you must provide the token in the `X-Consul-Token` header for each call: + +```shell-session +$ curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" ... +``` + +To learn about alternative ways to authenticate, refer to the following documentation: + +* [CLI Authentication](/consul/commands#authentication) +* [API Authentication](/consul/api-docs/api-structure#authentication) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index ec1afef6f1f1..f04ec8373d64 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -815,7 +815,41 @@ }, { "title": "Tokens", - "path": "security/acl/acl-tokens" + "routes": [ + { + "title": "Overview", + "path": "security/acl/tokens" + }, + { + "title": "Create ACL Tokens", + "routes": [ + { + "title": "Create a service token", + "path": "security/acl/tokens/create/create-a-service-token" + }, + { + "title": "Create an agent token", + "path": "security/acl/tokens/create/create-an-agent-token" + }, + { + "title": "Create a UI token", + "path": "security/acl/tokens/create/create-a-ui-token" + }, + { + "title": "Create a mesh gateway token", + "path": "security/acl/tokens/create/create-a-mesh-gateway-token" + }, + { + "title": "Create an ingress gateway token", + "path": "security/acl/tokens/create/create-an-ingress-gateway-token" + }, + { + "title": "Create a terminating gateway token", + "path": "security/acl/tokens/create/create-a-terminating-gateway-token" + } + ] + } + ] }, { "title": "Policies", From 953fec05040ddcc05c707fd6e9a44fa6ec9129ba Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Mon, 8 May 2023 10:37:27 -0500 Subject: [PATCH 02/10] Fix doc headers --- .../create/create-a-mesh-gateway-token.mdx | 22 +++++------ .../tokens/create/create-a-service-token.mdx | 4 +- .../create-a-terminating-gateway-token.mdx | 2 +- .../acl/tokens/create/create-a-ui-token.mdx | 2 +- .../tokens/create/create-an-agent-token.mdx | 38 +++++++++---------- .../create-an-ingress-gateway-token.mdx | 2 +- 6 files changed, 35 insertions(+), 35 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx index dda33e706789..189e3c6efd1a 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx @@ -1,13 +1,13 @@ --- layout: docs page_title: Create a token for mesh gateway registration -Description: >- +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 to enable a mesh gateway to register. +This topic describes how to create a token to enable a mesh gateway to register. ## Introduction @@ -27,7 +27,7 @@ To create a token for the mesh gateway, you must define a policy, register the p ### Define a custom policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. #### Consul OSS @@ -35,7 +35,7 @@ The following example policy grants the mesh gateway the appropriate permissions -```hcl +```hcl mesh = "write" peering = "read" service "mesh-gateway" { @@ -246,7 +246,7 @@ You can specify an admin partition when creating policies in Consul Enterprise. consul acl policy create \ -name mgw-register -rules @mgw-register.hcl \ -description "Mesh gateway policy" \ - -partition ptn1 + -partition ptn1 ``` Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. @@ -295,7 +295,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ }' ``` -Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. +Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. ### Link the policy to a token @@ -307,7 +307,7 @@ Run the `consul acl token create` command and specify the policy name or ID to c ##### Consul OSS -The following command creates the ACL token linked to the policy `mgw-register`. +The following command creates the ACL token linked to the policy `mgw-register`. ```shell-session $ consul acl token create \ @@ -338,10 +338,10 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --data '{ "Policies": [ { - "Name": "mgw-register" + "Name": "mgw-register" } ] -}' +}' ``` ##### Consul Enterprise @@ -354,11 +354,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --data '{ "Policies": [ { - "Name": "mgw-register" + "Name": "mgw-register" } ], "Partition": "ptn1" -}' +}' ``` @include 'create-token-auth-methods.mdx' diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index 8098bb832496..e812c767f238 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: Create tokens for service registration -Description: >- +description: >- Learn how to create ACL tokens that your services can present to Consul servers so that they can register with the Consul catalog. --- @@ -297,7 +297,7 @@ The following commands create the ACL token linked to the policy `svc1-register` ```shell-session $ consul acl token create -partition "ptn1" -namespace "ns1" \ -description "Service token for svc1" \ - -policy-name "svc1-register" + -policy-name "svc1-register" ``` #### API diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx index 777efc634081..6f574da5f373 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: Create a token for terminating gateway registration -Description: >- +description: >- Learn how to create ACL tokens that your terminating gateway can present to Consul servers so that they can register with the Consul catalog. --- diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx index 61355a39a7d0..f9dad0ce94d9 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: Create tokens for agent registration -Description: >- +description: >- Learn how to create ACL tokens that your Consul agents can present to Consul servers so that they can join the Consul cluster. --- diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx index 41cd23041401..123acb6effa9 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: Create tokens for agent registration -Description: >- +description: >- Learn how to create ACL tokens that your Consul agents can present to Consul servers so that they can join the Consul cluster. --- @@ -60,9 +60,9 @@ $ consul acl token create -partition "ptn1" \ ### API -Send a PUT request to the `/acl/token` endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. +Send a PUT request to the `/acl/token` endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. -The following example creates a token linked to a node identity named `node1`: +The following example creates a token linked to a node identity named `node1`: #### Consul OSS @@ -72,8 +72,8 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --data '{ "NodeIdentities": [ { - "NodeName": "node1", - "Datacenter": "dc1" + "NodeName": "node1", + "Datacenter": "dc1" } ] }' @@ -89,8 +89,8 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --data '{ "NodeIdentities": [ { - "NodeName": "node1", - "Datacenter": "dc1" + "NodeName": "node1", + "Datacenter": "dc1" } ], "Partition": "ptn1" @@ -113,7 +113,7 @@ The following example policy grants the agent node `write` permission for node ` -```hcl +```hcl node "node1" { policy = "write" } @@ -185,7 +185,7 @@ partition "ptn1" { ### Register policies with Consul -After defining the custom policies, you can register them with Consul using the command line or API endpoint. +After defining the custom policies, you can register them with Consul using the command line or API endpoint. #### CLI @@ -238,7 +238,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ }' ``` -Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. +Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. ### Link custom policies to tokens @@ -250,7 +250,7 @@ Run the `consul acl token create` command and specify the policy name or ID to c ##### Consul OSS -The following command creates the ACL token linked to the policy `node1-register`. +The following command creates the ACL token linked to the policy `node1-register`. ```shell-session $ consul acl token create \ @@ -272,7 +272,7 @@ Send a PUT request to the `/acl/token` endpoint and specify the policy name or I ##### Consul OSS -The following example creates an ACL token that the agent can use to register as node `node1` in the catalog: +The following example creates an ACL token that the agent can use to register as node `node1` in the catalog: ```shell-session $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ @@ -280,10 +280,10 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --data '{ "Policies": [ { - "Name": "node1-register" + "Name": "node1-register" } ] -}' +}' ``` ##### Consul Enterprise @@ -296,24 +296,24 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --data '{ "Policies": [ { - "Name": "node1-register" + "Name": "node1-register" } ], "Partition": "ptn1" -}' +}' ``` @include 'create-token-auth-methods.mdx' -## Apply the token +## Apply the token Configure the Consul agent to present the token by either specifying the token in the agent configuration file or by using the `consul set-agent-token` command. ### Apply the token in a file -Specify the token in the [`acl.token.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) field of the agent configuration file so that the agent can present it and register into the catalog on startup. +Specify the token in the [`acl.token.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) field of the agent configuration file so that the agent can present it and register into the catalog on startup. -```hcl +```hcl acl = { enabled = true tokens = { diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx index 70a1974cfc39..096c79ce5f4d 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: Create a token for ingress gateway registration -Description: >- +description: >- Learn how to create ACL tokens that your ingress gateway can present to Consul servers so that they can register with the Consul catalog. --- From 06da2afc0ac1a5978f8219f611be70585112fab9 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Tue, 9 May 2023 11:31:16 -0500 Subject: [PATCH 03/10] Move permission requirements to requirements --- .../create/create-a-mesh-gateway-token.mdx | 8 +++++++- .../tokens/create/create-a-service-token.mdx | 16 ++++++++++----- .../create-a-terminating-gateway-token.mdx | 20 ++++++++++++------- .../acl/tokens/create/create-a-ui-token.mdx | 4 ++++ .../tokens/create/create-an-agent-token.mdx | 14 +++++++++---- .../create-an-ingress-gateway-token.mdx | 8 +++++++- .../partials/create-token-requirements.mdx | 4 ---- 7 files changed, 52 insertions(+), 22 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx index 189e3c6efd1a..b66bf22a6d9e 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx @@ -11,7 +11,13 @@ This topic describes how to create a token to enable a mesh gateway to register. ## Introduction -Gateways must present a token linked to policies that grant the appropriate set of permissions. For a mesh gateway to be discoverable and to route to other services in a mesh, the token must be linked to policies that grant the following permissions: +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. If you are not using Consul cluster peering, then you can omit the `peering:read` permission. diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index e812c767f238..a7338b1a2854 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -11,11 +11,7 @@ This topic describes how to create a token that you can use to discover services ## Introduction -Services must present a token linked to policies that grant the appropriate set of permissions. For a service to be discoverable or to interact with other services in a mesh, the token must be linked to policies that grant the following permissions: - -* `service:write`: Enables the service to update the catalog. If service mesh is enabled, the service's sidecar proxy can also update the catalog.Note that this permission implicitly grants `intention:read` permission to sidecar proxies so that they can read and enforce intentions. Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for details. -* `service:read`: Enables the service to learn about other services in the network. If service mesh is enabled, the service's sidecar proxy can also learn about other services in the network. -* `node:read`: Enables the sidecar proxy to discover and route traffic to other services in the catalog if service mesh is enabled. +Services must present a token linked to policies that grant the appropriate set of permissions in order to be discoverable or to interact with other services in a mesh. ### Service identities versus custom policies @@ -25,6 +21,16 @@ We recommend using a service identity to grant permissions for service discovery Your organization may have requirements or processes for deploying services in a way that is inconsistent with service and node identities. In these cases, you can create custom policies and link them to tokens. +## Requirements + +Core ACL functionality is available in all versions of Consul. + +The service token must be linked to policies that grant the following permissions: + +* `service:write`: Enables the service to update the catalog. If service mesh is enabled, the service's sidecar proxy can also update the catalog.Note that this permission implicitly grants `intention:read` permission to sidecar proxies so that they can read and enforce intentions. Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for details. +* `service:read`: Enables the service to learn about other services in the network. If service mesh is enabled, the service's sidecar proxy can also learn about other services in the network. +* `node:read`: Enables the sidecar proxy to discover and route traffic to other services in the catalog if service mesh is enabled. + @include 'create-token-requirements.mdx' ## Create tokens linked to service identities diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx index 6f574da5f373..3fcd71a9aec9 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -11,13 +11,7 @@ This topic describes how to create an ACL token that enables a terminating gatew ## Introduction -Gateways must present a token linked to policies that grant the appropriate set of permissions. For a terminating gateway to be discoverable and to forward traffic out of the mesh, the token must be linked to policies that grant the following permissions: - -* `service:write` to allow the terminating gateway to register into the catalog -* `service:write` for each service that it forwards traffic for -* `node:read` for the nodes of each service that it forwards traffic for -* `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. +Gateways must present a token linked to policies that grant the appropriate set of permissions in order to be discoverable and to forward traffic out of the mesh. ### External services @@ -27,6 +21,18 @@ The following policy examples assume the terminating gateway only needs to forwa To learn how to configure terminating gateways, refer to the [Terminating Gateways](/consul/docs/connect/gateways/terminating-gateway#terminating-gateway-configuration) documentation and the [Understand Terminating Gateways](/consul/tutorials/developer-mesh/service-mesh-terminating-gateways) tutorial. +## Requirements + +Core ACL functionality is available in all versions of Consul. + +The terminating gateway token must be linked to policies that grant the following permissions: + +* `service:write` to allow the terminating gateway to register into the catalog +* `service:write` for each service that it forwards traffic for +* `node:read` for the nodes of each service that it forwards traffic for +* `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' ## Create a token linked to a policy diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx index f9dad0ce94d9..9cf40ee2e5e9 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -13,6 +13,10 @@ This topic describes how to create a token that you can use to view resources in 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' ## Create a token with read-only access to the catalog diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx index 123acb6effa9..c7e78b31748c 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx @@ -11,10 +11,7 @@ This topic describes how to create a token that you can use to register an agent ## Introduction -Consul agents must present a token linked to policies that grant the appropriate set of permissions. For an agent to register into the catalog, the token must be linked to policies that grant the following permissions: - -* `node:write`: Enables the agent to update the catalog. -* `service:read`: Enables the agent to discover other services in the catalog +Consul agents must present a token linked to policies that grant the appropriate set of permissions in order to register into the catalog and to discover services and nodes in the catalog. Specify the [`agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) token to the Consul agent so that it can present the token when it registers into the catalog. @@ -26,6 +23,15 @@ We recommend using a node identity to grant permissions to the agent rather than Your organization may have requirements or processes for deploying services in a way that is inconsistent with service and node identities. In these cases, you can create custom policies and link them to tokens. +## Requirements + +Core ACL functionality is available in all versions of Consul. + +The agent token must be linked to policies that grant the following permissions: + +* `node:write`: Enables the agent to update the catalog. +* `service:read`: Enables the agent to discover other services in the catalog + @include 'create-token-requirements.mdx' ## Create tokens linked to node identities diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx index 096c79ce5f4d..12db987e4650 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx @@ -11,7 +11,13 @@ This topic describes how to create a token to enable an ingress gateway to regis ## Introduction -Gateways must present a token linked to policies that grant the appropriate set of permissions. For an ingress gateway to register and to route to other services in a mesh, the token must be linked to policies that grant the following permissions: +Gateways must present a token linked to policies that grant the appropriate set of permissions in order to register into the catalog and to route to other services in a mesh. + +## Requirements + +Core ACL functionality is available in all versions of Consul. + +The ingress gateway token must be linked to policies that grant the following permissions: * `service:write` to allow the ingress 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 diff --git a/website/content/partials/create-token-requirements.mdx b/website/content/partials/create-token-requirements.mdx index 8b55f500517a..bf4742719e8d 100644 --- a/website/content/partials/create-token-requirements.mdx +++ b/website/content/partials/create-token-requirements.mdx @@ -1,7 +1,3 @@ -## Requirements - -Core ACL functionality is available in all versions of Consul. - ### Authentication You must provide an ACL token linked to a policy with `acl:write` permissions to create and modify ACL tokens and policies using the CLI or API. From d4d6ab8568e3358ec1204f8117d70ae776dd8a24 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Tue, 9 May 2023 14:10:51 -0500 Subject: [PATCH 04/10] Restructure create-a-service-token page --- .../tokens/create/create-a-service-token.mdx | 237 +++++++++++------- 1 file changed, 152 insertions(+), 85 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index a7338b1a2854..053b93c70015 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -33,59 +33,75 @@ The service token must be linked to policies that grant the following permission @include 'create-token-requirements.mdx' -## Create tokens linked to service identities +## Create a token linked to a service identity in Consul OSS Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. You can manually create 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. -### CLI + + + Run the `consul acl token create` command and specify the policy or service identity to link to create a token. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command. The following example creates an ACL token linked to a service identity for a service named `svc1`. -#### Consul OSS - ```shell-session $ consul acl token create \ -description "Service token for svc1" \ -service-identity "svc1" ``` -#### Consul Enterprise + -You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: - -```shell-session -$ consul acl token create -partition "ptn1" -namespace "ns1" \ - -description "Service token for svc1" \ - -service-identity "svc1" -``` - -### API + Send a PUT request to the `/acl/token` endpoint and specify a service identity in the request body to create a token linked to the service identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. The following example creates a token linked to a service identity named `svc1`: -#### Consul OSS - ```shell-session $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ --data '{ "ServiceIdentities": [ { - "ServiceName": "svc1", - "Datacenters": ["dc1"] + "ServiceName": "svc1" } ] }' +``` + + + + + +## Create a token linked to a service identity in Consul Enterprise + +Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. + +You can manually create 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. + + + + +Run the `consul acl token create` command and specify the policy or service identity to link to create a token. 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: + +```shell-session +$ consul acl token create -partition "ptn1" -namespace "ns1" \ + -description "Service token for svc1" \ + -service-identity "svc1" ``` -#### Consul Enterprise + + + + +Send a PUT request to the `/acl/token` endpoint and specify a service identity in the request body to create a token linked to the service identity. An ACL token linked to a policy with permissions to use the API endpoint is required. 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: @@ -95,8 +111,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --data '{ "ServiceIdentities": [ { - "ServiceName": "svc1", - "Datacenters": ["dc1"] + "ServiceName": "svc1" } ], "Namespace": "ns1", @@ -104,9 +119,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + -## Create tokens linked to custom policies +## Create a token linked to a custom policy in Consul OSS When you are unable to link tokens to a service identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. @@ -114,8 +131,6 @@ When you are unable to link tokens to a service identity, you can define custom You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. -#### Consul OSS - The following example policy grants the `svc1` service `write` permissions so that it can register into the catalog. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. @@ -160,7 +175,97 @@ node_prefix "" { -#### Consul Enterprise + +### Register the policy with Consul + +After defining the custom policies, you can register them with Consul using the command line or API endpoint. + + + + + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `svc1-register.hcl`: + + +```shell-session +$ consul acl policy create \ + -name "svc1-register" -rules @svc1-register.hcl \ + -description "Allow svc1 to register into the catalog" +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl token create` command. + + + + + +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 custom policy defined in `svc1-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": "svc1-register", + "Description": "Allow svc1 to register into the catalog", + "Rules": "service \"svc1\" {\n policy = \"write\"\n}\nservice \"svc1-sidecar-proxy\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nnode_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. + + + + + +### Link the custom 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. + + + + + +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 commands create the ACL token linked to the policy `svc1-register`. + +```shell-session +$ consul acl token create \ + -description "Service token for svc1" \ + -policy-name "svc1-register" +``` + + + + + +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 the `svc1` service can use to register in the `ns1` namespaces of 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": "svc1-register" + } + ] +}' +``` + + + + + +## Create a token linked to a custom policy in Consul Enterprise + +When you are unable to link tokens to a service identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. + +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example policy allows the `svc1` service to register in the `ns1` namespace of partition `ptn1`. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. @@ -218,23 +323,17 @@ partition "ptn1" { -### Register policies with Consul -After defining the custom policies, you can register them with Consul using the command line or API endpoint. +### Register the policy with Consul -#### CLI +After defining the custom policies, you can register them with Consul using the command line or API endpoint. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `svc1-register.hcl`: + -##### Consul OSS + -```shell-session -$ consul acl policy create \ - -name "svc1-register" -rules @svc1-register.hcl \ - -description "Allow svc1 to register into the catalog" -``` +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `svc1-register.hcl`: -##### Consul Enterprise ```shell-session $ consul acl policy create -partition "ptn1" -namespace "ns1" \ @@ -244,23 +343,11 @@ $ consul acl policy create -partition "ptn1" -namespace "ns1" \ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl token create` command. -#### 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 custom policy defined in `svc1-register.hcl`. You must embed policy rules in the `Rules` field of the request body - -##### Consul OSS + -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Name": "svc1-register", - "Description": "Allow svc1 to register into the catalog", - "Rules": "service \"svc1\" {\n policy = \"write\"\n}\nservice \"svc1-sidecar-proxy\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\n" -}' -``` + -##### Consul Enterprise +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 custom policy defined in `svc1-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 \ @@ -276,25 +363,19 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. -### Link custom policies to tokens + -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. + -#### CLI +### Link the custom policy to a token -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. - -##### Consul OSS +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. -The following commands create the ACL token linked to the policy `svc1-register`. + -```shell-session -$ consul acl token create \ - -description "Service token for svc1" \ - -policy-name "svc1-register" -``` + -##### Consul Enterprise +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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: @@ -306,27 +387,11 @@ $ consul acl token create -partition "ptn1" -namespace "ns1" \ -policy-name "svc1-register" ``` -#### 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. - -##### Consul OSS + -The following example creates an ACL token that the `svc1` service can use to register in the `ns1` namespaces of 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": "svc1-register" - } - ] -}' -``` + -##### Consul Enterprise +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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: @@ -344,4 +409,6 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + From fad7f57d2518d2fbb4e1c06c8dd0ea225375885a Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 10 May 2023 13:57:36 -0500 Subject: [PATCH 05/10] Shorten headings --- .../security/acl/tokens/create/create-a-service-token.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index 053b93c70015..cf9d6cd54748 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -33,7 +33,7 @@ The service token must be linked to policies that grant the following permission @include 'create-token-requirements.mdx' -## Create a token linked to a service identity in Consul OSS +## Service identity in Consul OSS Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. @@ -77,7 +77,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ -## Create a token linked to a service identity in Consul Enterprise +## Service identity in Consul Enterprise Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. @@ -123,7 +123,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ -## Create a token linked to a custom policy in Consul OSS +## Custom policy in Consul OSS When you are unable to link tokens to a service identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. @@ -259,7 +259,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ -## Create a token linked to a custom policy in Consul Enterprise +## Custom policy in Consul Enterprise When you are unable to link tokens to a service identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. From e961d91938970f542d97ac2c89d2cf9703d9c3ff Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 10 May 2023 16:08:06 -0500 Subject: [PATCH 06/10] Restructure pages --- .../create/create-a-mesh-gateway-token.mdx | 289 ++++++++++----- .../create-a-terminating-gateway-token.mdx | 297 ++++++--------- .../acl/tokens/create/create-a-ui-token.mdx | 340 +++++++++++------- .../tokens/create/create-an-agent-token.mdx | 230 +++++++----- .../create-an-ingress-gateway-token.mdx | 170 +++++---- 5 files changed, 779 insertions(+), 547 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx index b66bf22a6d9e..3ce77a9a2180 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx @@ -27,7 +27,8 @@ The mesh gateway must present a token linked to a policy that grants the followi @include 'create-token-requirements.mdx' -## Create a token linked to a policy + +## 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. @@ -35,8 +36,6 @@ To create a token for the mesh gateway, you must define a policy, register the p You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. -#### Consul OSS - The following example policy grants the mesh gateway the appropriate permissions for the mesh gateway to register as a service named `mesh-gateway`. @@ -88,7 +87,93 @@ agent_prefix "" { -#### Consul Enterprise using `default` partition +### 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. + + + + + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`: + +```shell-session +$ consul acl policy create \ + -name "mgw-register" -rules @mgw-register.hcl \ + -description "Mesh gateway policy" +``` + + + + + +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 custom 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. + + + + + +### 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. + + + + + +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" +``` + + + + + +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" + } + ] +}' +``` + + + + + +## 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 custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 policy allows a mesh gateway to register as a service named `mesh-gateway` in the default partition. @@ -161,7 +246,101 @@ namespace_prefix "" { -#### Consul Enterprise using non-`default` partition +### 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. + + + + + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom 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. + + + + + +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 custom 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. + + + + + +### 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. + + + + + +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" +``` + + + + + +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" +}' +``` + + + + + +## 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 custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 ACL policy rules allow a mesh gateway to register as the `mesh-gateway` service in a non-default partition. @@ -225,70 +404,33 @@ namespace_prefix "" { - ### 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. -#### CLI - -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`: + -##### Consul OSS + -```shell-session -$ consul acl policy create \ - -name "mgw-register" -rules @mgw-register.hcl \ - -description "Mesh gateway policy" -``` - -##### Consul Enterprise +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom 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 \ +$ consul acl policy create -partition "ptn1" \ -name mgw-register -rules @mgw-register.hcl \ - -description "Mesh gateway policy" \ - -partition ptn1 + -description "Mesh gateway policy" ``` Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. -#### 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 custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. - -##### Consul OSS - - -```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" -}' -``` - -##### Consul Enterprise (Default Partition) - + -```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" -}' -``` + -##### Consul Enterprise (Non-default Partition) +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 custom 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 \ @@ -303,54 +445,33 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. -### 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. + -#### 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. +### Link the policy to a token -##### Consul OSS +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. -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" -``` + -##### Consul Enterprise +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 \ +$ consul acl token create -partition "ptn1" \ -description "Mesh gateway token" \ -policy-name "mgw-register" ``` -#### 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. + -##### Consul OSS - - -```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" - } - ] -}' -``` - -##### Consul Enterprise +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`. @@ -367,4 +488,6 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx index 3fcd71a9aec9..c34c3b007ea5 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -35,7 +35,7 @@ The terminating gateway token must be linked to policies that grant the followin @include 'create-token-requirements.mdx' -## Create a token linked to a policy +## Consul OSS To create a token for the terminating gateway, you must define a policy, register the policy with Consul, and link the policy to a token. @@ -43,8 +43,6 @@ To create a token for the terminating gateway, you must define a policy, registe You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. -#### Consul OSS - The following example policy allows a terminating gateway to register as a service named `terminating-gateway`. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. @@ -96,90 +94,95 @@ agent_prefix "" { -#### Consul Enterprise using `default` partition and `default` namespace +### Register the policy with Consul -You can specify an admin partition and namespace when using Consul Enterprise. The following example policy allows a terminating gateway to register as a service named `terminating-gateway` in the `default` partition and `default` namespace. +After defining the policy, you can register the policy with Consul using the command line or API endpoint. -For this example, the terminating gateway forwards traffic for the following two services: +The following commands create the ACL policy and token. -* `external-service-1` in the `default` namespace -* `external-service-2` in the `ns1` namespace + - + -```hcl -partition "default" { - namespace "default" { - service "terminating-gateway" { - policy = "write" - } - service "external-service-1" { - policy = "write" - } - node_prefix "" { - policy = "read" - } - agent_prefix "" { - policy = "read" - } - } - namespace "ns1" { - service "external-service-2" { - policy = "write" - } - node_prefix "" { - policy = "read" - } - } -} +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `tgw-register.hcl`: + +```shell-session +$ consul acl policy create \ + -name "tgw-register" -rules @tgw-register.hcl \ + -description "Terminating gateway policy" ``` -```json -{ - "partition": { - "default": [{ - "namespace": { - "default": [{ - "agent_prefix": { - "": [{ - "policy": "read" - }] - }, - "node_prefix": { - "": [{ - "policy": "read" - }] - }, - "service": { - "external-service-1": [{ - "policy": "write" - }], - "terminating-gateway": [{ - "policy": "write" - }] - } - }], - "ns1": [{ - "node_prefix": { - "": [{ - "policy": "read" - }] - }, - "service": { - "external-service-2": [{ - "policy": "write" - }] - } - }] - } - }] - } -} +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + + + + + +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 custom policy defined in `tgw-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": "tgw-register", + "Description": "Terminating gateway policy", + "Rules": "service \"terminating-gateway\" {\n policy = \"write\"\n}\nservice \"external-service-1\" {\n policy = \"write\"\n}\nservice \"external-service-2\" {\n policy = \"write\"\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. + + + + + +### 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. + + + + + +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 `tgw-register`. + +```shell-session +$ consul acl token create \ + -description "Terminating gateway token" \ + -policy-name "tgw-register" +``` + + + + + +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": "tgw-register" + } + ] +}' +``` + + + + + +## Consul Enterprise + +To create a token for the terminating gateway, you must define a policy, register the policy with Consul, and link the policy to a token. -#### Consul Enterprise using a non-`default` partition and non-`default` namespace +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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. The following example policy allows a terminating gateway to register as a service named `terminating-gateway` in namespace `ns1` in partition `ptn1`. @@ -268,33 +271,13 @@ partition "ptn1" { 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. - -#### CLI - -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `tgw-register.hcl`: - -##### Consul OSS - -```shell-session -$ consul acl policy create \ - -name "tgw-register" -rules @tgw-register.hcl \ - -description "Terminating gateway policy" -``` - -##### Consul Enterprise using `default` partition and `default` namespace - -You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. The policy must be created in the partition where the terminating gateway will register. The following example creates the policy in the `default` partition. +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the policy must be created in the `default` namespace. The following example creates the policy in the partition `ptn1` and `default` namespace because the example policy contains permissions for multiple namespaces. -```shell-session -$ consul acl policy create -partition "default" -namespace "default" \ - -name "tgw-register" -rules @tgw-register.hcl \ - -description "Terminating gateway policy" -``` + -##### Consul Enterprise using a non-`default` partition and non-`default` namespace + -You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the policy must be created in the `default` namespace. The following example creates the policy in the partition `ptn1` and `default` namespace because the example policy contains permissions for multiple namespaces. +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `tgw-register.hcl`: ```shell-session $ consul acl policy create -partition "ptn1" -namespace "default" \ @@ -304,41 +287,11 @@ $ consul acl policy create -partition "ptn1" -namespace "default" \ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. -#### 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 custom policy defined in `tgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. - -##### Consul OSS - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Name": "tgw-register", - "Description": "Terminating gateway policy", - "Rules": "service \"terminating-gateway\" {\n policy = \"write\"\n}\nservice \"external-service-1\" {\n policy = \"write\"\n}\nservice \"external-service-2\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nagent_prefix \"\" {\n policy = \"read\"\n}\n" -}' -``` - -##### Consul Enterprise using `default` partition and `default` namespace - -You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway are registered. The following example creates the policy in the `default` partition. - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Name": "tgw-register", - "Description": "Terminating gateway policy", - "Partition": "default", - "Namespace": "default", - "Rules": "partition \"default\" {\n namespace \"default\" {\n service \"terminating-gateway\" {\n policy = \"write\"\n }\n service \"external-service-1\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n agent_prefix \"\" {\n policy = \"read\"\n }\n }\n namespace \"ns1\" {\n service \"external-service-2\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n" -}' -``` + -##### Consul Enterprise using a non-`default` partition and non-`default` namespace + -You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the policy must be created in the default namespace. The following example creates the policy in the partition `ptn1` and `default` namespace because the example policy contains permissions for multiple namespaces. +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 custom policy defined in `tgw-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 \ @@ -354,37 +307,21 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. -### 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. + -#### 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. - -##### Consul OSS - -The following command creates the ACL token linked to the policy `tgw-register`. - -```shell-session -$ consul acl token create \ - -description "Terminating gateway token" \ - -policy-name "tgw-register" -``` +### Link the policy to a token -##### Consul Enterprise using the `default` partition and `default` namespace +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. -You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the same partition where the terminating gateway is registered. The following example creates the token in the partition `default` and namespace `default`. +You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the token must be created in the `default` namespace. The following example creates the token in the `default` namespace in the `ptn1` partition because the example policy contains permissions for multiple namespaces. -```shell-session -$ consul acl token create -partition "default" -namespace "default" \ - -description "Terminating gateway token" \ - -policy-name "tgw-register" -``` + -##### Consul Enterprise using a non-`default` partition and non-`default` namespace + -You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the same partition where the terminating gateway is registered. The following example creates the token in the partition `ptn1` and namespace `default`. +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 "ptn1" -namespace "default" \ @@ -392,45 +329,11 @@ $ consul acl token create -partition "ptn1" -namespace "default" \ -policy-name "tgw-register" ``` -#### 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. + -##### Consul OSS - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Policies": [ - { - "Name": "tgw-register" - } - ] -}' -``` - -##### Consul Enterprise using the `default` partition and `default` namespace - -You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. The following example creates the token in the partition `ptn1` and namespace `default`. - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Policies": [ - { - "Name": "tgw-register" - } - ], - "Partition": "default", - "Namespace": "default" -}' -``` - -##### Consul Enterprise using a non-`default` partition and non-`default` namespace - -You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the token must be created in the `default` namespace. The following example creates the token in the `default` namespace in the `ptn1` partition because the example policy contains permissions for multiple namespaces. +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 \ @@ -446,4 +349,6 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx index 9cf40ee2e5e9..3e268ed0dd89 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -19,7 +19,7 @@ Core ACL functionality is available in all versions of Consul. @include 'create-token-requirements.mdx' -## Create a token with read-only access to the catalog +## View catalog in Consul OSS 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. @@ -27,8 +27,6 @@ This section describes how to create a token that grants read-only access to the You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. -#### Consul OSS - The following policy allows you to view all services and nodes in the catalog. @@ -59,7 +57,93 @@ node_prefix "" { -#### Consul Enterprise +### Register policies with Consul + +After defining the policies, you can register them with Consul using the command line or API endpoint. + + + + + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom 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" +``` + +efer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + + + + + +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 custom 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" +}' +``` + + + + + +### Link custom policies to tokens + +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. + + + + + +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" +``` + + + + + +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" + } + ] +}' +``` + + + + + +## 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 custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 policy allows users that log in with the token to view services and nodes in the catalog in any partition and in any namespace. @@ -111,19 +195,11 @@ partition_prefix "" { After defining the policies, you can register them with Consul using the command line or API endpoint. -#### CLI - -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-catalog.hcl`. - -##### Consul OSS + -```shell-session -$ consul acl policy create \ - -name "ui-view-catalog" -rules @ui-view-catalog.hcl \ - -description "Allow viewing the catalog" -``` + -##### Consul Enterprise +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-catalog.hcl`. You can specify an admin partition, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the network areas 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. @@ -137,23 +213,11 @@ $ consul acl policy create -partition "default" -namespace "default" \ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. -#### 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 custom policy defined in `view-catalog.hcl`. You must embed the policy rules in the `Rules` field of the request body. - -##### Consul OSS + -```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" -}' -``` + -##### Consul Enterprise +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 custom 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 \ @@ -167,25 +231,19 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ }' ``` -### Link custom policies to tokens - -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. + -#### 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. +### Link custom policies to tokens -##### Consul OSS +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. -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" -``` + -##### Consul Enterprise +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" \ @@ -193,27 +251,11 @@ $ consul acl token create -partition "default" -namespace "default" \ -policy-name "ui-view-catalog" ``` -#### 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. - -##### Consul OSS + -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" - } - ] -}' -``` + -##### Consul Enterprise +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, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the network areas 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. @@ -233,9 +275,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + -## Create a token with read-only access to all resources + + +## View all resources in Consul OSS 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. @@ -243,8 +287,6 @@ This section describes how to create a token with read-only access to all resour You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. -#### Consul OSS - The following policy allows viewing 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. @@ -289,7 +331,93 @@ service_prefix "" { -#### Consul Enterprise +### Register policies with Consul + +After defining the policies, you can register them with Consul using the command line or API endpoint. + + + + + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom 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. + + + + + +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 custom 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" +}' +``` + + + + + +### Link custom policies to tokens + +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. + + + + + +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" +``` + + + + + +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" + } + ] +}' +``` + + + + + +## 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 custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. 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 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. @@ -351,19 +479,11 @@ partition_prefix "" { After defining the policies, you can register them with Consul using the command line or API endpoint. -#### CLI - -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-all.hcl`. - -##### Consul OSS + -```shell-session -$ consul acl policy create \ - -name "ui-view-all" -rules @ui-view-all.hcl \ - -description "Allow viewing all resources" -``` + -##### Consul Enterprise +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-all.hcl`. You can specify an admin partition, namespace, or both when creating policies in Consul Enterprise. The policy is only valid in the specified network areas. Because the policy grants cross-partition and cross-namespace access, the policy must be created in the `default` partition and the `default` namespace. @@ -375,23 +495,11 @@ $ consul acl policy create -partition "default" -namespace "default" \ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. -#### 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 custom policy defined in `ui-view-all.hcl`. You must embed the policy rules in the `Rules` field of the request body. - -##### Consul OSS + -```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" -}' -``` + -##### Consul Enterprise +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 custom 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 \ @@ -405,25 +513,19 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ }' ``` -### Link custom policies to tokens - -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. + -#### 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. +### Link custom policies to tokens -##### Consul OSS +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. -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" -``` + -##### Consul Enterprise +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" \ @@ -431,27 +533,11 @@ $ consul acl token create -partition "default" -namespace "default" \ -policy-name "ui-view-all" ``` -#### 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. + -##### Consul OSS + -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" - } - ] -}' -``` - -##### Consul Enterprise +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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. 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. @@ -469,4 +555,6 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx index c7e78b31748c..cfcd3ebecb43 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx @@ -34,17 +34,17 @@ The agent token must be linked to policies that grant the following permissions: @include 'create-token-requirements.mdx' -## Create tokens linked to node identities +## Node identity in Consul OSS Refer to [Node identities](/consul/docs/security/acl#node-identities) for information about node identities that you can link to tokens. You can manually create 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. -### CLI + -Run the `consul acl token create` command and specify the policy or node identity to link to create a token. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command. + -#### Consul OSS +Run the `consul acl token create` command and specify the policy or node identity to link to create a token. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command. The following command creates an ACL token linked to a node identity for a node named `node1` in the datacenter `dc1`. @@ -54,24 +54,14 @@ $ consul acl token create \ -node-identity "node1:dc1" ``` -#### Consul Enterprise + -You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in partition `ptn1` in datacenter `dc1`: - -```shell-session -$ consul acl token create -partition "ptn1" \ - -description "Agent token for node1" \ - -node-identity "node1:dc1" -``` - -### API + Send a PUT request to the `/acl/token` endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint. The following example creates a token linked to a node identity named `node1`: -#### Consul OSS - ```shell-session $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ @@ -85,7 +75,35 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -#### Consul Enterprise + + + + +## Node identity in Consul Enterprise + +Refer to [Node identities](/consul/docs/security/acl#node-identities) for information about node identities that you can link to tokens. + +You can manually create 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. + + + + + +Run the `consul acl token create` command and specify the policy or node identity to link to create a token. 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 following example creates an ACL token that the agent can use to register in partition `ptn1` in datacenter `dc1`: + +```shell-session +$ consul acl token create -partition "ptn1" \ + -description "Agent token for node1" \ + -node-identity "node1:dc1" +``` + + + + + +Send a PUT request to the `/acl/token` endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. 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 a token in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in the partition `ptn1` in datacenter `dc1`: @@ -103,9 +121,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + -## Create tokens linked to custom policies +## Custom policy in Consul OSS When you are unable to link tokens to a node identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog. @@ -113,8 +133,6 @@ When you are unable to link tokens to a node identity, you can define custom pol You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. -#### Consul OSS - The following example policy grants the agent node `write` permission for node `node1` so that it can register into the catalog. It grants service `read` permissions to discover services in the catalog. @@ -145,7 +163,97 @@ service_prefix "" { -#### Consul Enterprise +### Register the policy with Consul + +After defining the custom policies, you can register them with Consul using the command line or API endpoint. + + + + + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `node1-register.hcl`: + +```shell-session +$ consul acl policy create \ + -name "node1-register" -rules @node1-register.hcl \ + -description "Custom policy for node1" \ +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + + + + + +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 custom policy defined in `node1-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": "node1-register", + "Description": "Allow node1 to register into the catalog", + "Rules": "node \"node1\" {\n policy = \"write\"\n}\nservice_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. + + + + + +### Link the custom 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. + + + + + +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 `node1-register`. + +```shell-session +$ consul acl token create \ + -description "Agent token for node1" \ + -policy-name "node1-register" +``` + + + + + +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 the agent can use to register as node `node1` in 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": "node1-register" + } + ] +}' +``` + + + + + + + +## Custom policy in Consul Enterprise + +When you are unable to link tokens to a node identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog. + +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 grants the `node1` node `write` permission to register in the partition `ptn1`. It grants service `read` permissions for any service in any namespace in the `ptn1` partition. @@ -193,19 +301,11 @@ partition "ptn1" { After defining the custom policies, you can register them with Consul using the command line or API endpoint. -#### CLI - -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `node1-register.hcl`: - -##### Consul OSS + -```shell-session -$ consul acl policy create \ - -name "node1-register" -rules @node1-register.hcl \ - -description "Custom policy for node1" \ -``` + -##### Consul Enterprise +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `node1-register.hcl`: ```shell-session $ consul acl policy create -partition "ptn1" \ @@ -215,23 +315,11 @@ $ consul acl policy create -partition "ptn1" \ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. -#### 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 custom policy defined in `node1-register.hcl`. You must embed policy rules in the `Rules` field of the request body. - -##### Consul OSS + -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Name": "node1-register", - "Description": "Allow node1 to register into the catalog", - "Rules": "node \"node1\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\n" -}' -``` + -##### Consul Enterprise +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 custom policy defined in `node1-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 \ @@ -246,25 +334,19 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. -### Link custom policies to tokens + -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. + -#### CLI +### Link custom policies to tokens -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. +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 OSS + -The following command creates the ACL token linked to the policy `node1-register`. + -```shell-session -$ consul acl token create \ - -description "Agent token for node1" \ - -policy-name "node1-register" -``` - -##### Consul Enterprise +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 "ptn1" \ @@ -272,27 +354,11 @@ $ consul acl token create -partition "ptn1" \ -policy-name "node1-register" ``` -#### 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. - -##### Consul OSS + -The following example creates an ACL token that the agent can use to register as node `node1` in 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": "node1-register" - } - ] -}' -``` + -##### Consul Enterprise +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 following example creates an ACL token that the agent can use to register as the node `node1` in the partition `ptn1`: @@ -309,7 +375,9 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + ## Apply the token diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx index 12db987e4650..cc881eda5812 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx @@ -25,7 +25,7 @@ The ingress gateway token must be linked to policies that grant the following pe @include 'create-token-requirements.mdx' -## Create a token linked to a policy +## Consul OSS To create a token for the ingress gateway, you must define a policy, register the policy with Consul, and link the policy to a token. @@ -33,8 +33,6 @@ To create a token for the ingress gateway, you must define a policy, register th You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies. -#### Consul OSS - The following example policy grants the ingress gateway the appropriate permissions to register as a service named `ingress-gateway`. @@ -81,7 +79,95 @@ agent_prefix "" { -#### Consul Enterprise +### 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. + + + + + +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `igw-register.hcl`: + +```shell-session +$ consul acl policy create \ + -name "igw-register" -rules @igw-register.hcl \ + -description "Ingress gateway policy" +``` + +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. + + + + + +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 custom policy defined in `igw-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": "igw-register", + "Description": "Ingress gateway policy", + "Rules": "service \"ingress-gateway\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nservice_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. + + + + + +### 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. + + + + + +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 `igw-register`. + +```shell-session +$ consul acl token create \ + -description "Ingress gateway token" \ + -policy-name "igw-register" +``` + + + + + +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": "igw-register" + } + ] +}' +``` + + + + + +## Consul Enterprise + +To create a token for the ingress gateway, you must define a policy, register the policy with Consul, and link the policy to a token. + +### Define a custom policy + +You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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. The following policy allows an ingress gateway to register as a service named `ingress-gateway` in the `ptn1` partition and `ns1` namespace. @@ -153,19 +239,11 @@ After defining the policy, you can register the policy with Consul using the com The following commands create the ACL policy and token. -#### CLI - -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `igw-register.hcl`: - -##### Consul OSS + -```shell-session -$ consul acl policy create \ - -name "igw-register" -rules @igw-register.hcl \ - -description "Ingress gateway policy" -``` + -##### Consul Enterprise +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `igw-register.hcl`: You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. The following example creates the policy in the `default` namespace in the `ptn1` partition. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. @@ -177,23 +255,11 @@ $ consul acl policy create -partition "ptn1" -namespace "default" \ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. -#### 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 custom policy defined in `igw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. - -##### Consul OSS + -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Name": "igw-register", - "Description": "Ingress gateway policy", - "Rules": "service \"ingress-gateway\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nagent_prefix \"\" {\n policy = \"read\"\n}\n" -}' -``` + -##### Consul Enterprise +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 custom policy defined in `igw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition `ptn1` and namespace `ns1`. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. @@ -211,25 +277,19 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint. -### 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. + -#### 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. +### Link the policy to a token -##### Consul OSS +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. -The following command creates the ACL token linked to the policy `igw-register`. + -```shell-session -$ consul acl token create \ - -description "Ingress gateway token" \ - -policy-name "igw-register" -``` + -##### Consul Enterprise +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 and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition `ptn1` and namespace `default`. The example policy contains permissions for resources in multiple namespaces. You must create ACL tokens linked to policies that grant permissions for multiple namespaces in the `default` namespace. @@ -239,25 +299,11 @@ $ consul acl token create -partition "ptn1" -namespace "default" \ -policy-name "igw-register" ``` -#### 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. - -##### Consul OSS - -```shell-session -$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ - --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ - --data '{ - "Policies": [ - { - "Name": "igw-register" - } - ] -}' -``` + -##### Consul Enterprise +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. You must create the token in the partition where the ingress gateway is registered. The following example creates the token in the partition `ptn1` and namespace `default`. @@ -275,4 +321,6 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ }' ``` -@include 'create-token-auth-methods.mdx' + + + From 7e7acea42968aa9a7d9b3d225a0479bd8205b140 Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 10 May 2023 16:59:19 -0500 Subject: [PATCH 07/10] Address feedback --- .../create/create-a-mesh-gateway-token.mdx | 137 ++++++++++-------- .../tokens/create/create-a-service-token.mdx | 32 ++-- .../create-a-terminating-gateway-token.mdx | 16 +- .../acl/tokens/create/create-a-ui-token.mdx | 40 ++--- .../tokens/create/create-an-agent-token.mdx | 30 ++-- .../create-an-ingress-gateway-token.mdx | 16 +- 6 files changed, 141 insertions(+), 130 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx index 3ce77a9a2180..eafb384dbd8a 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx @@ -2,16 +2,22 @@ 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. + 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 to enable a mesh gateway to register. +This topic describes how to create a token for a mesh gateway. ## Introduction -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. +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 @@ -20,21 +26,24 @@ 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. If you are not using Consul cluster peering, then you can omit the `peering:read` permission. +* `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. +* `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 custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 grants the mesh gateway the appropriate permissions for the mesh gateway to register as a service named `mesh-gateway`. @@ -97,7 +106,7 @@ The following commands create the ACL policy and token. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`: +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 \ @@ -109,7 +118,7 @@ $ consul acl policy create \ -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 custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 \ @@ -171,9 +180,9 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ 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 custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 policy allows a mesh gateway to register as a service named `mesh-gateway` in the default partition. @@ -181,24 +190,25 @@ You can specify an admin partition and namespace when using Consul Enterprise. M ```hcl mesh = "write" -peering = "read" partition_prefix "" { peering = "read" } -namespace "default" { - service "mesh-gateway" { - policy = "write" - } - agent_prefix "" { - policy = "read" - } -} -namespace_prefix "" { - node_prefix "" { - policy = "read" +partition "default" { + namespace "default" { + service "mesh-gateway" { + policy = "write" + } + agent_prefix "" { + policy = "read" + } } - service_prefix "" { - policy = "read" + namespace_prefix "" { + node_prefix "" { + policy = "read" + } + service_prefix "" { + policy = "read" + } } } ``` @@ -206,38 +216,41 @@ namespace_prefix "" { ```json { "mesh": "write", - "peering": "read", - "partition_prefix": { - "": [{ - "peering": "read" - }] - }, - "namespace": { + "partition": { "default": [{ - "agent_prefix": { - "": [{ - "policy": "read" + "namespace": { + "default": [{ + "service": { + "mesh-gateway": [{ + "policy": "write" + }] + }, + "agent_prefix": { + "": [{ + "policy": "read" + }] + } }] }, - "service": { - "mesh-gateway": [{ - "policy": "write" + "namespace_prefix": { + "": [{ + "node_prefix": { + "": [{ + "policy": "read" + }] + }, + "service_prefix": { + "": [{ + "policy": "read" + }] + } }] } }] }, - "namespace_prefix": { + "partition_prefix": { "": [{ - "node_prefix": { - "": [{ - "policy": "read" - }] - }, - "service_prefix": { - "": [{ - "policy": "read" - }] - } + "peering": "read" }] } } @@ -256,7 +269,7 @@ The following commands create the ACL policy and token. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`: +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. @@ -272,7 +285,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 \ @@ -338,9 +351,9 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ 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 custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 ACL policy rules allow a mesh gateway to register as the `mesh-gateway` service in a non-default partition. @@ -348,7 +361,6 @@ You can specify an admin partition and namespace when using Consul Enterprise. M ```hcl mesh = "write" -peering = "read" namespace "default" { service "mesh-gateway" { policy = "write" @@ -370,18 +382,17 @@ namespace_prefix "" { ```json { "mesh": "write", - "peering": "read", "namespace": { "default": [{ - "agent_prefix": { - "": [{ - "policy": "read" - }] - }, "service": { "mesh-gateway": [{ "policy": "write" }] + }, + "agent_prefix": { + "": [{ + "policy": "read" + }] } }] }, @@ -414,7 +425,7 @@ The following commands create the ACL policy and token. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `mgw-register.hcl`: +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`. @@ -430,7 +441,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `mgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 \ diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index cf9d6cd54748..f4fe571058f8 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -7,7 +7,7 @@ description: >- # Create a service token -This topic describes how to create a token that you can use to discover services and to register services into the Consul catalog. If you are using Consul service mesh, this token can be used by a sidecar proxy to discover and route to other services. +This topic describes how to create a token that you can use to register a service and discover services in the Consul catalog. If you are using Consul service mesh, this token can be used by a sidecar proxy to discover and route to other services. ## Introduction @@ -27,7 +27,7 @@ Core ACL functionality is available in all versions of Consul. The service token must be linked to policies that grant the following permissions: -* `service:write`: Enables the service to update the catalog. If service mesh is enabled, the service's sidecar proxy can also update the catalog.Note that this permission implicitly grants `intention:read` permission to sidecar proxies so that they can read and enforce intentions. Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for details. +* `service:write`: Enables the service to update the catalog. If service mesh is enabled, the service's sidecar proxy can also update the catalog. Note that this permission implicitly grants `intention:read` permission to sidecar proxies so that they can read and enforce intentions. Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for details. * `service:read`: Enables the service to learn about other services in the network. If service mesh is enabled, the service's sidecar proxy can also learn about other services in the network. * `node:read`: Enables the sidecar proxy to discover and route traffic to other services in the catalog if service mesh is enabled. @@ -125,11 +125,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ ## Custom policy in Consul OSS -When you are unable to link tokens to a service identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. +When you are unable to link tokens to a service identity, you can define policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 grants the `svc1` service `write` permissions so that it can register into the catalog. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. @@ -178,13 +178,13 @@ node_prefix "" { ### Register the policy with Consul -After defining the custom policies, you can register them with Consul using the command line or API endpoint. +After defining the policies, you can register them with Consul using the command line or API endpoint. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `svc1-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `svc1-register.hcl`: ```shell-session @@ -199,7 +199,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `svc1-register.hcl`. You must embed policy rules in the `Rules` field of the request body +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 `svc1-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 \ @@ -217,7 +217,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf -### Link the custom policy to a token +### 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. @@ -261,11 +261,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ ## Custom policy in Consul Enterprise -When you are unable to link tokens to a service identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. +When you are unable to link tokens to a service identity, you can define policies, register them with Consul, and link the policies to tokens that enable services to register into the Consul catalog. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example policy allows the `svc1` service to register in the `ns1` namespace of partition `ptn1`. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. @@ -326,13 +326,13 @@ partition "ptn1" { ### Register the policy with Consul -After defining the custom policies, you can register them with Consul using the command line or API endpoint. +After defining the policies, you can register them with Consul using the command line or API endpoint. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `svc1-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `svc1-register.hcl`: ```shell-session @@ -347,7 +347,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `svc1-register.hcl`. You must embed policy rules in the `Rules` field of the request body +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 `svc1-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 \ @@ -367,7 +367,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf -### Link the custom policy to a token +### 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. diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx index c34c3b007ea5..087f66b243a5 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -39,9 +39,9 @@ The terminating gateway token must be linked to policies that grant the followin To create a token for the terminating gateway, you must define a policy, register the policy with Consul, and link the policy to a token. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 allows a terminating gateway to register as a service named `terminating-gateway`. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. @@ -104,7 +104,7 @@ The following commands create the ACL policy and token. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `tgw-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `tgw-register.hcl`: ```shell-session $ consul acl policy create \ @@ -118,7 +118,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `tgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 `tgw-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 \ @@ -180,9 +180,9 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ To create a token for the terminating gateway, you must define a policy, register the policy with Consul, and link the policy to a token. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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. The following example policy allows a terminating gateway to register as a service named `terminating-gateway` in namespace `ns1` in partition `ptn1`. @@ -277,7 +277,7 @@ You can specify an admin partition and namespace when creating policies in Consu -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `tgw-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `tgw-register.hcl`: ```shell-session $ consul acl policy create -partition "ptn1" -namespace "default" \ @@ -291,7 +291,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `tgw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 `tgw-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 \ diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx index 3e268ed0dd89..e20813c8a40a 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -25,7 +25,7 @@ This section describes how to create a token that grants read-only access to the ### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 policy allows you to view all services and nodes in the catalog. @@ -57,7 +57,7 @@ node_prefix "" { -### Register policies with Consul +### Register the policy with Consul After defining the policies, you can register them with Consul using the command line or API endpoint. @@ -65,7 +65,7 @@ After defining the policies, you can register them with Consul using the command -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-catalog.hcl`. +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 \ @@ -79,7 +79,7 @@ efer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for detai -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 custom policy defined in `view-catalog.hcl`. You must embed the policy rules in the `Rules` field of the request body. +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 \ @@ -95,7 +95,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ -### Link custom policies to tokens +### 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. @@ -143,7 +143,7 @@ This section describes how to create a token that grants read-only access to the ### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 policy allows users that log in with the token to view services and nodes in the catalog in any partition and in any namespace. @@ -191,7 +191,7 @@ partition_prefix "" { -### Register policies with Consul +### Register the policy with Consul After defining the policies, you can register them with Consul using the command line or API endpoint. @@ -199,7 +199,7 @@ After defining the policies, you can register them with Consul using the command -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-catalog.hcl`. +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, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the network areas 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. @@ -217,7 +217,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `view-catalog.hcl`. You must embed the policy rules in the `Rules` field of the request body. +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 \ @@ -235,7 +235,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ -### Link custom policies to tokens +### 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. @@ -285,7 +285,7 @@ This section describes how to create a token with read-only access to all resour ### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 policy allows viewing 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. @@ -331,7 +331,7 @@ service_prefix "" { -### Register policies with Consul +### Register the policy with Consul After defining the policies, you can register them with Consul using the command line or API endpoint. @@ -339,7 +339,7 @@ After defining the policies, you can register them with Consul using the command -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-all.hcl`. +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 \ @@ -353,7 +353,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `ui-view-all.hcl`. You must embed the policy rules in the `Rules` field of the request body. +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 \ @@ -369,7 +369,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ -### Link custom policies to tokens +### 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. @@ -417,7 +417,7 @@ This section describes how to create a token with read-only access to all resour ### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies represent externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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. @@ -475,7 +475,7 @@ partition_prefix "" { -### Register policies with Consul +### Register the policy with Consul After defining the policies, you can register them with Consul using the command line or API endpoint. @@ -483,7 +483,7 @@ After defining the policies, you can register them with Consul using the command -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `ui-view-all.hcl`. +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, namespace, or both when creating policies in Consul Enterprise. The policy is only valid in the specified network areas. Because the policy grants cross-partition and cross-namespace access, the policy must be created in the `default` partition and the `default` namespace. @@ -499,7 +499,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `ui-view-all.hcl`. You must embed the policy rules in the `Rules` field of the request body. +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 \ @@ -517,7 +517,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ -### Link custom policies to tokens +### 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. diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx index cfcd3ebecb43..0a45da314f3a 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx @@ -127,11 +127,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ ## Custom policy in Consul OSS -When you are unable to link tokens to a node identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog. +When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 grants the agent node `write` permission for node `node1` so that it can register into the catalog. It grants service `read` permissions to discover services in the catalog. @@ -165,13 +165,13 @@ service_prefix "" { ### Register the policy with Consul -After defining the custom policies, you can register them with Consul using the command line or API endpoint. +After defining the policies, you can register them with Consul using the command line or API endpoint. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `node1-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `node1-register.hcl`: ```shell-session $ consul acl policy create \ @@ -185,7 +185,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `node1-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 `node1-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 \ @@ -203,7 +203,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf -### Link the custom policy to a token +### 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. @@ -249,11 +249,11 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ ## Custom policy in Consul Enterprise -When you are unable to link tokens to a node identity, you can define custom policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog. +When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 grants the `node1` node `write` permission to register in the partition `ptn1`. It grants service `read` permissions for any service in any namespace in the `ptn1` partition. @@ -297,15 +297,15 @@ partition "ptn1" { -### Register policies with Consul +### Register the policy with Consul -After defining the custom policies, you can register them with Consul using the command line or API endpoint. +After defining the policies, you can register them with Consul using the command line or API endpoint. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `node1-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `node1-register.hcl`: ```shell-session $ consul acl policy create -partition "ptn1" \ @@ -319,7 +319,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `node1-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 `node1-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 \ @@ -338,7 +338,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf -### Link custom policies to tokens +### 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. diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx index cc881eda5812..9a7772ff1d5b 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx @@ -29,9 +29,9 @@ The ingress gateway token must be linked to policies that grant the following pe To create a token for the ingress gateway, you must define a policy, register the policy with Consul, and link the policy to a token. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 grants the ingress gateway the appropriate permissions to register as a service named `ingress-gateway`. @@ -89,7 +89,7 @@ The following commands create the ACL policy and token. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `igw-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `igw-register.hcl`: ```shell-session $ consul acl policy create \ @@ -103,7 +103,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `igw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 `igw-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 \ @@ -165,9 +165,9 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ To create a token for the ingress gateway, you must define a policy, register the policy with Consul, and link the policy to a token. -### Define a custom policy +### Define a policy -You can send custom policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policies are externally defined policies. 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 send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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. The following policy allows an ingress gateway to register as a service named `ingress-gateway` in the `ptn1` partition and `ns1` namespace. @@ -243,7 +243,7 @@ The following commands create the ACL policy and token. -Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a custom policy defined in `igw-register.hcl`: +Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `igw-register.hcl`: You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. The following example creates the policy in the `default` namespace in the `ptn1` partition. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. @@ -259,7 +259,7 @@ Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for deta -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 custom policy defined in `igw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. +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 `igw-register.hcl`. You must embed policy rules in the `Rules` field of the request body. You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition `ptn1` and namespace `ns1`. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. From 582a1cee3e7e055339f58881f6bde82635446deb Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 14 Jun 2023 08:48:16 -0500 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Co-authored-by: Jared Kirschner <85913323+jkirschner-hashicorp@users.noreply.github.com> --- .../acl/tokens/create/create-a-service-token.mdx | 4 ++-- .../create/create-a-terminating-gateway-token.mdx | 10 ++-------- .../security/acl/tokens/create/create-a-ui-token.mdx | 4 ++-- 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index f4fe571058f8..5da26fad2854 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -7,7 +7,7 @@ description: >- # Create a service token -This topic describes how to create a token that you can use to register a service and discover services in the Consul catalog. If you are using Consul service mesh, this token can be used by a sidecar proxy to discover and route to other services. +This topic describes how to create a token that you can use to register a service and discover services in the Consul catalog. If you are using Consul service mesh, a sidecar proxy can use the token to discover and route traffic to other services. ## Introduction @@ -89,7 +89,7 @@ You can manually create tokens using the Consul command line or API endpoint. Yo Run the `consul acl token create` command and specify the policy or service identity to link to create a token. 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: +You can specify an admin partition, namespace, or both when creating tokens in Consul Enterprise. The token can only include permissions in the specified scope, if any. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: ```shell-session $ consul acl token create -partition "ptn1" -namespace "ns1" \ diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx index 087f66b243a5..89a6d3b46ee8 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -11,21 +11,15 @@ This topic describes how to create an ACL token that enables a terminating gatew ## Introduction -Gateways must present a token linked to policies that grant the appropriate set of permissions in order to be discoverable and to forward traffic out of the mesh. - -### External services - Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to services and destinations outside the mesh. -The following policy examples assume the terminating gateway only needs to forward traffic to two external services named `external-service-1` and `external-service-2`. The policy examples include `service:write` permissions for these two services. If you have additional services, `service:write` permissions for those services also need to be included in the policy rules. - To learn how to configure terminating gateways, refer to the [Terminating Gateways](/consul/docs/connect/gateways/terminating-gateway#terminating-gateway-configuration) documentation and the [Understand Terminating Gateways](/consul/tutorials/developer-mesh/service-mesh-terminating-gateways) tutorial. ## Requirements Core ACL functionality is available in all versions of Consul. -The terminating gateway token must be linked to policies that grant the following permissions: +The terminating gateway token must be linked to policies that grant the appropriate set of permissions in order to be discoverable and to forward traffic out of the mesh. The following permissions are required: * `service:write` to allow the terminating gateway to register into the catalog * `service:write` for each service that it forwards traffic for @@ -43,7 +37,7 @@ To create a token for the terminating gateway, you must define a policy, registe You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 allows a terminating gateway to register as a service named `terminating-gateway`. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. +The following example policy allows a terminating gateway to register as a service named `terminating-gateway`. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules. diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx index e20813c8a40a..1788d1ee45d5 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -73,7 +73,7 @@ $ consul acl policy create \ -description "Allow viewing the catalog" ``` -efer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. +Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command. @@ -287,7 +287,7 @@ This section describes how to create a token with read-only access to all resour You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 policy allows viewing 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. +The following 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. From 4641a38cf1e25f41248510b1d3cb1433a6c4ba8b Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 14 Jun 2023 09:01:53 -0500 Subject: [PATCH 09/10] "Define a policy" wording feedback --- .../create/create-a-mesh-gateway-token.mdx | 16 ++++++----- .../tokens/create/create-a-service-token.mdx | 16 ++++++----- .../create-a-terminating-gateway-token.mdx | 14 ++++++---- .../acl/tokens/create/create-a-ui-token.mdx | 27 +++++++++---------- .../tokens/create/create-an-agent-token.mdx | 8 +++--- .../create-an-ingress-gateway-token.mdx | 10 +++---- 6 files changed, 49 insertions(+), 42 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx index eafb384dbd8a..a8a5bb8e9f5e 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx @@ -43,9 +43,9 @@ To create a token for the mesh gateway, you must define a policy, register the p ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 grants the mesh gateway the appropriate permissions for the mesh gateway to register as a service named `mesh-gateway`. +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. @@ -182,9 +182,11 @@ To create a token for the mesh gateway, you must define a policy, register the p ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 policy allows a mesh gateway to register as a service named `mesh-gateway` in the default partition. +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. @@ -353,9 +355,11 @@ To create a token for the mesh gateway, you must define a policy, register the p ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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. -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 ACL policy rules allow a mesh gateway to register as the `mesh-gateway` service in a non-default partition. +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. diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index 5da26fad2854..02864b9a3c13 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -103,7 +103,7 @@ $ consul acl token create -partition "ptn1" -namespace "ns1" \ Send a PUT request to the `/acl/token` endpoint and specify a service identity in the request body to create a token linked to the service identity. An ACL token linked to a policy with permissions to use the API endpoint is required. 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: +You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: ```shell-session $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ @@ -129,9 +129,9 @@ When you are unable to link tokens to a service identity, you can define policie ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 grants the `svc1` service `write` permissions so that it can register into the catalog. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. +The following example policy is defined in a file. The policy grants the `svc1` service `write` permissions so that it can register into the catalog. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. @@ -265,9 +265,11 @@ When you are unable to link tokens to a service identity, you can define policie ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example policy allows the `svc1` service to register in the `ns1` namespace of partition `ptn1`. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes. + +The following example policy is defined in a file. The policy allows the `svc1` service to register in the `ns1` namespace of partition `ptn1`. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services. @@ -377,7 +379,7 @@ After registering the policies into Consul, you can create and link tokens using 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: +You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: The following commands create the ACL token linked to the policy `svc1-register`. @@ -393,7 +395,7 @@ $ consul acl token create -partition "ptn1" -namespace "ns1" \ 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: +You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`: ```shell-session $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx index 89a6d3b46ee8..4cbeec4f9f77 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -35,9 +35,9 @@ To create a token for the terminating gateway, you must define a policy, registe ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 allows a terminating gateway to register as a service named `terminating-gateway`. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules. +The following example policy is defined in a file. The policy grants the appropriate permissions to register as a service named `terminating-gateway` and to operate as a terminating gateway. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules. @@ -176,16 +176,20 @@ To create a token for the terminating gateway, you must define a policy, registe ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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. The following example policy allows a terminating gateway to register as a service named `terminating-gateway` in namespace `ns1` in partition `ptn1`. +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes. + +The following example policy is defined in a file. The policy grants the appropriate permissions for a terminating gateway to register as a service named `terminating-gateway` in namespace `ns1` in partition `ptn1`. For this example, the terminating gateway forwards traffic for the following two services: * `external-service-1` in the `default` namespace * `external-service-2` in the `ns1` namespace -The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. +The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules. + +The policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx index 1788d1ee45d5..ab41f6e6cf3f 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -25,9 +25,9 @@ This section describes how to create a token that grants read-only access to the ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 policy allows you to view all services and nodes in the catalog. +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. @@ -143,12 +143,9 @@ This section describes how to create a token that grants read-only access to the ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 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. +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. @@ -201,7 +198,7 @@ After defining the policies, you can register them with Consul using the command 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, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the network areas 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. +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. @@ -257,7 +254,7 @@ $ consul acl token create -partition "default" -namespace "default" \ 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, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the network areas 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. +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. @@ -285,9 +282,9 @@ This section describes how to create a token with read-only access to all resour ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 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. +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. @@ -417,9 +414,9 @@ This section describes how to create a token with read-only access to all resour ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 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. +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. @@ -485,7 +482,7 @@ After defining the policies, you can register them with Consul using the command 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, namespace, or both when creating policies in Consul Enterprise. The policy is only valid in the specified network areas. Because the policy grants cross-partition and cross-namespace access, the policy must be created in the `default` partition and the `default` namespace. +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" \ @@ -539,7 +536,7 @@ $ consul acl token create -partition "default" -namespace "default" \ 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, namespace, or both when creating tokens in Consul Enterprise. The token is only valid in the specified network areas. 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. +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 \ diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx index 0a45da314f3a..0b4e978b78aa 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx @@ -131,9 +131,9 @@ When you are unable to link tokens to a node identity, you can define policies, ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 grants the agent node `write` permission for node `node1` so that it can register into the catalog. It grants service `read` permissions to discover services in the catalog. +The following example policy is defined in a file. The policy grants `write` permission for node `node1` so that the Consul agent can register into the catalog. It grants `read` permissions to discover services in the catalog. @@ -253,9 +253,9 @@ When you are unable to link tokens to a node identity, you can define policies, ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 grants the `node1` node `write` permission to register in the partition `ptn1`. It grants service `read` permissions for any service in any namespace in the `ptn1` partition. +The following example policy is defined in a file. The policy grants the `write` permission for node `node1` in partition `ptn1` so that the Consul agent can register into the catalog. It grants `read` permissions to discover services in any namespace in the `ptn1` partition. diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx index 9a7772ff1d5b..93ad6a0d38be 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx @@ -31,9 +31,9 @@ To create a token for the ingress gateway, you must define a policy, register th ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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 grants the ingress gateway the appropriate permissions to register as a service named `ingress-gateway`. +The following example policy is defined in a file. The policy grants the ingress gateway the appropriate permissions to register as a service named `ingress-gateway` and to operate as an ingress gateway. @@ -167,11 +167,11 @@ To create a token for the ingress gateway, you must define a policy, register th ### Define a policy -You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. The following example policy is defined in a 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 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. The following policy allows an ingress gateway to register as a service named `ingress-gateway` in the `ptn1` partition and `ns1` namespace. +You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes. -The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. +The following example policy is defined in a file. The policy allows an ingress gateway to register as a service named `ingress-gateway` in the `ptn1` partition and `ns1` namespace. The policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace. From ed96efac66a067fb7362c7ba625233fe79c2fa2f Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 14 Jun 2023 09:02:07 -0500 Subject: [PATCH 10/10] Link to auth method docs --- .../acl/tokens/create/create-a-mesh-gateway-token.mdx | 6 +++--- .../security/acl/tokens/create/create-a-service-token.mdx | 8 ++++---- .../tokens/create/create-a-terminating-gateway-token.mdx | 4 ++-- .../docs/security/acl/tokens/create/create-a-ui-token.mdx | 8 ++++---- .../security/acl/tokens/create/create-an-agent-token.mdx | 8 ++++---- .../acl/tokens/create/create-an-ingress-gateway-token.mdx | 4 ++-- 6 files changed, 19 insertions(+), 19 deletions(-) diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx index a8a5bb8e9f5e..9736beb50d9e 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx @@ -138,7 +138,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). @@ -308,7 +308,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). @@ -466,7 +466,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx index 02864b9a3c13..125390b39830 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx @@ -37,7 +37,7 @@ The service token must be linked to policies that grant the following permission Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. -You can manually create 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. +You can manually create 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). @@ -81,7 +81,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. -You can manually create 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. +You can manually create 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). @@ -219,7 +219,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). @@ -371,7 +371,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx index 4cbeec4f9f77..5ba304a9f84b 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx @@ -132,7 +132,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). @@ -311,7 +311,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the token must be created in the `default` namespace. The following example creates the token in the `default` namespace in the `ptn1` partition because the example policy contains permissions for multiple namespaces. diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx index ab41f6e6cf3f..9c1e9019b5e7 100644 --- a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx @@ -97,7 +97,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ ### 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. +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). @@ -234,7 +234,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ ### 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. +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). @@ -368,7 +368,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ ### 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. +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). @@ -516,7 +516,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \ ### 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. +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). diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx index 0b4e978b78aa..598db91125f2 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx @@ -38,7 +38,7 @@ The agent token must be linked to policies that grant the following permissions: Refer to [Node identities](/consul/docs/security/acl#node-identities) for information about node identities that you can link to tokens. -You can manually create 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. +You can manually create 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). @@ -83,7 +83,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ Refer to [Node identities](/consul/docs/security/acl#node-identities) for information about node identities that you can link to tokens. -You can manually create 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. +You can manually create 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). @@ -205,7 +205,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). @@ -340,7 +340,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx index 93ad6a0d38be..65e01369966a 100644 --- a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx +++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx @@ -123,7 +123,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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). @@ -283,7 +283,7 @@ Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional inf ### 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. +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).