From 8fe0bd1cbdfc743e67ba79555c1240b7fee36113 Mon Sep 17 00:00:00 2001 From: "Chris S. Kim" Date: Wed, 22 Nov 2023 12:29:43 -0500 Subject: [PATCH] Add docs for identity acl rules (#19713) --- .../content/docs/security/acl/acl-rules.mdx | 51 +++++++++++++++++-- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index 6139ddeabb..c3f87970d5 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -19,6 +19,7 @@ The following table provides an overview of the resources you can use to create | `partition`
`partition_prefix` | Controls access to one or more admin partitions.
See [Admin Partition Rules](#admin-partition-rules) for details. | Yes | | `agent`
`agent_prefix` | Controls access to the utility operations in the [Agent API](/consul/api-docs/agent), such as `join` and `leave`.
See [Agent Rules](#agent-rules) for details. | Yes | | `event`
`event_prefix` | Controls access to event operations in the [Event API](/consul/api-docs/event), such as firing and listing events.
See [Event Rules](#event-rules) for details. | Yes | +| `identity`
`identity_prefix` | Controls access to workload identity operations in the [Catalog v2 group](/consul/docs/architecture/catalog/v2). | `key`
`key_prefix`   | Controls access to key/value store operations in the [KV API](/consul/api-docs/kv).
Can also use the `list` access level when setting the policy disposition.
Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul).
See [Key/Value Rules](#key-value-rules) for details. | Yes | | `keyring`       | Controls access to keyring operations in the [Keyring API](/consul/api-docs/operator/keyring).
See [Keyring Rules](#keyring-rules) for details. | No | | `mesh`       | Provides operator-level permissions for resources in the admin partition, such as ingress gateways or mesh proxy defaults. See [Mesh Rules](#mesh-rules) for details. | No | @@ -247,6 +248,48 @@ operation, so to enable this feature in a Consul environment with ACLs enabled, give agents a token with access to this event prefix, in addition to configuring [`disable_remote_exec`](/consul/docs/agent/config/config-files#disable_remote_exec) to `false`. +## Identity Rules + +The `identity` and `identity_prefix` resources control workload-identity-level registration and read access to the [Catalog v2 API group](/consul/docs/architecture/catalog/v2). +Specify the resource label in identity rules to set the scope of the rule. +The resource label in the following example is empty. As a result, the rules allow read-only access to any workload identity name with the empty prefix. +The rules also allow read-write access to the `app` identity and deny all access to the `admin` identity: + + + +```hcl +identity_prefix "" { + policy = "read" +} +identity "app" { + policy = "write" +} +identity "admin" { + policy = "deny" +} +``` + +```json +{ + "identity_prefix": { + "": { + "policy": "read" + } + }, + "identity": { + "app": { + "policy": "write" + }, + "admin": { + "policy": "deny" + } + } +} +``` + + + + ## Key/Value Rules The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/consul/api-docs/kv). @@ -592,13 +635,13 @@ These actions may required an ACL token to complete. Use the following methods t Nodes rules affect read access to nodes with services exported by [`exported-services` configuration entries](/consul/docs/connect/config-entries/exported-services#reading-services), including nodes imported from [cluster peerings](/consul/docs/connect/cluster-peering) or [admin partitions](/consul/docs/enterprise/admin-partitions) (Enterprise-only). Read access to all imported nodes is granted when either of the following rule sets are attached to a token: -- `service:write` is granted to any service. +- `service:write` is granted to any service. - `node:read` is granted to all nodes. For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace. You may need similarly scoped [Service Rules](#reading-imported-services) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`). -These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities). +These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities). Refer to [Reading Services](/consul/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint. @@ -831,13 +874,13 @@ set to `true` in order to enable script checks. Service rules affect read access to services exported by [`exported-services` configuration entries](/consul/docs/connect/config-entries/exported-services#reading-services), including services exported between [cluster peerings](/consul/docs/connect/cluster-peering) or [admin partitions](/consul/docs/enterprise/admin-partitions) (Enterprise-only). Read access to all imported services is granted when either of the following rule sets are attached to a token: -- `service:write` is granted to any service. +- `service:write` is granted to any service. - `service:read` is granted to all services. For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace. You may need similarly scoped [Node Rules](#reading-imported-nodes) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`). -These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities). +These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities). Refer to [Reading Services](/consul/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint.