From 068da60712ce8ccc260513b564bd862b110deadd Mon Sep 17 00:00:00 2001
From: Jim Kalafut <jim@kalafut.net>
Date: Fri, 19 Oct 2018 13:48:15 -0700
Subject: [PATCH] Update Azure Secrets docs (#5554)

Add coverage of application_object_id parameter.
---
 website/source/api/secret/azure/index.html.md | 12 ++--
 .../source/docs/secrets/azure/index.html.md   | 70 +++++++++++++++----
 2 files changed, 64 insertions(+), 18 deletions(-)

diff --git a/website/source/api/secret/azure/index.html.md b/website/source/api/secret/azure/index.html.md
index 7fba82016c..f51832ccdf 100644
--- a/website/source/api/secret/azure/index.html.md
+++ b/website/source/api/secret/azure/index.html.md
@@ -112,9 +112,10 @@ $ curl \
 
 ## Create/Update Role
 
-Create or update a Vault role. The provided Azure roles must exist
-for this call to succeed. See the Azure secrets [roles docs][roles]
-for more information about roles.
+Create or update a Vault role. Either `application_object_id` or
+`azure_roles` must be provided, and these resources must exist for this
+call to succeed. See the Azure secrets [roles docs][roles] for more
+information about roles.
 
 | Method   | Path                     | Produces                  |
 | :------- | :------------------------| :------------------------ |
@@ -123,9 +124,12 @@ for more information about roles.
 
 ### Parameters
 
-- `azure_roles` (`string: <required>`) - List of Azure roles to be assigned to the generated service
+- `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.
+- `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.
 - `ttl` (`string: ""`) – Specifies the default TTL for service principals generated using this role.
    Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine default TTL time.
 - `max_ttl` (`string: ""`) – Specifies the maximum TTL for service principals generated using this role. Accepts time
diff --git a/website/source/docs/secrets/azure/index.html.md b/website/source/docs/secrets/azure/index.html.md
index 90eb26f5c2..6ce133ac7c 100644
--- a/website/source/docs/secrets/azure/index.html.md
+++ b/website/source/docs/secrets/azure/index.html.md
@@ -19,6 +19,10 @@ Each service principal is associated with a Vault lease. When the lease expires
 (either during normal revocation or through early revocation), the service
 principal is automatically deleted.
 
+If an existing service principal is specified as part of the role configuration,
+a new password will be dynamically generated instead of a new service principal.
+The password will be deleted when the lease is revoked.
+
 ## Setup
 
 Most secrets engines must be configured in advance before they can perform their
@@ -50,10 +54,16 @@ management tool.
     If you are running Vault inside an Azure VM with MSI enabled, `client_id` and
     `client_secret` may be omitted. For more information on authentication, see the [authentication](#authentication) section below.
 
-1. Configure a role. Roles determine the permissions that the service principal
-generated by Vault will have to Azure resources.
+1. Configure a role. A role may be set up with either an existing service principal, or
+a set of Azure roles that will be assigned to a dynamically created service principal.
 
-    To configure a role called "my-role":
+To configure a role called "my-role" with an existing service principal:
+
+    ```text
+    $ vault write azure/roles/my-role application_object_id=<existing_app_obj_id> ttl=1h
+    ```
+
+    Alternatively, to configure the role to create a new service principal with Azure roles:
 
     ```text
     $ vault write azure/roles/my-role ttl=1h azure_roles=-<<EOF
@@ -66,14 +76,15 @@ generated by Vault will have to Azure resources.
     EOF
     ```
 
-    Roles may also have their own TTL configuration that is separate from the mount's
-    TTL. For more information on roles see the [roles](#roles) section below.
+Roles may also have their own TTL configuration that is separate from the mount's
+TTL. For more information on roles see the [roles](#roles) section below.
 
 
 ## Usage
 
 After the secrets engine is configured and a user/machine has a Vault token with
-the proper permissions, it can generate credentials.
+the proper permissions, it can generate credentials. The usage pattern is the same
+whether an existing or dynamic service principal is used.
 
 To generate a credential using the "my-role" role:
 
@@ -89,18 +100,26 @@ client_id          408bf248-dd4e-4be5-919a-7f6207a307ab
 client_secret      ad06228a-2db9-4e0a-8a5d-e047c7f32594
 ```
 
-This endpoint generates a renewable service principal. The application can login
-using the `client_id`/`client_secret` and will have access provided by the Azure roles set in
-the "my-role" configuration.
+This endpoint generates a renewable set of credentials. The application can login
+using the `client_id`/`client_secret` and will have access provided by configured service
+principal or the Azure roles set in the "my-role" configuration.
 
 
 ## Roles
 
-Vault roles let you configure mapped Azure roles and role-specific TTL parameters. One or more Azure
-roles will be assigned to a newly created service principal. The Vault role may optionally specify role-specific `ttl` and/or `max_ttl` values. When the lease is created, the
-more restrictive of the mount or role TTL value will be used.
+Vault roles let you configure either an existing service principal or a set of Azure roles, along with
+role-specific TTL parameters. If an existing service principal is not provided, the configured Azure
+roles will be assigned to a newly created service principal. The Vault role may optionally specify
+role-specific `ttl` and/or `max_ttl` values. When the lease is created, the more restrictive of the
+mount or role TTL value will be used.
+
+### Application Object IDs
+If an existing service principal is to be used, the Application Object ID must be set on the Vault role.
+This ID can be found by inspecting the desired Application with the `az` CLI tool, or via the Azure Portal. Note
+that the Application **Object** ID must be provided, not the Application ID.
 
 ### Azure Roles
+If dynamic service principals are used, Azure roles must be configured on the Vault role.
 Azure roles are provided as a JSON list, with each element describing an Azure role and scope to be assigned.
 Azure roles may be specified using the `role_name` parameter ("Owner"), or `role_id`
 ("/subscriptions/.../roleDefinitions/...").
@@ -153,6 +172,27 @@ The following Azure roles and Azure Active Directory (AAD) permissions are requi
 
 These permissions can be configured through the Azure Portal, CLI tool, or PowerShell.
 
+## Choosing between dynamic or existing service principals
+
+Dynamic service principals are preferred if the desired Azure resources can be provided
+via the RBAC system and Azure roles defined in the Vault role. This form of credential is
+completely decoupled from any other clients, is not subject to permission changes after
+issuance, and offers the best audit granularity.
+
+Access to some Azure services cannot be provided with the RBAC system, however. In these
+cases, an existing service principal can be set up with the necessary access, and Vault
+can create new passwords for this service principal. Any changes to the service principal
+permissions affect all clients. Furthermore, Azure does not provide any logging with
+regard to _which_ credential was used for an operation.
+
+An important limitation when using an existing service princicpal is that Azure limits the
+number of passwords for a single Application. This limit is based on Application object
+size and isn't firmly specified, but in practice hundreds of passwords can be issued per
+Application. An error will be returned if the object size is reached. This limit can be
+managed by reducing the role TTL, or by creating another Vault role against a different
+Azure service principal configured with the same permissions.
+
+
 ## Additional Notes
 
 -  **If a referenced Azure role doesn't exist, a credential will not be generated.**
@@ -171,8 +211,10 @@ These permissions can be configured through the Azure Portal, CLI tool, or Power
 - Service principal credential timeouts are not used. Vault will revoke access by
   deleting the service principal.
 
-- The Application Name for the service principal will be prefixed with `vault-`. This may
-  be used to search for Vault-created credentials using other tools or the Portal.
+- The Application Name for dynamic service principals will be prefixed with `vault-`. Similarly
+  the `keyId` of any passwords added to an existing service principal will begin with
+  `ffffff`. These may be used to search for Vault-created credentials using the `az` tool
+  or Portal.
 
 ## Help &amp; Support