From 595701e5bfb4814ce29bdf4ea2bb016f8cb65909 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 16 Dec 2021 17:24:46 -0800 Subject: [PATCH] ACL system docs updates re: admin partitions in Consul v1.11.0 --- .../content/docs/security/acl/acl-system.mdx | 122 ++++++++++++++---- 1 file changed, 99 insertions(+), 23 deletions(-) diff --git a/website/content/docs/security/acl/acl-system.mdx b/website/content/docs/security/acl/acl-system.mdx index 927e0838d2..7de5783a22 100644 --- a/website/content/docs/security/acl/acl-system.mdx +++ b/website/content/docs/security/acl/acl-system.mdx @@ -69,16 +69,53 @@ If the ACL system becomes inoperable, you can follow the ### ACL Policies -An ACL policy is a named set of rules and is composed of the following elements: - -- **ID** - The policy's auto-generated public identifier. -- **Name** - A unique meaningful name for the policy. -- **Description** - A human readable description of the policy. (Optional) -- **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules#rule-specification) documentation for more details. -- **Datacenters** - A list of datacenters the policy is valid within. -- **Namespace** - - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) +An ACL policy (not to be confused with [policy dispositions](/docs/security/acl/acl-rules#policy-dispositions)) is a named set of rules and several attributes that define the policy domain. The ID is generated when policy is created, but you can specify the attributes when creating the policy. Refer to the [ACL policy command line](https://www.consul.io/commands/acl/policy) documentation or [ACL policy API](/api-docs/acl/policies) documentation for additional information on how to create policies. + +ACL policies can have the following attributes: + +| Attribute | Description | Required | Default | +| --- | --- | --- | --- | +| `ID` | The policy's auto-generated public identifier. | N/A | N/A | +| `name` | Unique name for the policy. | Required | none | +| `description` | Human readable description of the policy. | Optional | none | +| `rules` | Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules#rule-specification) documentation for more details. | Optional | none | +| `datacenter` | Datacenter in which the policy is valid. More than one datacenter can be specified. | Optional | none | +| `namespace` | Namespace in which the policy is valid. Added in Consul Enterprise 1.7.0. | Optional | `default` | +| `partition` | Admin partition in which the policy is valid. Added in Consul Enterprise 1.11.0 | Optional | `default` | + +-> **Non-default Namespaces and Partitions** - Rules defined in a policy tied to an namespace or admin partition other than `default` can only grant a subset of privileges that affect the namespace or partition. See [Namespace Rules](/docs/acl/acl-rules#namespace-rules) and [Admin Partition Rules](/docs/acl/acl-rules#admin-partition-rules) for additional information. + +You can view the current ACL policies on the command line or through the API. The following example demonstrates the command line usage: + +```shell-session +$ consul acl policy list -format json -token +[ + { + "ID": "56595ec1-52e4-d6de-e566-3b78696d5459", + "Name": "b-policy", + "Description": "", + "Datacenters": null, + "Hash": "ULwaXlI6Ecqb9YSPegXWgVL1LlwctY9TeeAOhp5HGBA=", + "CreateIndex": 126, + "ModifyIndex": 126, + "Namespace": "default", + "Partition": "default" + }, + { + "ID": "00000000-0000-0000-0000-000000000001", + "Name": "global-management", + "Description": "Builtin Policy that grants unlimited access", + "Datacenters": null, + "Hash": "W1bQuDAlAlxEb4ZWwnVHplnt3I5oPKOZJQITh79Xlog=", + "CreateIndex": 70, + "ModifyIndex": 70, + "Namespace": "default", + "Partition": "default" + } +] +``` --> **Consul Enterprise Namespacing** - Rules defined in a policy in any namespace other than `default` will be [restricted](/docs/acl/acl-rules#namespace-rules) to being able to grant a subset of the overall privileges and only affecting that single namespace. +Note that the `Hash`, `CreateIndex`, and `ModifyIndex` attributes are also printed. These attributes are printed for all responses and are not specific to ACL policies. #### Builtin Policies @@ -130,8 +167,7 @@ node_prefix "" { The [API documentation for roles](/api/acl/roles#sample-payload) has some examples of using a service identity. --> **Consul Enterprise Namespacing** - Service Identity rules will be scoped to the single namespace that -the corresponding ACL Token or Role resides within. +-> **Service Scope for Namespace and Admin Partition** - Service identity rules in Consul Enterprise are scoped to the namespace or admin partition within which the corresponding ACL token or role resides. ### ACL Node Identities @@ -179,26 +215,66 @@ of the following elements: - **Service Identity Set** - The list of service identities that are applicable for the role. - **Namespace** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) --> **Consul Enterprise Namespacing** - Roles may only link to policies defined in the same namespace as the role itself. +-> **Linking Roles to Policies in Consul Enterprise** - Roles can only be linked to policies that are defined in the same namespace or admin partition. ### ACL Tokens -ACL tokens are used to determine if the caller is authorized to perform an action. An ACL token is composed of the following -elements: +Consul uses ACL tokens to determine if the caller is authorized to perform an action. An ACL token is composed of several attributes that you can specify when creating the token. Refer to the [ACL token command line](https://www.consul.io/commands/acl/token) documentation or [ACL token API](/api-docs/acl/tokens) documentation for additional information on how to create policies.: - **Accessor ID** - The token's public identifier. - **Secret ID** -The bearer token used when making requests to Consul. -- **Description** - A human readable description of the token. (Optional) - **Policy Set** - The list of policies that are applicable for the token. -- **Role Set** - The list of roles that are applicable for the token. (Added in Consul 1.5.0) -- **Service Identity Set** - The list of service identities that are applicable for the token. (Added in Consul 1.5.0) -- **Locality** - Indicates whether the token should be local to the datacenter it was created within or created in - the primary datacenter and globally replicated. -- **Expiration Time** - The time at which this token is revoked. (Optional; Added in Consul 1.5.0) -- **Namespace** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) +- **Role Set** - The list of roles that are applicable for the token. Added in Consul 1.5.0. +- **Service Identity Set** - The list of service identities that are applicable for the token. Added in Consul 1.5.0 +- **Local** - Indicates whether the token is local to the datacenter in which it was created. The attribute also can specify if the token was created in the primary datacenter and globally replicated. +- **CreateTime** - Timestamp indicating when the token was created. +- **Expiration Time** - The time at which this token is revoked. This attribute is option when creating a token. Added in Consul 1.5.0. +- **Namespace** - The namespace in which the policy resides. Added in Consul Enterprise 1.7.0. +- **Partition** - The partition in which the policy resides. Added in Consul Enterprise 1.11.0. + +-> **Linking Tokens to Policies in Consul Enterprise** - Tokens can only be linked to policies that are defined in the same namespace or admin partition. + +You can view the current ACL tokens on the command line or through the API. The following example demonstrates the command line usage: + +```shell-session +$ consul acl token list -format json -token +[ + { + "CreateIndex": 75, + "ModifyIndex": 75, + "AccessorID": "c3274caa-fbe4-b457-f4af-c05ba89a048d", + "SecretID": "105c016a-ae9c-2006-ce23-4ef8823ba2af", + "Description": "Bootstrap Token (Global Management)", + "Policies": [ + { + "ID": "00000000-0000-0000-0000-000000000001", + "Name": "global-management" + } + ], + "Local": false, + "CreateTime": "2021-12-16T10:22:08.906291-08:00", + "Hash": "Wda9obh/gvreyTbVhbyJ3ipX0M/apF4kpqowPQQx+u8=", + "Legacy": false, + "Namespace": "default", + "Partition": "default" + }, + { + "CreateIndex": 71, + "ModifyIndex": 71, + "AccessorID": "00000000-0000-0000-0000-000000000002", + "SecretID": "anonymous", + "Description": "Anonymous Token", + "Local": false, + "CreateTime": "2021-12-16T10:21:11.996298-08:00", + "Hash": "tgCOyeidw+oaoZXQ9mHy6+EnY7atKoGaBzg2ndTwXl0=", + "Legacy": false, + "Namespace": "default", + "Partition": "default" + } +] +``` --> **Consul Enterprise Namespacing** - Tokens may only link to policies and roles defined in the same namespace as -the token itself. +Note that the `CreateIndex`, `ModifyIndex`, and `Hash` attributes are also printed. These attributes are printed for all responses and are not specific to ACL tokens. #### Builtin Tokens