Public/Set-TppPermission.ps1
|
<# .SYNOPSIS Set permissions for TPP objects .DESCRIPTION Adds or modifies permissions on TPP objects .PARAMETER Path Path to an object. Can pipe output from many other functions. .PARAMETER Guid Guid representing a unique object .PARAMETER IdentityId The id that represents the user or group. You can use Find-TppIdentity or Get-TppPermission to get the id. .PARAMETER Permission TppPermission object. You can create a new object or get existing object from Get-TppPermission. .PARAMETER Force Overwrite an existing permission if one exists .PARAMETER VenafiSession Authentication for the function. The value defaults to the script session object $VenafiSession created by New-VenafiSession. A TPP token or VaaS key can also provided. If providing a TPP token, an environment variable named TPP_SERVER must also be set. .INPUTS Path, Guid, IdentityId .OUTPUTS None .EXAMPLE Set-TppPermission -Guid '1234abcd-g6g6-h7h7-faaf-f50cd6610cba' -IdentityId 'AD+mydomain.com:azsxdcfvgbhnjmlk09877654321' -Permission $TppPermObject Permission a user/group on an object specified by guid .EXAMPLE Set-TppPermission -Path '\ved\policy\my folder' -IdentityId 'AD+mydomain.com:azsxdcfvgbhnjmlk09877654321' -Permission $TppPermObject Permission a user/group on an object specified by path .EXAMPLE $id = Find-TppIdentity -Name 'brownstein' | Select-Object -ExpandProperty Id Find-TppObject -Path '\VED' -Recursive | Get-TppPermission -IdentityId $id | Set-TppPermission -Permission $TppPermObject -Force Reset permissions for a specific user/group for all objects. Note the use of -Force to overwrite existing permissions. .LINK http://VenafiPS.readthedocs.io/en/latest/functions/Set-TppPermission/ .LINK https://github.com/Venafi/VenafiPS/blob/main/VenafiPS/Public/Set-TppPermission.ps1 .LINK https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Permissions-object-guid-principal.php .LINK https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-PUT-Permissions-object-guid-principal.php .NOTES Confirmation impact is set to Medium, set ConfirmPreference accordingly. #> function Set-TppPermission { [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium', DefaultParameterSetName = 'ByGuid')] param ( [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = 'ByPath')] [ValidateNotNullOrEmpty()] [ValidateScript( { if ( $_ | Test-TppDnPath ) { $true } else { throw "'$_' is not a valid DN path" } })] [Alias('DN')] [String[]] $Path, [Parameter(Mandatory, ParameterSetName = 'ByGuid', ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [Alias('ObjectGuid')] [guid[]] $Guid, [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [ValidateScript( { if ( $_ | Test-TppIdentityFormat ) { $true } else { throw "'$_' is not a valid Prefixed Universal Id format. See https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-IdentityInformation.php." } })] [Alias('PrefixedUniversalId', 'ID')] [string[]] $IdentityId, [Parameter(Mandatory)] [TppPermission] $Permission, [Parameter()] [switch] $Force, [Parameter()] [psobject] $VenafiSession = $script:VenafiSession ) begin { Test-VenafiSession -VenafiSession $VenafiSession -Platform 'TPP' $params = @{ VenafiSession = $VenafiSession Method = 'Post' UriLeaf = 'placeholder' Body = $Permission.ToHashtable() FullResponse = $true } } process { if ( $PSCmdLet.ParameterSetName -eq 'ByPath' ) { $inputObject = $Path } else { $inputObject = $Guid } foreach ($thisInputObject in $inputObject) { if ( $PSCmdLet.ParameterSetName -eq 'ByPath' ) { $thisGuid = $thisInputObject | ConvertTo-TppGuid } else { $thisGuid = $thisInputObject } $params.UriLeaf = "Permissions/Object/{$thisGuid}" foreach ( $thisId in $IdentityId ) { if ( $thisId.StartsWith('local:') ) { # format of local is local:universalId $type, $id = $thisId.Split(':') $params.UriLeaf += "/$type/$id" } else { # external source, eg. AD, LDAP # format is type+name:universalId $type, $name, $id = $thisId -Split { $_ -in '+', ':' } $params.UriLeaf += "/$type/$name/$id" } if ( $PSCmdlet.ShouldProcess($thisInputObject, "Set permission for $thisId") ) { try { $response = Invoke-VenafiRestMethod @params switch ([int]$response.StatusCode) { '201' { # success } '409' { # user/group already has permissions defined on this object # need to use a put method instead if ( $Force.IsPresent ) { Write-Verbose "Existing user/group found and Force option provided, updating existing permissions" $params.Method = 'Put' $response = Invoke-VenafiRestMethod @params if ( [int]$response.StatusCode -ne '200' ) { Write-Error ('Failed to update permission with error {0}' -f $response.StatusDescription) } } else { # force option not provided, let the user know what's up Write-Error ('Permission for {0} already exists. To override, provide the -Force option.' -f $thisId) } } default { Write-Error ('Failed to create permission with error {0}, {1}' -f [int]$response.StatusCode, $response.ReasonPhrase) } } } catch { Write-Error ("Failed to set permissions on object $thisInputObject, user/group $thisId. $_") } } } } } } |