Security cmdlet Improvements and added Add-VSTeamBuildPermission (#386)

* made deny and allow mask non mandatory
* added ability to resolve service identity descriptor
* added cmdlet Add-VSTeamBuildPermission

.docs/Add-VSTeamBuildPermission.md

@@ -0,0 +1,118 @@
+<!-- #include "./common/header.md" -->
+
+# Add-VSTeamBuildPermission
+
+## SYNOPSIS
+
+<!-- #include "./synopsis/Add-VSTeamBuildPermission.md" -->
+
+## SYNTAX
+
+## DESCRIPTION
+
+<!-- #include "./synopsis/Add-VSTeamBuildPermission.md" -->
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+  $project = Get-VSTeamProject -Name MyProject
+  $user = Get-VSTeamUser -Descriptor "Microsoft.IdentityModel.Claims.ClaimsIdentity;788df857-dcd8-444d-885e-bff359bc1982\\[email protected]"
+  Add-VSTeamBuildPermission -Project $project -User $user -Allow DestroyBuilds, DeleteBuildDefinition, AdministerBuildPermissions -Deny StopBuilds, QueueBuilds, EditBuildDefinition
+```
+
+Adds the user '[email protected]' with the given descriptor to the build pipelines on project level. Permits the user to destroy builds, delete build definitions and administer them. Also denies to stop or queue builds as well as editing build definitions.
+
+### Example 2
+
+```powershell
+  $project = Get-VSTeamProject -Name MyProject
+  $user = Get-VSTeamUser -Descriptor "Microsoft.IdentityModel.Claims.ClaimsIdentity;788df857-dcd8-444d-885e-bff359bc1982\\[email protected]"
+Add-VSTeamBuildPermission -Project $project -User $user
+Warning: Permission masks for Allow and Deny do not inlude any permission. No Permission will change!
+```
+
+Tries to the user '[email protected]' with the given descriptor to the build pipelines on project level. No permissions (allow and deny) are given, it is possible but a warning is thrown.
+
+### Example 3
+
+```powershell
+  $project = Get-VSTeamProject -Name MyProject
+  $user = Get-VSTeamUser -Descriptor "Microsoft.IdentityModel.Claims.ClaimsIdentity;788df857-dcd8-444d-885e-bff359bc1982\\[email protected]"
+Add-VSTeamBuildPermission -Project $project -BuildID 5 -User $user -Allow DestroyBuilds -Deny StopBuilds
+```
+
+Allows the user '[email protected]' to the build with ID 5 to destry builds and deny to stop builds.
+
+## PARAMETERS
+
+### BuildID
+
+The build ID of the build pipeline to permit the identity object to.
+
+```yaml
+Type: String
+Required: True
+```
+
+### Descriptor
+
+The descriptor of the user or group to permit to
+
+```yaml
+Type: String
+Required: True
+```
+
+### User
+
+The user or service account to permit to. Service accounts are handled like normal users. The descriptor differs a little bit.
+
+```yaml
+Type: VSTeamUser
+Required: True
+```
+
+### Group
+
+The group to permit to
+
+```yaml
+Type: VSTeamGroup
+Required: True
+```
+
+### Allow
+
+Permissions that should be allowed. If no permissions are needed, then leave this parameter out.
+
+```yaml
+Type: VSTeamProjectPermissions
+Required: True
+```
+
+### Deny
+
+Permissions that should be denied. If no permissions are needed, then leave this parameter out.
+
+```yaml
+Type: VSTeamProjectPermissions
+Required: True
+```
+
+<!-- #include "./params/projectName.md" -->
+
+## INPUTS
+
+## OUTPUTS
+
+### System.Object
+
+## NOTES
+
+<!-- #include "./common/prerequisites.md" -->
+
+## RELATED LINKS
+
+<!-- #include "./common/related.md" -->

.docs/synopsis/Add-VSTeamBuildPermission.md

@@ -0,0 +1 @@
+Add Permissions to builds and multi staging pipelines

CHANGELOG.md

@@ -19,6 +19,12 @@ $buildId = Get-VSTeamBuild -Top 1
 Get-VSTeamRelease -artifactVersionId $buildId.Id
 ```
 
+Merged [Pull Request](https://github.com/DarqueWarrior/vsteam/pull/386) from [Sebastian Schütze](https://github.com/SebastianSchuetze) which included the following:
+
+- added the cmdlet Add-VSTeamBuildPermission following the other cmdlet like Add-VSTeamProjectPermission
+- changed internal permission (ACL) functions to not have deny or allow permissions to be mandatory, because this caused not to be able to only add allow or deny permissions.
+- allowed to handle user accounts from typ 'srv' which are service accounts of Azure DevOps. Now these can be permitted as well to all functions using ACLs
+
 ## 7.2.0
 
 Merged [Pull Request](https://github.com/DarqueWarrior/vsteam/pull/371) and (https://github.com/DarqueWarrior/vsteam/pull/389) from [Sebastian Schütze](https://github.com/SebastianSchuetze) which included the following:

Source/Classes/Provider/BuildPermissions.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace vsteam_lib
+{
+   [Flags]
+   public enum BuildPermissions
+   {
+      ViewBuilds = 1,
+      EditBuildQuality = 2,
+      RetainIndefinitely = 4,
+      DeleteBuilds = 8,
+      ManageBuildQualities = 16,
+      DestroyBuilds = 32,
+      UpdateBuildInformation = 64,
+      QueueBuilds = 128,
+      ManageBuildQueue = 256,
+      StopBuilds = 512,
+      ViewBuildDefinition = 1024,
+      EditBuildDefinition = 2048,
+      DeleteBuildDefinition = 4096,
+      OverrideBuildCheckInValidation = 8192,
+      AdministerBuildPermissions = 16384
+   }
+}

Source/Private/common.ps1

@@ -99,10 +99,9 @@ function _callAPI {
       }
 
       # We have to remove any extra parameters not used by Invoke-RestMethod
-
       $extra = 'NoAccount', 'NoProject', 'UseProjectId', 'Area', 'Resource', 'SubDomain', 'Id', 'Version', 'JSON', 'ProjectName', 'Team', 'Url', 'QueryString', 'AdditionalHeaders', 'CustomBearer'
 
-   foreach ($e in $extra) { $params.Remove($e) | Out-Null }
+      foreach ($e in $extra) { $params.Remove($e) | Out-Null }
 
       try {
          $resp = Invoke-RestMethod @params
@@ -596,6 +595,7 @@ function _buildProjectNameDynamicParam {
       }
    #>
 }
+
 function _buildProcessNameDynamicParam {
    param(
       [string] $ParameterName = 'ProcessName',
@@ -1014,7 +1014,13 @@ function _getDescriptorForACL {
       switch ($User.Origin) {
          "vsts" {
             $sid = _getVSTeamIdFromDescriptor -Descriptor $User.Descriptor
-            $descriptor = "Microsoft.TeamFoundation.Identity;$sid"
+
+            if ($User.Descriptor.StartsWith('svc.')) {
+               $descriptor = "Microsoft.TeamFoundation.ServiceIdentity;$sid"
+            }
+            else {
+               $descriptor = "Microsoft.TeamFoundation.Identity;$sid"
+            }
          }
          "aad" {
             $descriptor = "Microsoft.IdentityModel.Claims.ClaimsIdentity;$($User.Domain)\\$($User.PrincipalName)"
@@ -1067,4 +1073,4 @@ function _getBillingToken {
       -body ($sessionToken | ConvertTo-Json -Depth 50 -Compress)
 
    return $billingToken
-}
+}

Source/Public/Add-VSTeamAccessControlEntry.ps1

@@ -14,7 +14,7 @@
 
 function Add-VSTeamAccessControlEntry {
    [CmdletBinding(DefaultParameterSetName = 'ByNamespace',
-    HelpUri='https://methodsandpractices.github.io/vsteam-docs/docs/modules/vsteam/commands/Add-VSTeamAccessControlEntry')]
+      HelpUri='https://methodsandpractices.github.io/vsteam-docs/docs/modules/vsteam/commands/Add-VSTeamAccessControlEntry')]
    param(
       [Parameter(ParameterSetName = 'ByNamespace', Mandatory = $true, ValueFromPipeline = $true)]
       [vsteam_lib.SecurityNamespace] $SecurityNamespace,
@@ -37,6 +37,11 @@ function Add-VSTeamAccessControlEntry {
       [int] $DenyMask
    )
    process {
+
+      if ($AllowMask -eq 0 -and $DenyMask -eq 0) {
+         Write-Warning "Permission masks for Allow and Deny do not inlude any permission. No Permission will change!"
+      }
+
       if ($SecurityNamespace) {
          $SecurityNamespaceId = $SecurityNamespace.ID
       }

Source/Public/Add-VSTeamBuildPermission.ps1

@@ -0,0 +1,71 @@
+# Add or update ACEs in the ACL for the provided token. The request body
+# contains the target token, a list of ACEs and a optional merge parameter.
+# In the case of a collision (by identity descriptor) with an existing ACE
+# in the ACL, the "merge" parameter determines the behavior. If set, the
+# existing ACE has its allow and deny merged with the incoming ACE's allow
+# and deny. If unset, the existing ACE is displaced.
+#
+# Get-VSTeamOption 'Security' 'AccessControlEntries'
+# id              : ac08c8ff-4323-4b08-af90-bcd018d380ce
+# area            : Security
+# resourceName    : AccessControlEntries
+# routeTemplate   : _apis/{resource}/{securityNamespaceId}
+# https://bit.ly/Add-VSTeamAccessControlEntry
+
+function Add-VSTeamBuildPermission {
+   [CmdletBinding(DefaultParameterSetName = 'ByProjectAndUser',
+      HelpUri = 'https://methodsandpractices.github.io/vsteam-docs/docs/modules/vsteam/commands/Add-VSTeamBuildPermission')]
+   param(
+      [parameter(Mandatory = $true)]
+      [string]$ProjectID,
+
+      [parameter(Mandatory = $false)]
+      [string]$BuildID,
+
+      [parameter(Mandatory = $true, ParameterSetName = "ByProjectAndDescriptor")]
+      [string]$Descriptor,
+
+      [parameter(Mandatory = $true, ParameterSetName = "ByProjectAndGroup")]
+      [object]$Group,
+
+      [parameter(Mandatory = $true, ParameterSetName = "ByProjectAndUser")]
+      [object]$User,
+
+      [parameter(Mandatory = $false)]
+      [vsteam_lib.BuildPermissions]$Allow,
+
+      [parameter(Mandatory = $false)]
+      [vsteam_lib.BuildPermissions]$Deny
+   )
+
+   process {
+      # SecurityNamespaceID: 33344d9c-fc72-4d6f-aba5-fa317101a7e9
+      # Token: <projectId>/<pipelineId>
+
+      $securityNamespaceId = "33344d9c-fc72-4d6f-aba5-fa317101a7e9"
+
+      # Resolve Group to Descriptor
+      if ($Group) {
+         $Descriptor = _getDescriptorForACL -Group $Group
+      }
+
+      # Resolve User to Descriptor
+      if ($User) {
+         $Descriptor = _getDescriptorForACL -User $User
+      }
+
+      $token = $null
+      if ($BuildID) {
+         $token = "$ProjectID/$($BuildID)"
+      }
+      else {
+         $token = "$ProjectID"
+      }
+
+      Add-VSTeamAccessControlEntry -SecurityNamespaceId $securityNamespaceId `
+         -Descriptor $Descriptor `
+         -Token $token `
+         -AllowMask ([int]$Allow) `
+         -DenyMask ([int]$Deny)
+   }
+}

Source/Public/Add-VSTeamGitRepositoryPermission.ps1

@@ -52,10 +52,10 @@ function Add-VSTeamGitRepositoryPermission {
       [parameter(Mandatory = $true, ParameterSetName = "ByRepositoryNameAndUser")]
       [vsteam_lib.User]$User,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.GitRepositoryPermissions]$Allow,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.GitRepositoryPermissions]$Deny
    )
 

Source/Public/Add-VSTeamProjectPermission.ps1

@@ -14,7 +14,7 @@
 
 function Add-VSTeamProjectPermission {
    [CmdletBinding(DefaultParameterSetName = 'ByProjectAndUser',
-    HelpUri='https://methodsandpractices.github.io/vsteam-docs/docs/modules/vsteam/commands/Add-VSTeamProjectPermission')]
+      HelpUri = 'https://methodsandpractices.github.io/vsteam-docs/docs/modules/vsteam/commands/Add-VSTeamProjectPermission')]
    param(
       [parameter(Mandatory = $true)]
       [vsteam_lib.Project]$Project,
@@ -28,10 +28,10 @@ function Add-VSTeamProjectPermission {
       [parameter(Mandatory = $true, ParameterSetName = "ByProjectAndUser")]
       [vsteam_lib.User]$User,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.ProjectPermissions]$Allow,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.ProjectPermissions]$Deny
    )
 

Source/Public/Add-VSTeamWorkItemAreaPermission.ps1

@@ -41,10 +41,10 @@ function Add-VSTeamWorkItemAreaPermission {
       [parameter(Mandatory = $true, ParameterSetName = "ByProjectAndAreaIdAndUser")]
       [vsteam_lib.User]$User,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.WorkItemAreaPermissions]$Allow,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.WorkItemAreaPermissions]$Deny
    )
 

Source/Public/Add-VSTeamWorkItemIterationPermission.ps1

@@ -41,10 +41,10 @@ function Add-VSTeamWorkItemIterationPermission {
       [parameter(Mandatory = $true, ParameterSetName = "ByProjectAndIterationIdAndUser")]
       [vsteam_lib.User]$User,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.WorkItemIterationPermissions]$Allow,
 
-      [parameter(Mandatory = $true)]
+      [parameter(Mandatory = $false)]
       [vsteam_lib.WorkItemIterationPermissions]$Deny
    )
 

Tests/SampleFiles/serviceUsers.single.json

@@ -0,0 +1,28 @@
+{
+   "subjectKind": "user",
+   "domain": "Build",
+   "principalName": "fb855a12-eacc-4ace-9247-6fa867d60629",
+   "mailAddress": "",
+   "origin": "vsts",
+   "originId": "2b9ef1a4-2295-4ae4-a00f-003bfeadc56b",
+   "displayName": "Dfb855a12-eacc-4ace-9247-6fa867d60629 Build Service (Test Project Public)",
+   "_links": {
+      "self": {
+         "href": "https://vssps.dev.azure.com/Test Project Public/_apis/Graph/Users/svc.NTNjNjc0MjQtNjAzNy00ZjQ0LTgzYmQtOTBiOWRmYzdkMzVkOkJ1aWxkOmZiODU1YTEyLWVhY2MtNGFjZS05MjQ3LTZmYTg2N2Q2MDYyOQ"
+      },
+      "memberships": {
+         "href": "https://vssps.dev.azure.com/Test Project Public/_apis/Graph/Memberships/svc.NTNjNjc0MjQtNjAzNy00ZjQ0LTgzYmQtOTBiOWRmYzdkMzVkOkJ1aWxkOmZiODU1YTEyLWVhY2MtNGFjZS05MjQ3LTZmYTg2N2Q2MDYyOQ"
+      },
+      "membershipState": {
+         "href": "https://vssps.dev.azure.com/Test Project Public/_apis/Graph/MembershipStates/svc.NTNjNjc0MjQtNjAzNy00ZjQ0LTgzYmQtOTBiOWRmYzdkMzVkOkJ1aWxkOmZiODU1YTEyLWVhY2MtNGFjZS05MjQ3LTZmYTg2N2Q2MDYyOQ"
+      },
+      "storageKey": {
+         "href": "https://vssps.dev.azure.com/Test Project Public/_apis/Graph/StorageKeys/svc.NTNjNjc0MjQtNjAzNy00ZjQ0LTgzYmQtOTBiOWRmYzdkMzVkOkJ1aWxkOmZiODU1YTEyLWVhY2MtNGFjZS05MjQ3LTZmYTg2N2Q2MDYyOQ"
+      },
+      "avatar": {
+         "href": "https://dev.azure.com/Test Project Public/_apis/GraphProfile/MemberAvatars/svc.NTNjNjc0MjQtNjAzNy00ZjQ0LTgzYmQtOTBiOWRmYzdkMzVkOkJ1aWxkOmZiODU1YTEyLWVhY2MtNGFjZS05MjQ3LTZmYTg2N2Q2MDYyOQ"
+      }
+   },
+   "url": "https://vssps.dev.azure.com/Test Project Public/_apis/Graph/Users/svc.NTNjNjc0MjQtNjAzNy00ZjQ0LTgzYmQtOTBiOWRmYzdkMzVkOkJ1aWxkOmZiODU1YTEyLWVhY2MtNGFjZS05MjQ3LTZmYTg2N2Q2MDYyOQ",
+   "descriptor": "svc.NTNjNjc0MjQtNjAzNy00ZjQ0LTgzYmQtOTBiOWRmYzdkMzVkOkJ1aWxkOmZiODU1YTEyLWVhY2MtNGFjZS05MjQ3LTZmYTg2N2Q2MDYyOQ"
+}