NET-1825: New ACL token creation docs

website/content/docs/security/acl/tokens/create-a-service-token.mdx

@@ -0,0 +1,375 @@
+---
+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 and its sidecar proxy, if service mesh is enabled, to 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 and its sidecar proxy, if service mesh is enabled, to 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.
+
+## 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=<acl-token-secret-id>
+```
+
+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" ...
+```
+
+The examples described in this topic exclude the headers for brevity. 
+
+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)
+
+## 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  <EnterpriseAlert inline />
+
+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  <EnterpriseAlert inline />
+
+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"
+}'
+```
+
+### 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.
+
+## 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.
+
+
+<CodeTabs> 
+
+```hcl
+service "svc1" {
+  policy = "write"
+}
+service "svc1-sidecar-proxy" {
+  policy = "write"
+}
+service_prefix "" {
+  policy = "read"
+}
+node_prefix "" {
+  policy = "read"
+}
+```
+
+```json
+{
+  "service": {
+    "svc1": {
+      "policy": "write"
+    },
+    "svc1-sidecar-proxy": {
+      "policy": "write"
+    }
+  },
+  "service_prefix": {
+    "": {
+      "policy": "read"
+    }
+  },
+  "node_prefix": {
+    "": {
+      "policy": "read"
+    }
+  }
+}
+```
+
+</CodeTabs>
+
+#### Consul Enterprise <EnterpriseAlert inline />
+
+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.
+
+<CodeTabs>
+
+```hcl
+partition "ptn1" {
+  namespace "ns1" {
+    service "svc1" {
+      policy = "write"
+    }
+    service "svc1-sidecar-proxy" {
+      policy = "write"
+    }
+    service_prefix "" {
+      policy = "read"
+    }
+    node_prefix "svc1" {
+      policy = "read"
+    }
+  }
+}
+```
+
+```json
+{
+  "partition": {
+    "ptn1": {
+      "namespace": {
+        "ns1": {
+          "service": {
+            "svc1": {
+              "policy": "write"
+            },
+            "svc1-sidecar-proxy": {
+              "policy": "write"
+            }
+          },
+          "service_prefix": {
+            "": {
+              "policy": "read"
+            }
+          },
+          "node_prefix": {
+            "": {
+              "policy": "read"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+</CodeTabs>
+
+### 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 <EnterpriseAlert inline />
+
+```
+consul acl policy create \
+  -name svc1-register -rules @svc1-register.hcl \
+  -description "Custom policy for service svc1" \
+  -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 <EnterpriseAlert inline />
+
+```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 \"svc1\" {\n      policy = \"read\"\n    }\n  }\n}\n",
+
+}'
+```
+
+Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policy) 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-policy`. 
+
+```shell-session
+$ consul acl token create -description "Service token for svc1" \
+  -policy-name svc1-register
+```
+
+##### Consul Enterprise <EnterpriseAlert inline />
+
+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-policy`.
+
+```shell-session
+consul acl token create partition ptn1 -namespace ns1 \ 
+  -description "Service token for svc1" \
+  -policy-name sv1-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 <EnterpriseAlert inline />
+
+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 \
+  --data '{
+  "Policies": [
+    { 
+      "Name": "svc1-register" 
+    } 
+  ], 
+  "Namespace": "ns1",
+  "Partition": "ptn1"
+}'
+```
+
+#### 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.

website/data/docs-nav-data.json

@@ -748,7 +748,21 @@
           },
           {
             "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-a-service-token"
+                  }
+                ]
+              }
+            ]
           },
           {
             "title": "Policies",