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

425 lines
16 KiB
Markdown
Raw Blame History

---
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 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
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.
### Templated policies versus custom policies
You can create tokens linked to custom policies or to templated policies. [Templated policies](/consul/docs/security/acl#templated-policies) are constructs in Consul that enable you to quickly grant permissions for common use cases, rather than creating similar policies.
We recommend using the `builtin/service` templated policy to grant permissions for service discovery and service mesh use cases rather than creating a custom policy. This is because the `builtin/service` templated policy 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 the `builtin/service` templated policy. 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'
## Templated policies in Consul CE
Refer to [Templated policies](/consul/docs/security/acl#templated-policies) for information about creating templated policies 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](/consul/docs/security/acl/auth-methods).
<Tabs>
<Tab heading="CLI" group="CLI">
Run the `consul acl token create` command and specify a templated policy 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 the `builtin/service` templated policy for a service named `svc1`.
```shell-session
$ consul acl token create \
-description "Service token for svc1" \
-templated-policy "builtin/service" \
-var "name:api"
```
</Tab>
<Tab heading="API" group="API">
Send a PUT request to the `/acl/token` endpoint and specify a templated policy in the request body to create a token linked to the templated policy. 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 the `builtin/service` templated policy for a service named `svc1`:
```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"TemplatedPolicies": [
{
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "svc1"
}
}
]
}'
```
</Tab>
</Tabs>
## Templated policies in Consul Enterprise <EnterpriseAlert inline />
Refer to [Templated policies](/consul/docs/security/acl#templated-policies) for information about the use of templated policies in tokens and roles.
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).
<Tabs>
<Tab heading="CLI" group="CLI">
Run the `consul acl token create` command and specify the policy or templated policy 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 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" \
-description "Service token for svc1" \
-templated-policy "builtin/service"
-var "name:svc1"
```
</Tab>
<Tab heading="API" group="API">
Send a PUT request to the `/acl/token` endpoint and specify a policy or templated policy in the request body to create a token linked to the templated policy. 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 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 \
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"TemplatedPolicies": [
{
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "svc1"
}
}
],
"Namespace": "ns1",
"Partition": "ptn1"
}'
```
</Tab>
</Tabs>
## Custom policy in Consul CE
When you are unable to link tokens to a templated policy, 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 policy
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
The following example policy is defined in a file. The policy grants the `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
{
"node_prefix": {
"": [{
"policy": "read"
}]
},
"service": {
"svc1": [{
"policy": "write"
}],
"svc1-sidecar-proxy": [{
"policy": "write"
}]
},
"service_prefix": {
"": [{
"policy": "read"
}]
}
}
```
</CodeTabs>
### Register the policy with Consul
After defining the policies, you can register them with Consul using the command line or API endpoint.
<Tabs>
<Tab heading="CLI" group="CLI">
Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `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.
</Tab>
<Tab heading="API" group="API">
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in `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.
</Tab>
</Tabs>
### Link the policy to a token
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
<Tabs>
<Tab heading="CLI" group="CLI">
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
The following 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"
```
</Tab>
<Tab heading="API" group="API">
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
The following example creates an ACL token that 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"
}
]
}'
```
</Tab>
</Tabs>
## Custom policy in Consul Enterprise <EnterpriseAlert inline/>
When you are unable to link tokens to a templated policy, 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 policy
You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.
You can specify an admin partition and namespace when 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.
<CodeTabs>
```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"
}]
}
}]
}
}]
}
}
```
</CodeTabs>
### Register the policy with Consul
After defining the policies, you can register them with Consul using the command line or API endpoint.
<Tabs>
<Tab heading="CLI" group="CLI">
Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `svc1-register.hcl`:
```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.
</Tab>
<Tab heading="API" group="API">
Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in `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",
"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.
</Tab>
</Tabs>
### Link the policy to a token
After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).
<Tabs>
<Tab heading="CLI" group="CLI">
Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.
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`.
```shell-session
$ consul acl token create -partition "ptn1" -namespace "ns1" \
-description "Service token for svc1" \
-policy-name "svc1-register"
```
</Tab>
<Tab heading="API" group="API">
Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.
You can specify an admin partition 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 \
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"Policies": [
{
"Name": "svc1-register"
}
],
"Namespace": "ns1",
"Partition": "ptn1"
}'
```
</Tab>
</Tabs>
Reference in New Issue View Git Blame Copy Permalink