From 0d5651c0e4f6b705601c01d61504e4c3b199c593 Mon Sep 17 00:00:00 2001 From: Alexandros Alexiou Date: Wed, 13 Sep 2023 16:26:29 +0300 Subject: [PATCH] Add inherit from group policy functionality and remove policy from device --- ...move-TeamViewerPolicyFromManagedDevice.ps1 | 39 +++++ .../Public/Set-TeamViewerManagedDevice.ps1 | 14 ++ TeamViewerPS/TeamViewerPS.Types.ps1 | 6 + ...eamViewerPolicyFromManagedDevice.Tests.ps1 | 55 ++++++ .../Set-TeamViewerManagedDevice.Tests.ps1 | 23 +++ ...emove-TeamViewerPolicyFromManagedDevice.md | 157 ++++++++++++++++++ docs/commands/Set-TeamViewerManagedDevice.md | 30 +++- 7 files changed, 322 insertions(+), 2 deletions(-) create mode 100644 TeamViewerPS/Public/Remove-TeamViewerPolicyFromManagedDevice.ps1 create mode 100644 Tests/Public/Remove-TeamViewerPolicyFromManagedDevice.Tests.ps1 create mode 100644 docs/commands/Remove-TeamViewerPolicyFromManagedDevice.md diff --git a/TeamViewerPS/Public/Remove-TeamViewerPolicyFromManagedDevice.ps1 b/TeamViewerPS/Public/Remove-TeamViewerPolicyFromManagedDevice.ps1 new file mode 100644 index 0000000..61d7fa2 --- /dev/null +++ b/TeamViewerPS/Public/Remove-TeamViewerPolicyFromManagedDevice.ps1 @@ -0,0 +1,39 @@ +function Remove-TeamviewerPolicyFromManagedDevice { + [CmdletBinding(SupportsShouldProcess = $true)] + param( + [Parameter(Mandatory = $true)] + [securestring] + $ApiToken, + + [Parameter(Mandatory = $true, ValueFromPipeline = $true)] + [ValidateScript( { $_ | Resolve-TeamViewerManagedDeviceId } )] + [Alias("DeviceId")] + [object] + $Device, + + [Parameter(Mandatory = $true)] + [PolicyType] + $PolicyType + ) + Begin { + $body = @{ + 'policy_type' = [int]$PolicyType + } + } + Process { + $deviceId = $Device | Resolve-TeamViewerManagedDeviceId + $resourceUri = "$(Get-TeamViewerApiUri)/managed/devices/$deviceId/policy/remove" + + if ($PSCmdlet.ShouldProcess($Device.ToString(), "Change managed device entry")) { + Invoke-TeamViewerRestMethod ` + -ApiToken $ApiToken ` + -Uri $resourceUri ` + -Method Put ` + -ContentType "application/json; charset=utf-8" ` + -Body ([System.Text.Encoding]::UTF8.GetBytes(($body | ConvertTo-Json))) ` + -WriteErrorTo $PSCmdlet ` + -ErrorAction Stop | ` + Out-Null + } + } +} diff --git a/TeamViewerPS/Public/Set-TeamViewerManagedDevice.ps1 b/TeamViewerPS/Public/Set-TeamViewerManagedDevice.ps1 index ec99fef..62d415f 100644 --- a/TeamViewerPS/Public/Set-TeamViewerManagedDevice.ps1 +++ b/TeamViewerPS/Public/Set-TeamViewerManagedDevice.ps1 @@ -20,6 +20,11 @@ function Set-TeamViewerManagedDevice { [object] $Policy, + [ValidateScript( { $_ | Resolve-TeamViewerManagedGroupId } )] + [Alias("ManagedGroupId")] + [object] + $ManagedGroup, + [switch] $RemovePolicy ) @@ -35,6 +40,9 @@ function Set-TeamViewerManagedDevice { elseif ($RemovePolicy) { $body['teamviewerPolicyId'] = "" } + elseif ($ManagedGroup) { + $body['managedGroupId'] = $ManagedGroup | Resolve-TeamViewerManagedGroupId + } if ($Policy -And $RemovePolicy) { $PSCmdlet.ThrowTerminatingError( @@ -42,6 +50,12 @@ function Set-TeamViewerManagedDevice { ConvertTo-ErrorRecord -ErrorCategory InvalidArgument)) } + if (($Policy -or $RemovePolicy) -And $ManagedGroup) { + $PSCmdlet.ThrowTerminatingError( + ("The combination of parameters -Policy, -PolicyRemove and -ManagedGroup is not allowed." | ` + ConvertTo-ErrorRecord -ErrorCategory InvalidArgument)) + } + if ($body.Count -eq 0) { $PSCmdlet.ThrowTerminatingError( ("The given input does not change the managed device." | ` diff --git a/TeamViewerPS/TeamViewerPS.Types.ps1 b/TeamViewerPS/TeamViewerPS.Types.ps1 index cabf757..b1a10b0 100644 --- a/TeamViewerPS/TeamViewerPS.Types.ps1 +++ b/TeamViewerPS/TeamViewerPS.Types.ps1 @@ -3,3 +3,9 @@ enum TeamViewerConnectionReportSessionType { RemoteSupportActive = 2 RemoteSupportActiveSdk = 3 } + +enum PolicyType { + TeamViewer = 1 + Monitoring = 4 + PatchManagement = 5 +} diff --git a/Tests/Public/Remove-TeamViewerPolicyFromManagedDevice.Tests.ps1 b/Tests/Public/Remove-TeamViewerPolicyFromManagedDevice.Tests.ps1 new file mode 100644 index 0000000..4f87cdb --- /dev/null +++ b/Tests/Public/Remove-TeamViewerPolicyFromManagedDevice.Tests.ps1 @@ -0,0 +1,55 @@ +BeforeAll { + . "$PSScriptRoot/../../TeamViewerPS/Public/Remove-TeamViewerPolicyFromManagedDevice.ps1" + . "$PSScriptRoot/../../TeamViewerPS/TeamViewerPS.Types.ps1" + + @(Get-ChildItem -Path "$PSScriptRoot/../../TeamViewerPS/Private/*.ps1") | ` + ForEach-Object { . $_.FullName } + + $testApiToken = [securestring]@{} + $null = $testApiToken + $testDeviceId = '9e5617cb-2b20-4da2-bca4-c1bda85b29ab' + $null = $testDeviceId + + Mock Get-TeamViewerApiUri { '//unit.test' } + $mockArgs = @{} + Mock Invoke-TeamViewerRestMethod { $mockArgs.Body = $Body } +} + +Describe 'Remove-TeamViewerPolicyFromManagedDevice' { + + It 'Should call the correct API endpoint to remove a policy from the managed device' { + Remove-TeamViewerPolicyFromManagedDevice -ApiToken $testApiToken -Device $testDeviceId -PolicyType TeamViewer + Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter { + $ApiToken -eq $testApiToken -And ` + $Uri -eq "//unit.test/managed/devices/$testDeviceId/policy/remove" -And ` + $Method -eq 'Put' } + } + + It 'should remove teamviewer policy from managed device' { + Remove-TeamViewerPolicyFromManagedDevice -apitoken $testapitoken -device $testdeviceid -Policytype TeamViewer + $mockargs.body | Should -Not -BeNullOrEmpty + $body = [system.text.encoding]::utf8.getstring($mockargs.body) | ConvertFrom-Json + $body.policy_type | Should -Be 1 + } + + It 'should remove monitoring policy from managed device' { + Remove-TeamViewerPolicyFromManagedDevice -apitoken $testapitoken -device $testdeviceid -PolicyType Monitoring + $mockargs.body | Should -Not -BeNullOrEmpty + $body = [system.text.encoding]::utf8.getstring($mockargs.body) | ConvertFrom-Json + $body.policy_type | Should -Be 4 + } + + It 'should remove patch management policy from managed device' { + Remove-TeamViewerPolicyFromManagedDevice -apitoken $testapitoken -device $testdeviceid -PolicyType PatchManagement + $mockargs.body | Should -Not -BeNullOrEmpty + $body = [system.text.encoding]::utf8.getstring($mockargs.body) | ConvertFrom-Json + $body.policy_type | Should -Be 5 + } + + It 'Should throw an error when called with invalid policy type' { + { Remove-TeamViewerPolicyFromManagedDevice ` + -ApiToken $testApiToken ` + -Device $testDeviceId -PolicyType 2 } | Should -Throw + } +} + diff --git a/Tests/Public/Set-TeamViewerManagedDevice.Tests.ps1 b/Tests/Public/Set-TeamViewerManagedDevice.Tests.ps1 index 870e536..3936d3a 100644 --- a/Tests/Public/Set-TeamViewerManagedDevice.Tests.ps1 +++ b/Tests/Public/Set-TeamViewerManagedDevice.Tests.ps1 @@ -45,6 +45,13 @@ Describe 'Set-TeamViewerManagedDevice' { $body.teamviewerPolicyId | Should -Be '' } + It 'Should update the managed device policy to the managed group' { + Set-TeamViewerManagedDevice -ApiToken $testApiToken -Device $testDeviceId -ManagedGroup 'e579cfeb-0b29-4d91-9e81-2d9507f53ff8' + $mockArgs.Body | Should -Not -BeNullOrEmpty + $body = [System.Text.Encoding]::UTF8.GetString($mockArgs.Body) | ConvertFrom-Json + $body.managedGroupId | Should -Be 'e579cfeb-0b29-4d91-9e81-2d9507f53ff8' + } + It 'Should not be possible to set and remove the policy at the same time' { { Set-TeamViewerManagedDevice ` -ApiToken $testApiToken ` @@ -53,6 +60,22 @@ Describe 'Set-TeamViewerManagedDevice' { -RemovePolicy } | Should -Throw } + It 'Should not be possible to inherit and set a policy at the same time' { + { Set-TeamViewerManagedDevice ` + -ApiToken $testApiToken ` + -Device $testDeviceId ` + -Policy '2871c013-3040-4969-9ba4-ce970f4375e8' ` + -ManagedGroup '6808db5b-f3c1-4e42-8168-3ac96f5d456e' } | Should -Throw + } + + It 'Should not be possible to inherit and remove a policy at the same time' { + { Set-TeamViewerManagedDevice ` + -ApiToken $testApiToken ` + -Device $testDeviceId ` + -ManagedGroup '2871c013-3040-4969-9ba4-ce970f4375e8' ` + -RemovePolicy } | Should -Throw + } + It 'Should not be possible to use "none" or "inherit" as values for policy' { { Set-TeamViewerManagedDevice ` -ApiToken $testApiToken ` diff --git a/docs/commands/Remove-TeamViewerPolicyFromManagedDevice.md b/docs/commands/Remove-TeamViewerPolicyFromManagedDevice.md new file mode 100644 index 0000000..ecafb2f --- /dev/null +++ b/docs/commands/Remove-TeamViewerPolicyFromManagedDevice.md @@ -0,0 +1,157 @@ +--- +external help file: TeamViewerPS-help.xml +Module Name: TeamViewerPS +online version: [Link to Online Documentation] +schema: 2.0.0 +--- + +# Remove-TeamViewerPolicyFromManagedDevice + +## SYNOPSIS + +Remove a policy from a managed device based on type. + +Valid Types are: + +- TeamViewer +- Monitoring +- PatchManagement + +## SYNTAX + +```powershell +Remove-TeamViewerPolicyFromManagedDevice -ApiToken -Device -PolicyType [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +Remove a specified policy from a managed device. + +## EXAMPLES + +### Example 1 + +Remove TeamViewer policy from device + +```powershell +PS /> Remove-TeamViewerPolicyFromManagedDevice -Device 'd8773208-a685-4323-9de5-7f86951f8c30' -PolicyType 1 +``` + +```powershell +PS /> Remove-TeamViewerPolicyFromManagedDevice -Device 'd8773208-a685-4323-9de5-7f86951f8c30' -PolicyType TeamViewer +``` + +### Example 2 + +Remove Monitoring policy from device + +```powershell +PS /> Remove-TeamViewerPolicyFromManagedDevice -Device '730ee15a-1ea4-4d80-9cfe-5a01709d0a2f' -PolicyType 4 +``` + +```powershell +PS /> Remove-TeamViewerPolicyFromManagedDevice -Device '730ee15a-1ea4-4d80-9cfe-5a01709d0a2f' -PolicyType Monitoring +``` + +### Example 3 + +Remove PatchManagement policy from device + +```powershell +PS /> Remove-TeamViewerPolicyFromManagedDevice -Device '730ee15a-1ea4-4d80-9cfe-5a01709d0a2f' -PolicyType 5 +``` + +```powershell +PS /> Remove-TeamViewerPolicyFromManagedDevice -Device '730ee15a-1ea4-4d80-9cfe-5a01709d0a2f' -PolicyType PatchManagement +``` + +## PARAMETERS + +### -ApiToken + +The TeamViewer API access token. + +```yaml +Type: SecureString +Parameter Sets: (All) +Aliases: +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Device + +The managed device from which you want to remove the policy. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: DeviceId +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -PolicyType + +The type of policy to remove from the managed device. + +```yaml +Type: PolicyType (Enum) +Parameter Sets: (All) +Aliases: +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Object + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/docs/commands/Set-TeamViewerManagedDevice.md b/docs/commands/Set-TeamViewerManagedDevice.md index 4599997..1cc2bbb 100644 --- a/docs/commands/Set-TeamViewerManagedDevice.md +++ b/docs/commands/Set-TeamViewerManagedDevice.md @@ -15,7 +15,7 @@ Change properties of a TeamViewer managed device. ```powershell Set-TeamViewerManagedDevice [-ApiToken] [-Device] [[-Name] ] - [[-Policy] ] [-RemovePolicy] [-WhatIf] [-Confirm] [] + [[-Policy] ] [-RemovePolicy] [[-ManagedGroup] ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -53,7 +53,15 @@ Sets the policy of the device. PS /> Set-TeamViewerManagedDevice -Device '33a2e2e1-27ef-43e2-a175-f97ee0344033' -RemovePolicy ``` -Removes the policy from the managed device. +Removes the TeamViewer policy of the device. + +### Example 3 + +```powershell +PS /> Set-TeamViewerManagedDevice -Device '33a2e2e1-27ef-43e2-a175-f97ee0344033' -ManagedGroup '730ee15a-1ea4-4d80-9cfe-5a01709d0a2f' +``` + +Inherit the TeamViewer policy from a managed group to the device (the device has to be part of the managed group specified). ## PARAMETERS @@ -161,6 +169,24 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ManagedGroup + +Object that can be used to identify the managed group. +This can either be the managed group ID (as string or GUID) or a managed group +object that has been received using other module functions. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: ManagedGroupId + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + ### -WhatIf Shows what would happen if the cmdlet runs.