secrets/azure: add doc for rotate-root and AAD migration (#13066)

* secrets/azure: add doc for rotate-root and AAD migration

* Formatting

* Fix bad link, update warnings

website/content/api-docs/secret/azure.mdx

@@ -38,7 +38,10 @@ service principals. Environment variables will override any parameters set in th
   use when creating dynamic credentials. Defaults to generating an alphanumeric password if not set.
 - `use_microsoft_graph_api` `(bool: false)` - Indicates whether the secrets engine should use the
   [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api). If set to false, this will use the Azure
-  Active Directory API which has been [deprecated by Microsoft and will be removed in 2022](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-faq).
+  Active Directory API which is being [retired by Microsoft and will be removed in 2022](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-faq).
+- `root_password_ttl` `(string: 182d)` - Specifies how long the root password is valid for in Azure when 
+  rotate-root generates a new client secret. This can be either a number of seconds or a time formatted 
+  duration (ex: 24h, 48d).
 
   If set to true, the user specified via the `client_id` and `client_secret` will need to have the following permissions
   under the Microsoft Graph API: `Application.ReadWrite.All`, `Directory.ReadWrite.All`, and `Group.ReadWrite.All`.
@@ -55,7 +58,8 @@ service principals. Environment variables will override any parameters set in th
   "client_secret": "9a6346...",
   "environment": "AzureGermanCloud",
   "password_policy": "azure_policy",
-  "use_microsoft_graph_api": true
+  "use_microsoft_graph_api": true,
+  "root_password_ttl": "48d"
 }
 ```
 
@@ -162,6 +166,31 @@ $ vault delete azure/config
 </Tab>
 </Tabs>
 
+## Rotate Root
+
+This endpoint generates a new client secret for the root account defined in the config. The 
+value generated will only be known by Vault.
+
+~> Due to the eventual consistency of Microsoft Azure client secret APIs, the plugin 
+   may briefly stop authenticating to Azure as the password propagates through their 
+   datacenters.
+
+| Method | Path                      |
+| :----- | :------------------------ |
+| `POST` | `/azure/rotate-root` |
+
+### Parameters
+
+There are no parameters to this operation.
+
+### Sample Request
+
+```shell-session
+$ curl \
+  --header "X-Vault-Token: ..." \
+  --request POST \
+  http://127.0.0.1:8200/v1/azure/rotate-root
+
 ## Create/Update Role
 
 Create or update a Vault role. Either `application_object_id` or

website/content/docs/secrets/azure.mdx

@@ -21,7 +21,7 @@ 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.
 
-~> Microsoft has deprecated their Azure Active Directory API and will be removing it in
+~> Microsoft is shutting down their Azure Active Directory API and will be retiring it in
    2022. If you are currently using this secret engine, you will need to update the
    credentials to include Microsoft Graph API permissions and specify the
    `use_microsoft_graph_api` configuration value as true. See the
@@ -50,7 +50,8 @@ management tool.
        subscription_id=$AZURE_SUBSCRIPTION_ID \
        tenant_id=$AZURE_TENANT_ID \
        client_id=$AZURE_CLIENT_ID \
-       client_secret=$AZURE_CLIENT_SECRET
+       client_secret=$AZURE_CLIENT_SECRET \
+       use_microsoft_graph_api=true
 
    Success! Data written to: azure/config
    ```
@@ -192,17 +193,101 @@ The individual parameters are described in the [configuration][config] section o
 If the client ID or secret are not present and Vault is running on an Azure VM, Vault will attempt to use
 [Managed Service Identity (MSI)](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/overview) to access Azure. Note that when MSI is used, tenant and subscription IDs must still be explicitly provided in the configuration or environment variables.
 
-The following Azure roles and Azure Active Directory (AAD) permissions are required, regardless of which authentication method is used:
+### MS Graph Permissions
 
-- "Owner" role for the subscription scope
+The following Azure permissions should be assigned to the service principal provided to Vault for managing Azure:
-- "Read and write all applications" permission in AAD
 
-These permissions can be configured through the Azure Portal, CLI tool, or PowerShell.
+| Permission Name               | Type        |
-In your Azure subscription, your account must have `Microsoft.Authorization/*/Write`
+|-------------------------------|-------------|
-access to assign an AD app to a role. This action is granted through the [Owner](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#owner) role or
+| Application.Read.All          | Application |
-[User Access Administrator](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#user-access-administrator) role. If your account is assigned to the Contributor role, you
+| Application.ReadWrite.All     | Application |
-don't have adequate permission. You will receive an error when attempting to assign the service
+| Application.ReadWrite.OwnedBy | Application |
-principal to a role.
+| Directory.Read.All            | Application |
+| Directory.ReadWrite.All       | Application |
+| Group.Read.All                | Application |
+| Group.ReadWrite.All           | Application |
+| GroupMember.Read.All          | Application |
+| GroupMember.ReadWrite.All     | Application |
+
+| Permission Name               | Type        |
+|-------------------------------|-------------|
+| Application.Read.All          | Delegated   |
+| Application.ReadWrite.All     | Delegated   |
+| Directory.AccessAsUser.All    | Delegated   |
+| Directory.Read.All            | Delegated   |
+| Directory.ReadWrite.All       | Delegated   |
+| Group.Read.All                | Delegated   |
+| Group.ReadWrite.All           | Delegated   |
+| GroupMember.Read.All          | Delegated   |
+| GroupMember.ReadWrite.All     | Delegated   |
+
+Additionally the following IAM roles are required and need to be added to the service 
+principal using the Azure portal:
+
+- "Owner" role
+
+### AAD (Azure Active Directory)
+
+~> Microsoft is shutting down their Azure Active Directory API and will be retiring it in
+   2022. If you are currently using this secret engine, you will need to update the
+   credentials to include Microsoft Graph API permissions and specify the
+   `use_microsoft_graph_api` configuration value as true. See the
+   [API Docs](/api-docs/secret/azure#use_microsoft_graph_api) for more details.
+
+As part of the retirement of Azure Active Directory, new service principals can no longer 
+be granted Azure Active Directory permissions using the Azure Portal. To add the neccessary 
+API permissions for AAD, the Azure CLI is suggested. The following commands will add the 
+correct privileges to an existing service principal:
+
+```shell
+APP_ID='<App ID Here>'
+
+az ad app permission add \
+    --id ${APP_ID?} \
+    --api 00000002-0000-0000-c000-000000000000 \
+    --api-permissions \
+        1cda74f2-2616-4834-b122-5cb1b07f8a59=Role \
+        78c8a3c8-a07e-4b9e-af1b-b5ccab50a175=Role \
+        970d6fa6-214a-4a9b-8513-08fad511e2fd=Scope \
+        311a71cc-e848-46a1-bdf8-97ff7156d8e6=Scope
+
+az ad app permission grant --id ${APP_ID?} --api 00000002-0000-0000-c000-000000000000
+```
+
+Additionally the following IAM roles are required and need to be added to the service 
+principal using the Azure portal:
+
+- "Owner" role
+
+### Migrating From AAD To Microsoft Graph
+
+In this example we will migrate the Azure secret engine from using Azure Active Directory 
+(AAD) to Microsoft Graph.
+
+First, create a new service principal [with the proper permissions](/docs/secrets/azure#authentication)
+for managing Azure accounts. After granting the appropriate permissions, the following will be needed 
+from the service principal to configure the secret engine:
+
+1. Application (client) ID 
+1. Directory (tenant) ID
+1. Client Secret 
+1. Subscription ID
+
+Finally, the Azure secret engine configuration can be updated with the new values:
+
+```shell
+TENANT_ID='<Directory (Tenant) ID Here>'
+CLIENT_ID='Application (Client) ID Here>'
+CLIENT_SECRET='<Client Secret Here>'
+SUBSCRIPTION_ID='<Subcription ID Here>'
+
+vault write azure/config \
+        subscription_id=$SUBSCRIPTION_ID  \
+        client_id=$CLIENT_ID \
+        client_secret=$CLIENT_SECRET \
+        tenant_id=$TENANT_ID \
+        use_microsoft_graph_api=true
+```
 
 ## Choosing between dynamic or existing service principals