Merge pull request #116163 from rolyon/rolyon-rbac-arm-quickstart

[Azure RBAC] Quickstart: Add an Azure role assignment using template

Author: v-shmck

.openpublishing.redirection.json

@@ -33927,6 +33927,11 @@
       "redirect_url": "/azure/role-based-access-control/role-assignments-portal",
       "redirect_document_id": false
     },
+    {
+      "source_path": "articles/role-based-access-control/tutorial-role-assignments-user-template.md",
+      "redirect_url": "/azure/role-based-access-control/quickstart-role-assignments-template",
+      "redirect_document_id": true
+    },
     {
       "source_path": "articles/active-directory/privileged-identity-management/active-directory-securing-privileged-access.md",
       "redirect_url": "/azure/active-directory/users-groups-roles/directory-admin-roles-secure",

articles/role-based-access-control/TOC.yml

@@ -11,15 +11,15 @@
   items:
   - name: View access for a user
     href: check-access.md
+  - name: ARM template
+    displayName: Resource Manager
+    href: quickstart-role-assignments-template.md
 - name: Tutorials
   items:
   - name: Grant a user access - Portal
     href: quickstart-assign-role-user-portal.md
   - name: Grant a user access - PowerShell
     href: tutorial-role-assignments-user-powershell.md
-  - name: Grant a user access - Resource Manager Template
-    displayName: ARM, resource manager template
-    href: tutorial-role-assignments-user-template.md
   - name: Grant a group access - PowerShell
     href: tutorial-role-assignments-group-powershell.md
   - name: Create a custom role - PowerShell
@@ -67,7 +67,8 @@
       href: role-assignments-cli.md
     - name: REST API
       href: role-assignments-rest.md
-    - name: Template
+    - name: ARM template
+      displayName: Resource Manager
       href: role-assignments-template.md
   - name: List deny assignments
     items:
@@ -113,8 +114,8 @@
     href: /cli/azure/role?view=azure-cli-latest
   - name: REST API
     href: /rest/api/authorization/
-  - name: Resource Manager templates
-    displayName: ARM
+  - name: ARM templates
+    displayName: Resource Manager
     items:
     - name: Role Assignments
       href: /azure/templates/microsoft.authorization/roleassignments

articles/role-based-access-control/media/quickstart-role-assignments-template/role-assignment-portal.png

@@ -0,0 +1,140 @@
+---
+title: "Quickstart: Add an Azure role assignment using an Azure Resource Manager template - Azure RBAC"
+description: Learn how to grant access to Azure resources for a user at resource group scope using Azure Resource Manager templates and Azure role-based access control (Azure RBAC).
+services: role-based-access-control,azure-resource-manager
+author: rolyon
+manager: mtillman
+ms.service: role-based-access-control
+ms.topic: quickstart
+ms.custom: subject-armqs
+ms.workload: identity
+ms.date: 05/21/2020
+ms.author: rolyon
+
+#Customer intent: As a new user, I want to see how to grant access to resources by using Azure Resource Manager template so that I can start automating role assignment processes.
+
+---
+
+# Quickstart: Add an Azure role assignment using an Azure Resource Manager template
+
+[Azure role-based access control (Azure RBAC)](overview.md) is the way that you manage access to Azure resources. In this quickstart, you create a resource group and grant a user access to create and manage virtual machines in the resource group. This quickstart uses a Resource Manager template to grant the access.
+
+[!INCLUDE [About Azure Resource Manager](../../includes/resource-manager-quickstart-introduction.md)]
+
+If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
+
+## Prerequisites
+
+To add role assignments, you must have:
+
+* `Microsoft.Authorization/roleAssignments/write` and `Microsoft.Authorization/roleAssignments/delete` permissions, such as [User Access Administrator](built-in-roles.md#user-access-administrator) or [Owner](built-in-roles.md#owner)
+
+## Create a role assignment
+
+To add a role assignment, you must specify three elements: security principal, role definition, and scope. For this quickstart, the security principal is you or another user in your directory, the role definition is [Virtual Machine Contributor](built-in-roles.md#virtual-machine-contributor), and the scope is a resource group that you specify.
+
+### Review the template
+
+The template used in this quickstart is from [Azure Quickstart templates](https://azure.microsoft.com/resources/templates/101-rbac-builtinrole-resourcegroup/). The template has three parameters and a resources section. In the resources section, notice that it has the three elements of a role assignment: security principal, role definition, and scope. 
+
+:::code language="json" source="~/quickstart-templates/101-rbac-builtinrole-resourcegroup/azuredeploy.json" highlight="30-32":::
+
+### Deploy the template
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+
+1. Determine your email address that is associated with your Azure subscription. Or determine the email address of another user in your directory.
+
+1. Open Azure Cloud Shell for PowerShell.
+
+1. Copy and paste the following script into Cloud Shell.
+
+    ```azurepowershell
+    $resourceGroupName = Read-Host -Prompt "Enter a resource group name (i.e. ExampleGrouprg)"
+    $emailAddress = Read-Host -Prompt "Enter an email address for a user in your directory"
+    $location = Read-Host -Prompt "Enter a location (i.e. centralus)"
+    
+    $roleAssignmentName = New-Guid
+    $principalId = (Get-AzAdUser -Mail $emailAddress).id
+    $roleDefinitionId = (Get-AzRoleDefinition -name "Virtual Machine Contributor").id
+    $templateUri = "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-rbac-builtinrole-resourcegroup/azuredeploy.json"
+    
+    New-AzResourceGroup -Name $resourceGroupName -Location $location
+    New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri $templateUri -roleAssignmentName $roleAssignmentName -roleDefinitionID $roleDefinitionId -principalId $principalId
+    ```
+
+1. Enter a resource group name such as ExampleGrouprg.
+
+1. Enter an email address for yourself or another user in your directory.
+
+1. Enter a location for the resource group such as centralus.
+
+1. If necessary, press Enter to run the New-AzResourceGroupDeployment command.
+
+    The [New-AzResourceGroup](/powershell/module/az.resources/new-azresourcegroup) command creates a new resource group and the [New-AzResourceGroupDeployment](/powershell/module/az.resources/new-azresourcegroupdeployment) command deploys the template to add the role assignment.
+
+    You should see output similar to the following:
+
+    ```azurepowershell
+    PS> New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri $templateUri -roleAssignmentName $roleAssignmentName -roleDefinitionID $roleDefinitionId -principalId $principalId
+    
+    DeploymentName          : azuredeploy
+    ResourceGroupName       : ExampleGrouprg
+    ProvisioningState       : Succeeded
+    Timestamp               : 5/22/2020 9:01:30 PM
+    Mode                    : Incremental
+    TemplateLink            :
+                              Uri            : https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-rbac-builtinrole-resourcegroup/azuredeploy.json
+                              ContentVersion : 1.0.0.0
+    
+    Parameters              :
+                              Name                  Type                       Value
+                              ====================  =========================  ==========
+                              roleAssignmentName    String                     {roleAssignmentName}
+                              roleDefinitionID      String                     9980e02c-c2be-4d73-94e8-173b1dc7cf3c
+                              principalId           String                     {principalId}
+    
+    Outputs                 :
+    DeploymentDebugLogLevel :
+    ```
+
+## Review deployed resources
+
+1. In the Azure portal, open the resource group you created.
+
+1. In the left menu, click **Access control (IAM)**.
+
+1. Click the **Role assignments** tab.
+
+1. Verify that the **Virtual Machine Contributor** role is assigned to the user you specified.
+
+   ![New role assignment](./media/quickstart-role-assignments-template/role-assignment-portal.png)
+
+## Clean up resources
+
+To remove the role assignment and resource group you created, follow these steps.
+
+1. Copy and paste the following script into Cloud Shell.
+
+    ```azurepowershell
+    $emailAddress = Read-Host -Prompt "Enter the email address of the user with the role assignment to remove"
+    $resourceGroupName = Read-Host -Prompt "Enter the resource group name to remove (i.e. ExampleGrouprg)"
+    
+    $principalId = (Get-AzAdUser -Mail $emailAddress).id
+    
+    Remove-AzRoleAssignment -ObjectId $principalId -RoleDefinitionName "Virtual Machine Contributor" -ResourceGroupName $resourceGroupName
+    Remove-AzResourceGroup -Name $resourceGroupName
+    ```
+    
+1. Enter the email address of the user with the role assignment to remove.
+
+1. Enter the resource group name to remove such as ExampleGrouprg.
+
+1. If necessary, press Enter to run the Remove-AzResourceGroup command.
+
+1. Enter **Y** to confirm that you want to remove the resource group.
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Tutorial: Grant a user access to Azure resources using Azure PowerShell](tutorial-role-assignments-user-powershell.md)