From e6e844d6b5e8625133ed259cc7e9d178e7a2d6d4 Mon Sep 17 00:00:00 2001
From: Jim Kalafut <jkalafut@hashicorp.com>
Date: Tue, 15 Oct 2019 08:58:22 -0700
Subject: [PATCH] Update Azure Secrets docs to include group assignment (#7656)

---
 website/source/api/secret/azure/index.html.md |  4 ++
 .../source/docs/secrets/azure/index.html.md   | 62 ++++++++++++-------
 2 files changed, 44 insertions(+), 22 deletions(-)

diff --git a/website/source/api/secret/azure/index.html.md b/website/source/api/secret/azure/index.html.md
index 7c641f1d41..768092c6b0 100644
--- a/website/source/api/secret/azure/index.html.md
+++ b/website/source/api/secret/azure/index.html.md
@@ -127,6 +127,9 @@ information about roles.
 - `azure_roles` (`string: ""`) - List of Azure roles to be assigned to the generated service
    principal. The array must be in JSON format, properly escaped as a string. See [roles docs][roles]
    for details on role definition.
+- `azure_groups` (`string: ""`) - List of Azure groups that the generated service principal will be
+   assigned to. The array must be in JSON format, properly escaped as a string. See [groups docs][groups]
+   for more details.
 - `application_object_id` (`string: ""`) - Application Object ID for an existing service principal that will
    be used instead of creating dynamic service principals. If present, `azure_roles` will be ignored. See
    [roles docs][roles] for details on role definition.
@@ -235,3 +238,4 @@ See docs on how to [renew](/api/system/leases.html#renew-lease) and [revoke](/ap
 
 [docs]: /docs/secrets/azure/index.html
 [roles]: /docs/secrets/azure/index.html#roles
+[groups]: /docs/secrets/azure/index.html#azure-groups
diff --git a/website/source/docs/secrets/azure/index.html.md b/website/source/docs/secrets/azure/index.html.md
index 2d511a0b98..6ce29a599f 100644
--- a/website/source/docs/secrets/azure/index.html.md
+++ b/website/source/docs/secrets/azure/index.html.md
@@ -10,10 +10,10 @@ description: |-
 
 # Azure Secrets Engine
 
-The Azure secrets engine dynamically generates Azure service principals and role
-assignments.  Vault roles can be mapped to one or more Azure roles, providing a
-simple, flexible way to manage the permissions granted to generated service
-principals.
+The Azure secrets engine dynamically generates Azure service principals along
+with role and group assignments.  Vault roles can be mapped to one or more Azure
+roles, and optionally group assignments, providing a simple, flexible way to
+manage the permissions granted to generated service principals.
 
 Each service principal is associated with a Vault lease. When the lease expires
 (either during normal revocation or through early revocation), the service
@@ -126,32 +126,50 @@ Azure roles may be specified using the `role_name` parameter ("Owner"), or `role
 `role_id` is the definitive ID that's used during Vault operation; `role_name` is a convenience during
 role management operations. All roles *must exist* when the configuration is written or the operation will fail. The role lookup priority is:
 
-1. If `role_id` is provided, it validated and the corresponding `role_name` updated.
+1. If `role_id` is provided, it is validated and the corresponding `role_name` updated.
 1. If only `role_name` is provided, a case-insensitive search-by-name is made, succeeding
 only if *exactly one* matching role is found. The `role_id` field will updated with the matching role ID.
 
 The `scope` must be provided for every role assignment.
 
+### Azure Groups
+If dynamic service principals are used, a list of Azure groups may be configured on the Vault role.
+When the service principal is created, it will be assigned to these groups. Similar to the format used
+for specifying Azure roles, Azure groups may be referenced by either their `group_name` or `object_id`.
+Group specification by name must yield a single matching group.
+
 Example of role configuration:
 
 ```text
-$ vault write azure/roles/my-role ttl=1h max_ttl=24h azure_roles=-<<EOF
-  [
-    {
-        "role_name": "Contributor",
-    	"scope":  "/subscriptions/<uuid>/resourceGroups/Website"
-    },
-    {
-        "role_id": "/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>",
-    	"scope":  "/subscriptions/<uuid>"
-    },
-    {
-   	    "role_name": "This won't matter as it will be overwritten",
-   	    "role_id": "/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>",
-   	    "scope":  "/subscriptions/<uuid>/resourceGroups/Database"
-    }
-  ]
-EOF
+$ vault write azure/roles/my-role ttl=1h max_ttl=24h azure_roles=@az_roles.json azure_groups=@az_groups.json
+
+$ cat az_roles.json
+[
+  {
+    "role_name": "Contributor",
+    "scope":  "/subscriptions/<uuid>/resourceGroups/Website"
+  },
+  {
+    "role_id": "/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>",
+    "scope":  "/subscriptions/<uuid>"
+  },
+  {
+    "role_name": "This won't matter as it will be overwritten",
+    "role_id": "/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>",
+    "scope":  "/subscriptions/<uuid>/resourceGroups/Database"
+  }
+]
+
+$ cat az_groups.json
+[
+  {
+    "group_name": "foo",
+  },
+  {
+    "group_name": "This won't matter as it will be overwritten",
+    "object_id": "a6a834a6-36c3-4575-8e2b-05095963d603"
+  }
+]
 ```