From ed8aa7d24a4014e3a45287a53b98b0a90ef46ee4 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Tue, 8 Mar 2022 14:04:46 -0800 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Chris S. Kim --- website/content/docs/security/acl/acl-policies.mdx | 10 +++++----- website/content/docs/security/acl/acl-roles.mdx | 9 +++++---- website/content/docs/security/acl/acl-rules.mdx | 2 +- website/content/docs/security/acl/acl-tokens.mdx | 6 +++--- website/content/docs/security/acl/index.mdx | 2 +- 5 files changed, 15 insertions(+), 14 deletions(-) diff --git a/website/content/docs/security/acl/acl-policies.mdx b/website/content/docs/security/acl/acl-policies.mdx index 6c4114c0b..b164e25f0 100644 --- a/website/content/docs/security/acl/acl-policies.mdx +++ b/website/content/docs/security/acl/acl-policies.mdx @@ -113,7 +113,7 @@ Use the `policy` keyword and one of the following access levels to set a policy - `write`: Allows the resource to be read and modified. - `deny`: Denies read and write access to the resource. -The special `list` access level provices access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/options#acl_enable_key_list_policy) setting must be set to `true`. +The special `list` access level provides access to all keys with the specified resource label in the Consul KV. The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/options#acl_enable_key_list_policy) setting must be set to `true`. ### Matching and Prefix Values @@ -198,7 +198,7 @@ When using prefix-based rules, the most specific prefix match determines the act - A rule that denies access to a specific resource label - A prefix-based rule that allows write access to a class of resources -- An empty prefix that grants read-only access to all resource within the declared class +- An empty prefix that grants read-only access to all resources within the declared class #### Matching Precedence @@ -286,8 +286,8 @@ operator = "read" The rules from all policies, including roles and service identities, linked with a token are combined to form that token's effective rule set. Policy rules can be defined in either an `allowlist` or `denylist` mode, depending on the configuration of the [`acl_default_policy`](/docs/agent/options#acl_default_policy). -If the default policy is configured to deny access to all resources, then policy rules can be set to `allowlist` access to specific resources. -If the default policy is to allow then access to all resources, policy rules can be used to explicitly deny access to resources. +If the default policy is configured to deny access to all resources, then you can specify `allowlist` in policy rules to explicitly allow access to resources. +Conversely, if the default policy is configured to allow access to all resources, then you can specify `denylist` in policy rules to explicitly deny access to resources. ## Implementing Policies @@ -424,7 +424,7 @@ The `Hash`, `CreateIndex`, and `ModifyIndex` attributes are also printed. These ## Built-in Policies -New installations of Consul ship with the following built-ib policies. +New installations of Consul ship with the following built-in policies. ### Global Management diff --git a/website/content/docs/security/acl/acl-roles.mdx b/website/content/docs/security/acl/acl-roles.mdx index b975c938e..263228667 100644 --- a/website/content/docs/security/acl/acl-roles.mdx +++ b/website/content/docs/security/acl/acl-roles.mdx @@ -3,7 +3,7 @@ layout: docs page_title: Roles description: >- This topic describes roles within the access control list (ACL) system. A role is a named set of policies and service identities. - They are intended to + They enable you to reuse policies by decoupling the policies from the token distributed to team members. --- # Roles @@ -15,7 +15,7 @@ As a result, roles can provide a more convenient authentication infrastrcture th ## Workflow Overview -Roles are configurations link several policies to a token. The following procedure describes the workflow for implementing roles. +Roles are configurations linking several policies to a token. The following procedure describes the workflow for implementing roles. 1. Assemble rules into policies (see [Policies](/docs/security/acl/acl-policies)) and register them in Consul. 1. Define a role and include the policy IDs or names. @@ -64,7 +64,8 @@ Roles may contain the following table describe the attributes: - `Policies`: Specifies a the list of policies that are applicable for the role. The object can reference the policy `ID` or `Name` attribute. - `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 this policy resides within. Roles can only be linked to policies that are defined in the same namespace and admin partition. See [Namespaces](/docs/enterprise/namespaces) and [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.7.0+. +- `Namespace`: The namespace that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See [Namespaces](/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](/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.10.0+. ## Service Identities @@ -361,7 +362,7 @@ node "node-1" { } # Allows the agent to detect and diff services registered to itself. This is used during -# anti-entropy to reconcile difference between the agents knowledge of registered +# anti-entropy to reconcile differences between the agent's knowledge of registered # services and checks in comparison with what is known in the Catalog. service_prefix "" { policy = "read" diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index ab16f14dd..ddce746cc 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -7,7 +7,7 @@ description: >- # Rules Reference -This topic provides reference information for the types of access control level (ACL) rules you can create and how they affect access to datacenter resources. For details on how to create rules and group them into policies, see [Policies](/docs/security/acl/acl-policies). +This topic provides reference information for the types of access control list (ACL) rules you can create and how they affect access to datacenter resources. For details on how to create rules and group them into policies, see [Policies](/docs/security/acl/acl-policies). ## Overview diff --git a/website/content/docs/security/acl/acl-tokens.mdx b/website/content/docs/security/acl/acl-tokens.mdx index cedb2cf29..c9831bf5d 100644 --- a/website/content/docs/security/acl/acl-tokens.mdx +++ b/website/content/docs/security/acl/acl-tokens.mdx @@ -13,19 +13,19 @@ This topic describes access control list (ACL) tokens, which are the core method Tokens are artifacts in the ACL system used to authenticate users, services, and Consul agents. When ACLs are enabled, entities requesting access to a resource must include a token that has been linked with a policy, service identity, or node identity that grants permission to the resource. The ACL system checks the token and grants or denies access to resource based on the associated permissions. -Refer to the [ACL system workflow overview](/docs/security/acl/acl-system#workflow-overview) for an information about tokens' role in the ACL system. +Refer to the [ACL system workflow overview](/docs/security/acl/acl-system#workflow-overview) for information about tokens' role in the ACL system. ## 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 ](/api-docs/acl) and [ACL CLI](/commands/acl) documentation for instructions on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an +Refer to the [ACL API](/api-docs/acl) and [ACL CLI](/commands/acl) documentation for instructions on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an [auth method](/docs/security/acl/auth-methods). ## Passing Tokens Users deploying their services into the network or performing some operations in the Consul command line or GUI will need to include the value of the token's `SecretID` attribute. The `SecretID` is often referred to as the ACL token. It is an opaque string that identifies the requester so that the ACL system can determine if access to the requested resource should be granted or denied. -Tokens have several additional attributes. Refer to the (see [Token Attributes](#token-attributes)). +Tokens have several additional attributes. Refer to [Token Attributes](#token-attributes) for details. ### Service Requests diff --git a/website/content/docs/security/acl/index.mdx b/website/content/docs/security/acl/index.mdx index cc0be021f..197d63250 100644 --- a/website/content/docs/security/acl/index.mdx +++ b/website/content/docs/security/acl/index.mdx @@ -47,7 +47,7 @@ Refer to the following topics for details about tokens: ## Policies -An ACL policy is a set of rules grant or deny access to resources in the network. +An ACL policy is a set of rules that grant or deny access to resources in the network. The person responsible for administrating ACLs in your organization will assemble and create policies and link them to tokens. Tokens are the artifacts distributed to users so that they can be implemented. In addition to the rules that authenticate access to services, several attributes may be assigned policies that determine their scope.