Merge pull request #277197 from msmbaldwin/akv-rbac

Key Vault / RBAC includes and authentication blocks

Author: Jill Grant

articles/key-vault/certificates/quick-create-cli.md

@@ -28,6 +28,10 @@ In this quickstart, you create a key vault in Azure Key Vault with Azure CLI. Az
 
 [!INCLUDE [Create a key vault](../includes/key-vault-creation-cli.md)]
 
+## Give your user account permissions to manage secrets in Key Vault
+
+[!INCLUDE [Using RBAC to provide access to a key vault](../includes/rbac/upn-certificate-officer-cli.md)]
+
 ## Add a certificate to Key Vault
 
 To add a certificate to the vault, you just need to take a couple of additional steps. This certificate could be used by an application. 

articles/key-vault/certificates/quick-create-powershell.md

@@ -34,9 +34,9 @@ Connect-AzAccount
 
 [!INCLUDE [Create a key vault](../includes/key-vault-creation-powershell.md)]
 
-### Grant access to your key vault
+## Give your user account permissions to manage secrets in Key Vault
 
-[!INCLUDE [Using RBAC to provide access to a key vault](../includes/key-vault-quickstart-rbac-powershell.md)]
+[!INCLUDE [Using RBAC to provide access to a key vault](../includes/rbac/upn-certificate-officer-powershell.md)]
 
 ## Add a certificate to Key Vault
 

articles/key-vault/general/rbac-guide.md

@@ -21,20 +21,17 @@ ms.author: mbaldwin
 
 Azure role-based access control (Azure RBAC) is an authorization system built on [Azure Resource Manager](../../azure-resource-manager/management/overview.md) that provides centralized access management of Azure resources.
 
-Azure RBAC allows users to manage Key, Secrets, and Certificates permissions. It provides one place to manage all permissions across all key vaults.
+Azure RBAC allows users to manage keys, secrets, and certificates permissions, and provides one place to manage all permissions across all key vaults.
 
-The Azure RBAC model allows users to set permissions on different scope levels: management group, subscription, resource group, or individual resources.  Azure RBAC for key vault also allows users to have separate permissions on individual keys, secrets, and certificates
+The Azure RBAC model allows users to set permissions on different scope levels: management group, subscription, resource group, or individual resources.  Azure RBAC for key vault also allows users to have separate permissions on individual keys, secrets, and certificates.
 
 For more information, see [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md).
 
 ## Best Practices for individual keys, secrets, and certificates role assignments
 
-Our recommendation is to use a vault per application per environment
-(Development, Pre-Production, and Production) with roles assigned at Key Vault scope.
+Our recommendation is to use a vault per application per environment (Development, Pre-Production, and Production) with roles assigned at the key vault scope.
 
-Assigning roles on individual keys, secrets and certificates should be avoided. Exceptions to general guidance:
-
-- Scenarios where individual secrets must be shared between multiple applications, for example, one application needs to access data from the other application
+Assigning roles on individual keys, secrets and certificates should be avoided. An exception is a scenario where individual secrets must be shared between multiple applications; for example, where one application needs to access data from another application.
 
 More about Azure Key Vault management guidelines, see:
 
@@ -69,18 +66,18 @@ For more information about Azure built-in roles definitions, see [Azure built-in
 
 ## Using Azure RBAC secret, key, and certificate permissions with Key Vault
 
-The new Azure RBAC permission model for key vault provides alternative to the vault access policy permissions model. 
+The new Azure RBAC permission model for key vault provides alternative to the vault access policy permissions model.
 
 ### Prerequisites
 
 You must have an Azure subscription. If you don't, you can create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
 
-To manage role assignments, you must have `Microsoft.Authorization/roleAssignments/write` and `Microsoft.Authorization/roleAssignments/delete` permissions, such as [Key Vault Data Access Administrator](../../role-based-access-control/built-in-roles.md#key-vault-data-access-administrator) (with restricted permissions to only assign/remove specific Key Vault roles), [User Access Administrator](../../role-based-access-control/built-in-roles.md#user-access-administrator),or [Owner](../../role-based-access-control/built-in-roles.md#owner).
+To manage role assignments, you must have `Microsoft.Authorization/roleAssignments/write` and `Microsoft.Authorization/roleAssignments/delete` permissions, such as [Key Vault Data Access Administrator](../../role-based-access-control/built-in-roles.md#key-vault-data-access-administrator) (with restricted permissions to only assign/remove specific Key Vault roles), [User Access Administrator](../../role-based-access-control/built-in-roles.md#user-access-administrator), or [Owner](../../role-based-access-control/built-in-roles.md#owner).
 
 ### Enable Azure RBAC permissions on Key Vault
 
 > [!NOTE]
-> Changing permission model requires unrestricted 'Microsoft.Authorization/roleAssignments/write' permission, which is part of [Owner](../../role-based-access-control/built-in-roles.md#owner) and [User Access Administrator](../../role-based-access-control/built-in-roles.md#user-access-administrator) roles. Classic subscription administrator roles like 'Service Administrator' and 'Co-Administrator', or restricted 'Key Vault Data Access Administrator' cannot be used to change permission model.
+> Changing the permission model requires unrestricted 'Microsoft.Authorization/roleAssignments/write' permission, which is part of the [Owner](../../role-based-access-control/built-in-roles.md#owner) and [User Access Administrator](../../role-based-access-control/built-in-roles.md#user-access-administrator) roles. Classic subscription administrator roles like 'Service Administrator' and 'Co-Administrator', or restricted 'Key Vault Data Access Administrator' cannot be used to change permission model.
 
 1. Enable Azure RBAC permissions on new key vault:
 
@@ -95,8 +92,8 @@ To manage role assignments, you must have `Microsoft.Authorization/roleAssignmen
 
 ### Assign role
 
-> [!Note]
-> It's recommended to use the unique role ID instead of the role name in scripts. Therefore, if a role is renamed, your scripts would continue to work. In this document role name is used only for readability.
+> [!NOTE]
+> It's recommended to use the unique role ID instead of the role name in scripts. Therefore, if a role is renamed, your scripts would continue to work. In this document role name is used for readability.
 
 # [Azure CLI](#tab/azure-cli)
 

articles/key-vault/general/tutorial-net-create-vault-azure-web-app.md

@@ -35,7 +35,7 @@ To complete this tutorial, you need:
 * [Azure Key Vault.](./overview.md) You can create a key vault by using the [Azure portal](quick-create-portal.md), the [Azure CLI](quick-create-cli.md), or [Azure PowerShell](quick-create-powershell.md).
 * A Key Vault [secret](../secrets/about-secrets.md). You can create a secret by using the [Azure portal](../secrets/quick-create-portal.md), [PowerShell](../secrets/quick-create-powershell.md), or the [Azure CLI](../secrets/quick-create-cli.md).
 
-If you already have your web application deployed in Azure App Service, you can skip to [configure web app access to a key vault](#create-and-assign-a-managed-identity) and [modify web application code](#modify-the-app-to-access-your-key-vault) sections.
+If you already have your web application deployed in Azure App Service, you can skip to [configure web app access to a key vault](#configure-the-web-app-to-connect-to-key-vault) and [modify web application code](#modify-the-app-to-access-your-key-vault) sections.
 
 ## Create a .NET Core app
 In this step, you'll set up the local .NET Core project.
@@ -230,12 +230,12 @@ http://<your-webapp-name>.azurewebsites.net
 You'll see the "Hello World!" message you saw earlier when you visited `http://localhost:5000`.
 
 For more information about deploying web application using Git, see [Local Git deployment to Azure App Service](../../app-service/deploy-local-git.md)
- 
+
 ## Configure the web app to connect to Key Vault
 
 In this section, you'll configure web access to Key Vault and update your application code to retrieve a secret from Key Vault.
 
-### Create and assign a managed identity
+### Create and assign access to a managed identity
 
 In this tutorial, we'll use [managed identity](../../active-directory/managed-identities-azure-resources/overview.md) to authenticate to Key Vault. Managed identity automatically manages application credentials.
 
@@ -255,13 +255,7 @@ The command will return this JSON snippet:
 }
 ```
 
-To give your web app permission to do **get** and **list** operations on your key vault, pass the `principalId` to the Azure CLI [az keyvault set-policy](/cli/azure/keyvault?#az-keyvault-set-policy) command:
-
-```azurecli-interactive
-az keyvault set-policy --name "<your-keyvault-name>" --object-id "<principalId>" --secret-permissions get list
-```
-
-You can also assign access policies by using the [Azure portal](./assign-access-policy-portal.md) or [PowerShell](./assign-access-policy-powershell.md).
+[!INCLUDE [Using RBAC to provide access to a key vault](../includes/key-vault-quickstart-rbac.md)]
 
 ### Modify the app to access your key vault
 

articles/key-vault/general/tutorial-net-virtual-machine.md

@@ -111,18 +111,8 @@ xxxxxxxx-xx-xxxxxx   xxxxxxxx-xxxx-xxxx   SystemAssigned
 ---
 
 ## Assign permissions to the VM identity
-Assign the previously created identity permissions to your key vault with the [az keyvault set-policy](/cli/azure/keyvault#az-keyvault-set-policy) command:
 
-# [Azure CLI](#tab/azure-cli)
-```azurecli
-az keyvault set-policy --name '<your-unique-key-vault-name>' --object-id <VMSystemAssignedIdentity> --secret-permissions  get list set delete
-```
-# [Azure PowerShell](#tab/azurepowershell)
-
-```azurepowershell
-Set-AzKeyVaultAccessPolicy -ResourceGroupName <YourResourceGroupName> -VaultName '<your-unique-key-vault-name>' -ObjectId '<VMSystemAssignedIdentity>' -PermissionsToSecrets  get,list,set,delete
-```
----
+[!INCLUDE [Using RBAC to provide access to a key vault](../includes/key-vault-quickstart-rbac.md)]
 
 ## Sign in to the virtual machine
 

articles/key-vault/general/tutorial-python-virtual-machine.md

@@ -94,11 +94,7 @@ Note the system-assigned identity that's displayed in the following code. The ou
 
 ## Assign permissions to the VM identity
 
-Now you can assign the previously created identity permissions to your key vault by running the following command:
-
-```azurecli
-az keyvault set-policy --name "<your-unique-keyvault-name>" --object-id "<systemAssignedIdentity>" --secret-permissions get list
-```
+[!INCLUDE [Using RBAC to provide access to a key vault](../includes/key-vault-quickstart-rbac.md)]
 
 ## Log in to the VM
 

articles/key-vault/includes/key-vault-creation-cli.md

@@ -20,7 +20,7 @@ Use the Azure CLI [az keyvault create](/cli/azure/keyvault#az-keyvault-create) c
 - The location: **EastUS**.
 
 ```azurecli
-az keyvault create --name "<your-unique-keyvault-name>" --resource-group "myResourceGroup" --enable-rbac-authorization
+az keyvault create --name "<your-unique-keyvault-name>" --resource-group "myResourceGroup"
 ```
 
 The output of this command shows properties of the newly created key vault. Take note of these two properties:

articles/key-vault/includes/rbac/upn-certificate-officer-cli.md

@@ -0,0 +1,18 @@
+---
+author: msmbaldwin
+ms.service: key-vault
+ms.topic: include
+ms.date: 04/04/2024
+ms.author: msmbaldwin
+
+# Used by articles that show how to assign a Key Vault access policy
+
+---
+
+To gain permissions to your key vault through [Role-Based Access Control (RBAC)](/azure/key-vault/general/rbac-guide), assign a role to your "User Principal Name" (UPN) using the Azure CLI command [az role assignment create](/cli/azure/role/assignment#az-role-assignment-create).
+
+```azurecli
+az role assignment create --role "Key Vault Certificate Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"
+```
+
+Replace \<upn\>, \<subscription-id\>, \<resource-group-name\> and \<your-unique-keyvault-name\> with your actual values. Your UPN will typically be in the format of an email address (e.g., [email protected]).

articles/key-vault/includes/rbac/upn-certificate-officer-pivot.md

@@ -0,0 +1,20 @@
+---
+author: msmbaldwin
+ms.service: key-vault
+ms.topic: include
+ms.date: 04/04/2024
+ms.author: msmbaldwin
+
+# Used by articles that show how to assign a Key Vault access policy
+
+---
+
+### [Azure CLI](#tab/azure-cli)
+
+[!INCLUDE [Using RBAC to provide access to a key vault - CLI](./upn-certificate-officer-cli.md)]
+
+### [Azure PowerShell](#tab/azure-powershell)
+
+[!INCLUDE [Using RBAC to provide access to a key vault - PowerShell](./upn-certificate-officer-powershell.md)]
+
+---

articles/key-vault/includes/rbac/upn-certificate-officer-powershell.md

@@ -0,0 +1,18 @@
+---
+author: msmbaldwin
+ms.service: key-vault
+ms.topic: include
+ms.date: 04/04/2024
+ms.author: msmbaldwin
+
+# Used by articles that show how to assign a Key Vault access policy
+
+---
+
+To gain permissions to your key vault through [Role-Based Access Control (RBAC)](/azure/key-vault/general/rbac-guide), assign a role to your "User Principal Name" (UPN) using the Azure PowerShell cmdlet [New-AzRoleAssignment](/powershell/module/az.resources/new-azroleassignment).
+
+```azurepowershell
+New-AzRoleAssignment -SignInName "<upn>" -RoleDefinitionName "Key Vault Certificate Officer" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"
+```
+
+Replace \<upn\>, \<subscription-id\>, \<resource-group-name\> and \<your-unique-keyvault-name\> with your actual values. Your UPN will typically be in the format of an email address (e.g., [email protected]).