Manage Lab management permission through scripts

Article
11/14/2014

Lab Management has TfsLabConfig.exe command with which the Lab permissions can be managed. At times, there might be need for script to iterate through objects and set permissions. In the following blog, I would like to share how we can make use of Lab Management client and author PowerShell script for accomplishing the same. This script should be run as collection admin if you would like to manage permissions at collection level. The script should be run from a machine with VS 2012 where the TFS and Lab client dlls are available.

Please note that, using TfsLabConfig.exe would still be the recommended way, wherever possible.

#######################################################################################
#/// <Valid permissions that can be set>
#        /// Permission to query properties or status of Lab Management artifacts
#        /// </summary>
#        Read = 1,
#        /// <summary>
#        /// Permission to import virtual machine images into Lab Management
#        /// </summary>
#        Create = 2,
#        /// <summary>
#        /// Permission to create new Lab Management artifacts eg. creating LabEnvironment or creating LabTemplate from LabSystem.
#        /// </summary>
#        Write = 4,
#        /// <summary>
#        /// Permission to update properties of existing Lab Management artifacts
#        /// </summary>
#        Edit = 8,
#        /// <summary>
#        /// Permission to delete existing Lab Management artifacts
#        /// </summary>
#        Delete = 16,
#        /// <summary>
#        /// Permission to start machines
#        /// </summary>
#        Start = 32,
#        /// <summary>
#        /// Permission to stop machines
#        /// </summary>
#        Stop = 64,
#        /// <summary>
#        /// Permission to pause machines
#        /// </summary>
#        Pause = 128,
#        /// <summary>
#        /// Permission to create, apply and delete virtual machine snapshots
#        /// </summary>
#        ManageSnapshots = 256,
#        /// <summary>
#        /// Permissions to create, query or change properties of Lab Locations
#        /// </summary>
#        /// <remarks>Lab Locations are places that contain virtual machines, such as Host Groups and Library Shares</remarks>
#        ManageLocation = 512,
#        /// <summary>
#        /// Permission to delete Lab Locations
#        /// </summary>
#        DeleteLocation = 1024,
#        /// <summary>
#        /// Permission to change permissions on any Lab Management artifact
#        /// </summary>
#        ManagePermissions = 2048,
#        /// <summary>
#        /// Permission to change permissions on children (in security hierarchy) of any Lab Management artifact
#        /// </summary>
#        ManageChildPermissions = 4096,
#
#        ManageTestMachines = 8192
###########################################################################

#Function to deny permission for a user on an object
function Deny-LabPermissions
{
    param (
        [Parameter(Mandatory = $true)]
        $objecturi,
        [Parameter(Mandatory = $true)]
        $useridentity,
        [Parameter(Mandatory = $true)]
        $labinheritancechange,
        [Parameter(Mandatory = $true)]
        $denymask
        )

    process
    {
        $permlist = New-Object System.Collections.Generic.List``1[Microsoft.TeamFoundation.Lab.Client.LabPermissionChange];
        $labpermissionchange = New-Object Microsoft.TeamFoundation.Lab.Client.LabPermissionChange;
        $labpermissionchange.Denymask = $denymask;
        $labpermissionchange.IdentityName = $useridentity;
        $permlist.Add($labpermissionchange);

        $labsecuritydesc = New-Object Microsoft.TeamFoundation.Lab.Client.LabSecurityDescriptor;
        $labsecuritydesc.LabInheritanceChange = $labinheritancechange;
        $labsecuritydesc.LabPermissionChanges = $permlist;

$labService.UpdateObjectSecurity($labsecuritydesc, $objecturi);
}
}

#Function to allow permission for a user on an object
function Allow-LabPermissions
{
    param (
        [Parameter(Mandatory = $true)]
        $objecturi,
        [Parameter(Mandatory = $true)]
        $useridentity,
        [Parameter(Mandatory = $true)]
        $labinheritancechange,
        [Parameter(Mandatory = $true)]
        $allowmask
        )

    process
    {
        $permlist = New-Object System.Collections.Generic.List``1[Microsoft.TeamFoundation.Lab.Client.LabPermissionChange];
        $labpermissionchange = New-Object Microsoft.TeamFoundation.Lab.Client.LabPermissionChange;
        $labpermissionchange.Allowmask = $allowmask;
        $labpermissionchange.IdentityName = $useridentity;
        $permlist.Add($labpermissionchange);

$labService.UpdateObjectSecurity($labsecuritydesc, $objecturi);
}
}

# Specify the tfs collection url, projectName and test controllerName
$tfsCollectionUrl = New-Object System.URI("<collectionURL>");
$projectName = "<ProjectName>";

# Load Client Assembly
[Reflection.Assembly]::Load(“Microsoft.TeamFoundation.Client, Version=12.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a”);
[Reflection.Assembly]::Load(“Microsoft.TeamFoundation.Common, Version=12.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a”);
[Reflection.Assembly]::Load(“Microsoft.TeamFoundation.Lab.Client, Version=12.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a”);
[Reflection.Assembly]::Load(“Microsoft.TeamFoundation.Lab.Common, Version=12.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a”);

# Connect to tfs
$tfsCollection = [Microsoft.TeamFoundation.Client.TfsTeamProjectCollectionFactory]::GetTeamProjectCollection($tfsCollectionUrl);
$labService = $tfsCollection.GetService([Microsoft.TeamFoundation.Lab.Client.LabService]);

#To find valid permission for each object type. Not all objects have all permission types.
$labService.GetValidPermissionsForObject([Microsoft.TeamFoundation.Lab.Client.TeamProjectCollectionHostGroup]);
$labService.GetValidPermissionsForObject([Microsoft.TeamFoundation.Lab.Client.TeamProjectCollectionLibraryShare]);
$labService.GetValidPermissionsForObject([Microsoft.TeamFoundation.Lab.Client.TeamProjectHostGroup]);
$labService.GetValidPermissionsForObject([Microsoft.TeamFoundation.Lab.Client.TeamProjectLibraryShare]);

#you can also specify TFS groups - $identitylist.Add("[DefaultCollection]\Project Collection Administrators");
$useridentity = "<domain\user>;
$identitylist = New-Object System.Collections.Generic.List``1[String];
$identitylist.Add($useridentity);

#A sample to list and modify permissions for user(s) on Host group
$hglist = New-Object System.Collections.Generic.List``1[String];
$hglist.Add("All Hosts"); #Sample Host group name
$hglist.Add("All Hosts_HG1"); #Sample Host group name
$hgsecurity = $null;
$hglist | ForEach-Object -Process {
    #Find the corresponding URI
    $tpchgqueryspec = New-Object Microsoft.TeamFoundation.Lab.Client.TeamProjectCollectionHostGroupQuerySpec;
    $tpchgqueryspec.Name = $_;
    $hg = $labService.QueryTeamProjectCollectionHostGroups($tpchgqueryspec);
    $hguri = $hg[0].Uri.AbsoluteUri;

    #List Current permission
    $hgsecurity = $labService.GetObjectSecurity($identitylist, $hguri);
    $hgsecurity;

    #Update permission
    $allowmask = 2048; # Manage permissions. Refer list above.
    $denymask = 1023; # delete location. Refer list above.

    "Changing permission for " + $useridentity + " on object " + $hguri;
    Allow-LabPermissions -objecturi $hguri -useridentity $useridentity -labinheritancechange $true -allowmask $allowmask;
    Deny-LabPermissions -objecturi $hguri -useridentity $useridentity -labinheritancechange $true -denymask $denymask;
}

Manage Lab management permission through scripts

Additional resources