This article is contributed. See the original author and article here.

Azure provides a few built-in roles to allow or deny actions for Azure Lab Services.  These built-in roles include owner, contributor, lab creator, and reader.  If the built-in roles don’t fit your needs, you can also create and deploy a custom role. That is what we will do in this blog post.


In this scenario we need to create a Lab Liaison role.  A lab Liaison is a technical helper that will be able to reset student VMs for multiple labs and nothing else. We build off of the information in the previous post, Use Custom Role to Tailor Teachers’ Lab Management Permissions.


Defining the Lab Liaison Role

First, things first.  Let’s define our custom role. We’ll look at the overall role definition, and then discuss each section.



    "properties": {
        "roleName": "Lab Liaison",
        "description": "Lab Liaison can reset student VMs when necessary.",
        "assignableScopes": [
        "permissions": [
                "actions": [
                "notActions": [],
                "dataActions": [],
                "notDataActions": []



Roles contain a name, description, assignable scopes, and a list of allowed or not allowed actions.  Assignable scopes determine at what level a role can be assigned.  This may be a management group (preview), entire subscriptions (as shown above) or a specific resource groups.


Our custom role lists five specific actions.  Let’s go over why we need each action.





Allows the Lab Liaison to see the labs under each lab account.


Allows the Lab Liaison to reset a VM for any VM in a lab.




These three actions are the minimum required set of actions for to successfully load for a user.


You’ll notice that we only list specific allowed actions.  The advantage to this approach is that we can assign this role once to a user at the subscription or resource group level and that will affect resources contained within the subscription or resource group.  The Lab Liaison will have access see the VMs, reset the VMs in the Labs Portal and nothing else.  Lab Liaison will not be able to inadvertently set a schedule or change lab settings that affect the cost or running a lab. 


If you are creating a role that is less restrictive, consider using wildcard permissions in conjunction with the notAction section to exclude only specific permissions. 


Deploying Custom Role

There are a few ways to create or add a custom role in Azure including using the Azure Portal, Azure CLI or PowerShell.  We are going to use PowerShell today.


First, we to create a new custom role object.



$role = New-Object ` 
 -TypeName 'Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition'
$role.Id = $null
$role.Name = "Lab Liaison Role"
$role.Description = "Can view labs in Azure Lab portal and reset student VMs."
$role.IsCustom = $true
$role.Actions = @()
$role.AssignableScopes = @()



Next, let’s set the assignable scope to the current subscription.  (Run Connect-AzAccount first, if not done already.)  You can add more than one assignable scope if there are several management groups, subscriptions and/or resource groups that should have this role available.



$currentSubscriptionId = Get-AzContext `
 | Select-Object -expand Subscription `
 | Select-Object -expand Id



Next, let’s add the specific actions we need for the Lab Liaison Role.



$roleAssignmentsToAdd = @(

$roleAssignmentsToAdd | 
ForEach-Object {



Lastly, let’s add the newly created custom role to Azure.



New-AzRoleDefinition -Role $role



Go to Import-LabLiaisonRole.ps1 to see this script in its entirety.  The full script also contains the ability to assign the role to several subscriptions at once, ability to update an existing role, and extra error checking.


Assigning a Custom Role

Yeah! Our custom role is now available for use.  Now let’s assign the role to someone.  Roles can be assigned to users, groups, and service principals. 


For our example, we will assign a specific user,,  access at the resource group level.  The user will be able to reset VMs under any lab under any lab account in that resource group. Role assignments require the

  • Active Directory object id.  This is the id of the user, group, or service principal

  • Scope the assignment affects.  For example if assignment is made at the resource group level, it will affect all resources in that group, including any lab accounts and labs in that resource group.

  • Name of role definition.  In our case, that’s ‘Lab Liaison’

We are going to assign the role to a user, so let’s find the id for the user first.



#Get AD object id for user.  Try both user principal name and email
$email = ''
$userAdObject = $null
$userAdObject = Get-AzADUser `
-UserPrincipalName $email.ToString().Trim() `
-ErrorAction SilentlyContinue
if (-not $userAdObject){
$userAdObject = Get-AzADUser `
   -Mail $email.ToString().Trim() `
   -ErrorAction SilentlyContinue
if (-not $userAdObject){
 	Write-Error "Couldn't find user '$email' in Azure AD."



Next, we need to get the id of the resource group, so we can set the scope of the role assignment.



$resourceGroupeId = Get-AzResourceGroup `
 -ResourceGroupName '{resource-group-name}' `
 | Select-Object -ExpandProperty ResourceId



Now we are all set to make the role assignment.  Creating a role assignment with the same object id, definition name and scope will throw an error, so we’ll only create the role assignment if it doesn’t exist already.



$RoleDefinitionName = "Lab Services Liaison"
if (-not (Get-AzRoleAssignment `
 -ObjectId $userAdObject.Id `
 -RoleDefinitionName $RoleDefinitionName `
 -Scope $resourceGroupId `
 -ErrorAction SilentlyContinue)) {

New-AzRoleAssignment `
    -ObjectId $userAdObject.Id `
    -RoleDefinitionName $RoleDefinitionName 
    -Scope $resourceGroupId



Role assignments can be made with the subscription, resource group, lab account and even specific lab as the scope.  Just pass in the resource id for that resource to the scope argument.  Consider using the Az.LabServices PowerShell module (preview) to make the task of getting resource id for lab accounts and labs easier. 



You are all set!  We’ve defined, imported, and assigned our Lab Liaison custom role.  If you want to create a role with more permission, refer back to the Use Custom Role to Tailor Teachers’ Lab Management Permissions – Microsoft Tech Community blog post.  It has a nice list of Lab Services permissions and their purpose.


We hope that you find this post helpful!

~Az Labs team

Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.

%d bloggers like this: