add devtest users

Author: v-thepet

articles/devtest-labs/devtest-lab-add-devtest-user.md

@@ -1,136 +1,127 @@
 ---
 title: Add owners and users
-description: Add owners and users in Azure DevTest Labs using either the Azure portal or PowerShell
+description: Learn about the Azure DevTest Labs Owner, Contributor, and DevTest Labs User roles, and how to add members to lab roles by using the Azure portal or Azure PowerShell.
 ms.topic: how-to
-ms.date: 06/26/2020 
+ms.date: 01/21/2022
 ms.custom: devx-track-azurepowershell
 ---
 
-# Add owners and users in Azure DevTest Labs
-
-Access in Azure DevTest Labs is controlled by [Azure role-based access control (Azure RBAC)](../role-based-access-control/overview.md). Using Azure RBAC, you can segregate duties within your team into *roles* where you grant only the amount of access necessary to users to perform their jobs. Three of these Azure roles are *Owner*, *DevTest Labs User*, and *Contributor*. In this article, you learn what actions can be performed in each of the three main Azure roles. From there, you learn how to add users to a lab - both via the portal and via a PowerShell script, and how to add users at the subscription level.
-
-## Actions that can be performed in each role
-There are three main roles that you can assign a user:
-
-* Owner
-* DevTest Labs User
-* Contributor
-
-The following table illustrates the actions that can be performed by users in each of these roles:
-
-| **Actions users in this role can perform** | **DevTest Labs User** | **Owner** | **Contributor** |
-| --- | --- | --- | --- |
-| **Lab tasks** | | | |
-| Add users to a lab |No |Yes |No |
-| Update cost settings |No |Yes |Yes |
-| **VM base tasks** | | | |
-| Add and remove custom images |No |Yes |Yes |
-| Add, update, and delete formulas |Yes |Yes |Yes |
-| Enable Marketplace images |No |Yes |Yes |
-| **VM tasks** | | | |
-| Create VMs |Yes |Yes |Yes |
-| Start, stop, and delete VMs |Only VMs created by the user |Yes |Yes |
-| Update VM policies |No |Yes |Yes |
-| Add/remove data disks to/from VMs |Only VMs created by the user |Yes |Yes |
-| **Artifact tasks** | | | |
-| Add and remove artifact repositories |No |Yes |Yes |
-| Apply artifacts |Yes |Yes |Yes |
+# Azure DevTest Labs owners, contributors, and users
 
-> [!NOTE]
-> When a user creates a VM, that user is automatically assigned to the **Owner** role of the created VM.
-> 
-> 
+This article describes the three built-in Azure DevTest Labs roles: *Owner*, *Contributor*, and *DevTest Labs User*, and how to add users with those roles to labs. DevTest Labs uses Azure [role-based access control](../role-based-access-control/overview.md) (Azure RBAC) to define roles that have only the necessary access to do certain lab tasks. This article describes the tasks each role can do, and how to add users to lab roles by using the Azure portal or an Azure PowerShell script.
 
-## Add an owner or user at the lab level
-Owners and users can be added at the lab level via the Azure portal. 
-A user can be an external user with a valid [Microsoft account (MSA)](./devtest-lab-faq.yml).
-The following steps guide you through the process of adding an owner or user to a lab in Azure DevTest Labs:
+## Actions each role can take
 
-1. Sign in to the [Azure portal](https://portal.azure.com) as [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).
+Lab Owner, Contributor, and DevTest Labs User roles can take the following actions in DevTest Labs:
 
-1. Open the desired resource group and select **DevTest Labs**.
+### Owner
 
-1. In the navigation menu, select **Access control (IAM)**.
+The lab Owner role can take all of the following actions:
 
-1. Select **Add** > **Add role assignment**.
+Lab tasks:
+- Add users to the lab
+- Update cost settings
 
-    ![Access control (IAM) page with Add role assignment menu open.](../../includes/role-based-access-control/media/add-role-assignment-menu-generic.png)
+Virtual machine (VM) base tasks:
+- Add and remove custom images
+- Add, update, and delete formulas
+- Enable Marketplace images
 
-1. On the **Role** tab, select the **OWNER** or **USER** role.
+VM tasks:
+- Create VMs
+- Start, stop, or delete VMs
+- Update VM policies
+- Add or remove VM data disks
 
-    ![Add role assignment page with Role tab selected.](../../includes/role-based-access-control/media/add-role-assignment-role-generic.png)
+Artifact tasks:
+- Add and remove artifact repositories
+- Apply artifacts to VMs
 
-1. On the **Members** tab, select the user you want to give the desired role to.
+### Contributor
 
-1. On the **Review + assign** tab, select **Review + assign** to assign the role.
+The lab Contributor role can take all the same actions as lab Owner, except it can't add users to labs.
 
+### DevTest Labs User
 
-## Add an external user to a lab using PowerShell
+The DevTest Labs User role can take the following actions in DevTest Labs:
 
-[!INCLUDE [updated-for-az](../../includes/updated-for-az.md)]
+- Add, update, and delete VM base formulas.
+- Create VMs.
+- Start, stop, or delete VMs the user creates.
+- Add or remove data disks from VMs the user creates.
+- Apply artifacts to VMs.
+
+> [!NOTE]
+> Lab users automatically have the **Owner** role on VMs they create.
+
+## Add Owners, Contributors, or DevTest Labs Users
 
-In addition to adding users in the Azure portal, you can add an external user to your lab using a PowerShell script. 
-In the following example, modify the parameter values under the **Values to change** comment.
-You can retrieve the `subscriptionId`, `labResourceGroup`, and `labName` values from the lab blade in the Azure portal.
+A lab Owner can add members to lab roles by using the Azure portal or an Azure PowerShell script. The user to add can be an external user with a valid [Microsoft account (MSA)](./devtest-lab-faq.yml).
+
+Azure permissions propagate from parent scope to child scope. Owners of an Azure subscription that contains labs are automatically owners of the subscription's DevTest Labs service, the labs, and the VMs and other resources they contain. Subscription owners can add Owners, Contributors, and DevTest Labs Users to labs in the subscription.
 
 > [!NOTE]
-> The sample script assumes that the specified user has been added as a guest to the Active Directory, and will fail if that is not the case. To add a user not in the Active Directory to a lab, use the Azure portal to assign the user to a role as illustrated in the section, [Add an owner or user at the lab level](#add-an-owner-or-user-at-the-lab-level).   
-> 
-> 
+> Added lab Owners' scope of administration is narrower than the subscription owner's scope. Added Owners don't have full access to some resources that the DevTest Labs service creates.
 
-```azurepowershell
-# Add an external user in DevTest Labs user role to a lab
-# Ensure that guest users can be added to the Azure Active directory:
-# https://azure.microsoft.com/documentation/articles/active-directory-create-users/#set-guest-user-access-policies
+### Prerequisites
 
-# Values to change
-$subscriptionId = "<Enter Azure subscription ID here>"
-$labResourceGroup = "<Enter lab's resource name here>"
-$labName = "<Enter lab name here>"
-$userDisplayName = "<Enter user's display name here>"
+- You must be an Owner of the lab, either directly or by inheritance as a subscription owner.
+- Sign in to the [Azure portal](https://portal.azure.com) as an [Owner](../role-based-access-control/built-in-roles.md#owner) or [User Access Administrator](../role-based-access-control/built-in-roles.md#user-access-administrator).
 
-# Log into your Azure account
-Connect-AzAccount
+### Add a member to a lab by using the Azure portal
 
-# Select the Azure subscription that contains the lab. 
-# This step is optional if you have only one subscription.
-Select-AzSubscription -SubscriptionId $subscriptionId
+- To add a user at the subscription level, open the subscription page.
+- To add a user at the lab level, open the resource group that has the lab, and select the lab from the list of resources.
 
-# Retrieve the user object
-$adObject = Get-AzADUser -SearchString $userDisplayName
+1. In the left navigation for the subscription or lab, select **Access control (IAM)**.
 
-# Create the role assignment. 
-$labId = ('subscriptions/' + $subscriptionId + '/resourceGroups/' + $labResourceGroup + '/providers/Microsoft.DevTestLab/labs/' + $labName)
-New-AzRoleAssignment -ObjectId $adObject.Id -RoleDefinitionName 'DevTest Labs User' -Scope $labId
-```
+1. Select **Add** > **Add role assignment**.
 
-## Add an owner or user at the subscription level
-Azure permissions are propagated from parent scope to child scope in Azure. Therefore, owners of an Azure subscription that contains labs are automatically owners of those labs. They also own the VMs and other resources created by the lab's users, and the Azure DevTest Labs service. 
+   ![Screenshot that shows an access control (IAM) page with the Add role assignment menu open.](media/devtest-lab-add-devtest-user/add-role-assignment-menu-generic.png)
 
-You can add additional owners to a lab via the lab's blade in the [Azure portal](https://go.microsoft.com/fwlink/p/?LinkID=525040). 
-However, the added owner's scope of administration is more narrow than the subscription owner's scope. 
-For example, the added owners do not have full access to some of the resources that are created in the subscription by the DevTest Labs service. 
+1. On the **Add Role Assignment** page, select the **Owner**, **Contributor**, or **User** role, and then select **Next**.
 
-To add an owner to an Azure subscription, follow these steps:
+   ![Screenshot that shows the Add role assignment page with the Role tab selected.](media/devtest-lab-add-devtest-user/add-role-assignment-role-generic.png)
 
-1. Sign in to the [Azure portal](https://portal.azure.com) as [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).
+1. On the **Members** tab, select **Select members**.
 
-1. Open the desired Subscription group.
+1. On the **Select members** screen, select the member you want to add, and then select **Select**.
 
-1. In the navigation menu, select **Access control (IAM)**.
+1. Select **Review + assign**, and after reviewing the details, select **Review + assign** again.
 
-1. Select **Add** > **Add role assignment**.
+### Add a DevTest Labs User to a lab by using Azure PowerShell
+
+[!INCLUDE [updated-for-az](../../includes/updated-for-az.md)]
+
+You can add a DevTest Labs User to a lab by using the following Azure PowerShell script. The script requires the user to be in the Azure Active Directory (Azure AD). For information about adding an external user to Azure AD as a guest, see [Add a new guest user](/active-directory/fundamentals/add-users-azure-active-directory#add-a-new-guest-user). If the user isn't in Azure AD, the script fails. Use the portal procedure instead.
+
+In the following script, update the parameter values under the `# Values to change` comment. You can get the `subscriptionId`, `labResourceGroup`, and `labName` values from the lab's main page in the Azure portal.
+
+```azurepowershell
+# Add an external user to a lab user role in DevTest Labs.
+# Make sure the guest user is added to Azure AD.
 
-    ![Access control (IAM) page with Add role assignment menu open.](../../includes/role-based-access-control/media/add-role-assignment-menu-generic.png)
+# Values to change
+$subscriptionId = "<Azure subscription ID>"
+$labResourceGroup = "<Lab's resource group name>"
+$labName = "<Lab name>"
+$userDisplayName = "<User's display name>"
 
-1. On the **Role** tab, select the **OWNER** role.
+# Log into your Azure account.
+Connect-AzAccount
 
-    ![Add role assignment page with Role tab selected.](../../includes/role-based-access-control/media/add-role-assignment-role-generic.png)
+# Select the Azure subscription that contains the lab. This step is optional if you have only one subscription.
+Select-AzSubscription -SubscriptionId $subscriptionId
 
-1. On the **Members** tab, select the user you want to give the owner role to.
+# Get the user object.
+$adObject = Get-AzADUser -SearchString $userDisplayName
 
-1. On the **Review + assign** tab, select **Review + assign** to assign the role.
+# Create the role assignment. 
+$labId = ('subscriptions/' + $subscriptionId + '/resourceGroups/' + $labResourceGroup + '/providers/Microsoft.DevTestLab/labs/' + $labName)
+New-AzRoleAssignment -ObjectId $adObject.Id -RoleDefinitionName 'DevTest Labs User' -Scope $labId
+```
 
+## Next steps
 
-[!INCLUDE [devtest-lab-try-it-out](../../includes/devtest-lab-try-it-out.md)]
+- [Customize permissions with custom roles](devtest-lab-grant-user-permissions-to-specific-lab-policies.md)
+- [Automate adding lab users](automate-add-lab-user.md)