From fea8ee51259c3a16684a63b9e1e6a2c1d99f79eb Mon Sep 17 00:00:00 2001
From: Chris Hoffman <christopher.hoffman@gmail.com>
Date: Thu, 23 Aug 2018 10:05:44 -0400
Subject: [PATCH] Docs: ACL Templating (#5159)

---
 website/source/docs/concepts/policies.html.md | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/website/source/docs/concepts/policies.html.md b/website/source/docs/concepts/policies.html.md
index 2298e97a3d..3440373bcd 100644
--- a/website/source/docs/concepts/policies.html.md
+++ b/website/source/docs/concepts/policies.html.md
@@ -225,6 +225,57 @@ credentials _creates_ database credentials, but the HTTP request is a GET which
 corresponds to a `read` capability. Thus, to grant access to generate database
 credentials, the policy would grant `read` access on the appropriate path.
 
+## Templated Policies
+
+The policy syntax allows for doing variable replacement in the policy strings
+with values available to the token. Currently `identity` information can be
+injected into policies.
+
+### Parameters
+
+|                                    Name                                |                                    Description                               |
+| :--------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
+| `identity.entity.id`                                                   | The entity's ID                                                              |
+| `identity.entity.name`                                                 | The entity's name                                                            |
+| `identity.entity.metadata.<<metadata key>>`                            | Metadata associated with the entity for the given key                        |
+| `identity.entity.aliases.<<mount accessor>>.id`                        | Entity alias ID for the given mount                                          |
+| `identity.entity.aliases.<<mount accessor>>.name`                      | Entity alias name for the given mount                                        |
+| `identity.entity.aliases.<<mount accessor>>.metadata.<<metadata key>>` | Metadata associated with the alias for the given mount and metadata key      |
+| `identity.groups.ids.<<group id>>.name`                                | The group name for the given group ID                                        |
+| `identity.groups.names.<<group name>>.id`                              | The group ID for the given group name                                        |
+
+### Examples
+
+The following policy creates a section of the KVv2 Secret Engine to a specific user
+
+```ruby
+path "secret/data/{{identity.entity.id}}/*" {
+  capabilities = ["create", "update", "read", "delete"]
+}
+
+path "secret/metadata/{{identity.entity.id}}/*" {
+  capabilities = ["list"]
+}
+```
+
+If you wanted to create a shared section of KV that is associated with entities that are in a
+group.
+
+```ruby
+# In the example below, the group ID maps a group and the path 
+path "secret/data/groups/{{identity.groups.ids.fb036ebc-2f62-4124-9503-42aa7A869741.name}}/*" {
+  capabilities = ["create", "update", "read", "delete"]
+}
+
+path "secret/metadata/groups/{{identity.groups.ids.fb036ebc-2f62-4124-9503-42aa7A869741.name}}/*" {
+  capabilities = ["list"]
+}
+```
+
+~> When developing templated policies, use IDs wherever possible.  Each ID is unique to the user and names can change over
+time. This ensures that if a given user or group name is changed, the policy will be mapped to the intended entity
+or group.
+
 ## Fine-Grained Control
 
 In addition to the standard set of capabilities, Vault offers finer-grained