diff --git a/website/content/docs/security/acl/acl-roles.mdx b/website/content/docs/security/acl/acl-roles.mdx index 6f094931ee2d..5812703831de 100644 --- a/website/content/docs/security/acl/acl-roles.mdx +++ b/website/content/docs/security/acl/acl-roles.mdx @@ -12,7 +12,7 @@ They enable you to reuse policies by decoupling the policies from the token dist Instead, the token is linked to the role, which is able to hold several policies that can be updated asynchronously without distributing new tokens to users. As a result, roles can provide a more convenient authentication infrastructure than creating unique policies and tokens for each requester. -## Workflow Overview +## Workflow overview Roles are configurations linking several policies to a token. The following procedure describes the workflow for implementing roles. @@ -21,19 +21,20 @@ Roles are configurations linking several policies to a token. The following proc 1. Register the role in Consul and link it to a token. 1. Distribute the tokens to users for implementation. -## Creating Roles +## Creating roles Creating roles is commonly the responsibility of the Consul ACLs administrator. Roles have several attributes, including service identities and node identities. Refer to the following documentation for details: - [Role Attributes](#role-attributes) +- [Templated Policies](#templated-policies) - [Service Identities](#service-identities) - [Node Identities](#node-identities) Use the Consul command line or API endpoint to create roles. -### Command Line +### Command line Issue the `consul acl role create` command to create roles. In the following example, a role named `crawler` is created that contains a policy named `crawler-kv` and a policy named `crawler-key`. @@ -53,7 +54,7 @@ $ curl --request PUT --data @payload.json http://127.0.0.1:8500/v1/acl/role Refer to the [API documentation](/consul/api-docs/acl/roles) for details. -## Role Attributes +## Role attributes Roles may contain the following attributes: @@ -61,20 +62,118 @@ Roles may contain the following attributes: - `Name`: A unique meaningful name for the role. You can specify the role `Name` when linking it to tokens. - `Description`: (Optional) A human-readable description of the role. - `Policies`: Specifies a the list of policies that are applicable for the role. The object can reference the policy `ID` or `Name` attribute. +- `TemplatedPolicies`: Specifies a list of templated polcicies that are applicable for the role. See [Templated Policies](#templated-policies) for details. - `ServiceIdentities`: Specifies a list of services that are applicable for the role. See [Service Identities](#service-identities) for details. - `NodeIdentities`: Specifies a list of nodes that are applicable for the role. See [Node Identities](#node-identities) for details. - `Namespace`: The namespace that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See [Namespaces](/consul/docs/enterprise/namespaces) for additional information. Requires Consul Enterprise 1.7.0+ - `Partition`: The admin partition that the policy resides in. Roles can only be linked to policies that are defined in the same admin partition. See [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.10.0+. -## Service Identities +## Templated policies + +You can specify a templated policy when configuring roles or linking tokens to policies. Templated policies enable you to quickly construct policies for common Consul use cases, rather than creating identical policies for each use cases. + +Consul uses templated policies during the authorization process to automatically generate a policy for the use case specified. Consul links the generated policy to the role or token so that it will have permission for the specific use case. + +### Templated policy specification + +The following templated policy example configuration uses the `builtin/service` templated policy to give a service named `api` and its sidecar proxy the required permissions to register into the catalog. + +```json +{ + "TemplatedPolicies": [ + { + "TemplateName": "builtin/service", + "TemplateVariables": { + "Name": "api" + } + } + ] +} +``` + +- `TemplatedPolicies`: Declares a templated policy block. +- `TemplatedPolicies.TemplateName`: String value that specifies the name of the templated policy you want to use. +- `TemplatedPolicies.TemplateVariables`: Map that specifies the required variables for the templated policies. This field is optional as not all templated policies require variables. + +Refer to the [API documentation for roles](/consul/api-docs/acl/roles#sample-payload) for additional information and examples. + +-> In Consul Enterprise, templated policies inherit the namespace or admin partition scope of the corresponding ACL token or role. - +The `builtin/service` sample templated policy generates the following policy for a service named `api`: + +```hcl +# Allow the service and its sidecar proxy to register into the catalog. +service "api" { + policy = "write" +} +service "api-sidecar-proxy" { + policy = "write" +} + +# Allow for any potential upstreams to be resolved. +service_prefix "" { + policy = "read" +} +node_prefix "" { + policy = "read" +} +``` + +Refer to the [rules reference](/consul/docs/security/acl/acl-rules) for information about the rules in the policy. + +### Example + +The following role configuration contains a templated policy that gives the role required permission for a service named `web` to register itself and its sidecar into the catalog. + + + +```json +{ + "Name": "example-role", + "Description": "Showcases all input parameters", + "TemplatedPolicies": [ + { + "TemplateName": "builtin/service", + "TemplateVariables": { + "Name": "web" + } + } + ] +} +``` + + + +During the authorization process, Consul generates the following policies for the `web` services and links it to the token: + + + +```hcl +# Allow the service and its sidecar proxy to register into the catalog. +service "web" { + policy = "write" +} +service "web-sidecar-proxy" { + policy = "write" +} + +# Allow for any potential upstreams to be resolved. +service_prefix "" { + policy = "read" +} +node_prefix "" { + policy = "read" +} +``` + + +## Service Identities You can specify a service identity when configuring roles or linking tokens to policies. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service. Service identities are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. Refer to the [service mesh](/consul/docs/connect) topic for additional information about Consul service mesh. -### Service Identity Specification +### Service identity specification Use the following syntax to define a service identity: @@ -211,7 +310,7 @@ You can specify a node identity when configuring roles or linking tokens to poli Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) field when configuring the agent. -### Node Identity Specification +### Node identity specification Use the following syntax to define a node identity: @@ -299,4 +398,4 @@ service_prefix "" { } ``` - + \ No newline at end of file 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 25a3eb700c17..8f17df702d80 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 @@ -13,13 +13,13 @@ This topic describes how to create a token that you can use to register a servic 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 +### Templated policies 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. +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 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`. +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 service and node identities. In these cases, you can create custom policies and link them to tokens. +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 @@ -33,9 +33,9 @@ The service token must be linked to policies that grant the following permission @include 'create-token-requirements.mdx' -## Service identity in Consul CE +## Templated policies in Consul CE -Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service identities that you can link to tokens. +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). @@ -43,31 +43,35 @@ 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. +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 a service identity for a service named `svc1`. +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" \ - -service-identity "svc1" + -templated-policy "builtin/service" \ + -var "name: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. +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 a service identity named `svc1`: +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 '{ - "ServiceIdentities": [ + "TemplatedPolicies": [ { - "ServiceName": "svc1" + "TemplateName": "builtin/service", + "TemplateVariables": { + "Name": "svc1" + } } ] }' @@ -77,9 +81,9 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ -## Service identity in Consul Enterprise +## Templated policies 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. +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). @@ -87,21 +91,22 @@ 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. +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" \ - -service-identity "svc1" + -templated-policy "builtin/service" + -var "name:svc1" ``` -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. +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`: @@ -109,9 +114,12 @@ You can specify an admin partition and namespace when creating tokens in Consul $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \ --data '{ - "ServiceIdentities": [ + "TemplatedPolicies": [ { - "ServiceName": "svc1" + "TemplateName": "builtin/service", + "TemplateVariables": { + "Name": "svc1" + } } ], "Namespace": "ns1", @@ -125,7 +133,7 @@ $ curl --request PUT http://127.0.0.1:8500/v1/acl/token \ ## Custom policy in Consul CE -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. +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 @@ -261,7 +269,7 @@ $ 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 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 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 diff --git a/website/content/docs/security/acl/tokens/index.mdx b/website/content/docs/security/acl/tokens/index.mdx index e0ad114e5324..0c57cbbe38f7 100644 --- a/website/content/docs/security/acl/tokens/index.mdx +++ b/website/content/docs/security/acl/tokens/index.mdx @@ -15,7 +15,7 @@ Tokens are artifacts in the ACL system used to authenticate users, services, and Refer to the [ACL system workflow overview](/consul/docs/security/acl#workflow-overview) for information about tokens' role in the ACL system. -## Creating Tokens +## Creating tokens The person responsible for administrating ACLs can use the API or CLI to create and link tokens to entities that enable permissions to resources. Refer to the [ACL API](/consul/api-docs/acl) and [ACL CLI](/consul/commands/acl) documentation for instructions on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an @@ -29,7 +29,7 @@ Users deploying their services into the network or performing some operations in Tokens have several additional attributes. Refer to [Token Attributes](#token-attributes) for details. -### Service Requests +### Service requests Specify the value of the `SecretID` attribute with the `token` parameter when configuring your services. In the following example service configuration, the `token` has been included as a string parameter to the `redis` service: @@ -66,7 +66,7 @@ service = { Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference) for additional information. -### Agent Requests +### Agent requests Consul agents can be configured to hold several ACL tokens (see [`tokens`](/consul/docs/agent/config/config-files#acl_tokens_default)) to accommodate several use cases. The following table describes agent configuration fields where ACLs are applicable and whether the configurations apply to servers, clients, or both. @@ -101,7 +101,7 @@ tokens = { Refer to the [agent configurations documentation](/consul/docs/agent/config/config-files) for additional information. -### Command Line Requests +### Command line requests To make a request on the command line, specify the ACL token with the [`-token` command line flag](/consul/commands#authentication). In the following example, a token is included to enable the user to create an intention on the command line: @@ -112,11 +112,11 @@ $ consul intention create -file one.json two.json -token "233b604b-b92e-48c8-a25 Refer to the documentation for the command line operations you want to perform for additional information. -#### Environment Variables +#### Environment variables You can export tokens to environment variables on the local machine, which enable you to omit the `-token` flag when performing operations on the Consul command line. Refer to the [Consul command line documentation](/consul/commands#environment-variables) for details. -### API Requests +### API requests Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/consul/api-docs/api-structure#authentication) for details. @@ -126,25 +126,26 @@ The following example shows the header for a GET request to the `agent/members` $ curl --header "X-Consul-Token: " "http://127.0.0.1:8500/v1/agent/members" ``` -## Token Attributes +## Token attributes The following table is a partial list of attributes that a token may contain. Refer to the [API](/consul/api-docs/acl/tokens) or [command line](/consul/commands/acl/token) documentation for all attributes that can be assigned or generated for a token: | Attribute | Description | Type | Default | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | -| `AccessorID` | Used for [audit logging](/consul/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated | +| `AccessorID` | Used for [audit logging](/consul/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated | | `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated | -| `Partition` | Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information. | String | `default` | -| `Namespace` | Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/consul/docs/enterprise/namespaces) for additional information. | String | `default` | +| `Partition` | Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information. | String | `default` | +| `Namespace` | Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/consul/docs/enterprise/namespaces) for additional information. | String | `default` | | `Description` | Human-readable description for documenting the purpose of the token. | String | none | | `Local` | Indicates whether the token should be replicated globally or local to the datacenter.
Set to `false` to replicate globally across all reachable datacenters.
Setting to `true` configures the token to functional in the local datacenter only. | Boolean | `false` | -| `ServiceIdentities` | Specifies a list of service identities to apply to the token. See [Service Identities](/consul/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none | -| `NodeIdentities` | Specifies a list of node identities to apply to the token. See [Node Identities](/consul/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none | +| `TemplatedPolicies` | Specifies a list of templated policies to apply to the token. See [Templated Policies](/consul/docs/security/acl/acl-roles#templated-policies) in the "Roles" topic for additional information. | Array | none | +| `ServiceIdentities` | Specifies a list of service identities to apply to the token. See [Service Identities](/consul/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none | +| `NodeIdentities` | Specifies a list of node identities to apply to the token. See [Node Identities](/consul/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none | | `Policies` | List of policies linked to the token, including the policy ID and name. | String | none | -| `Roles` | List of roles linked to the token, including the role ID and name. | String | none | +| `Roles` | List of roles linked to the token, including the role ID and name. | String | none | -## Special-purpose Tokens +## Special-purpose tokens Your ACL administrator can configure several tokens that enable specific functions, such as bootstrapping the ACL system or accessing Consul under specific conditions. The following table describes the special-purpose tokens: @@ -158,11 +159,11 @@ system or accessing Consul under specific conditions. The following table descri All reserved tokens except the `initial_management` token can be created or updated using the [/v1/agent/token API](/consul/api-docs/agent#update-acl-tokens). -### Snapshot Tokens +### Snapshot tokens Snapshots are artifacts created with the [snapshot API](/consul/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and interacting with them requires a token with `acl:write` privileges. -### ACL Agent Token +### ACL agent token The [`acl.tokens.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default), though if the `acl.tokens.agent` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: @@ -190,11 +191,11 @@ key_prefix "_rexec" { The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/consul/docs/agent/config/config-files#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. -## Built-in Tokens +## Built-in tokens Consul includes a built-in anonymous token and initial management token. Both tokens are injected during when you bootstrap the cluster. -### Anonymous Token +### Anonymous token The anonymous token is used when a request is made to Consul without specifying a bearer token. This token has the following attributes (see [Token Attributes](#token-attributes) for additional information): @@ -204,7 +205,7 @@ This token has the following attributes (see [Token Attributes](#token-attribute The description and policies may be updated, but the anonymous token cannot be deleted. -### Initial Management Token +### Initial management token Including an initial management token in the Consul configuration creates the token and links it with the built-in [global management](/consul/docs/security/acl/acl-policies#global-management) policy. @@ -217,7 +218,7 @@ See the [Bootstrapping ACLs tutorial](/consul/tutorials/security/access-control- In Consul 1.4 - 1.10, this was called the `master` token. It was renamed to `initial_management` token in Consul 1.11. --> -### ACL Agent Recovery Token +### ACL agent recovery token The [`acl.tokens.agent_recovery`](/consul/docs/agent/config/config-files#acl_tokens_agent_recovery) is designed to be used when the Consul servers are not available. The policy linked to the token is managed locally on the agent and does not require a token to be defined on the Consul servers. Once set, it implicitly has the following policy associated with it