Merge pull request #29 from AlexandrosAlexiou/Enrich-Managed-Devices-…

…Policy-Management Add policy management capabilities for managed devices
teamviewer · Sep 18, 2023 · 6c219bd · 6c219bd
2 parents ba4e062 + 0d5651c
commit 6c219bd
Show file tree

Hide file tree

Showing 7 changed files with 322 additions and 2 deletions.
diff --git a/TeamViewerPS/Public/Remove-TeamViewerPolicyFromManagedDevice.ps1 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
@@ -20,6 +20,11 @@ function Set-TeamViewerManagedDevice {
         [object]
         $Policy,
 
+        [ValidateScript( { $_ | Resolve-TeamViewerManagedGroupId } )]
+        [Alias("ManagedGroupId")]
+        [object]
+        $ManagedGroup,
+
         [switch]
         $RemovePolicy
     )
@@ -35,13 +40,22 @@ function Set-TeamViewerManagedDevice {
         elseif ($RemovePolicy) {
             $body['teamviewerPolicyId'] = ""
         }
+        elseif ($ManagedGroup) {
+            $body['managedGroupId'] = $ManagedGroup | Resolve-TeamViewerManagedGroupId
+        }
 
         if ($Policy -And $RemovePolicy) {
             $PSCmdlet.ThrowTerminatingError(
                 ("Parameters -Policy and -RemovePolicy cannot be used together." | `
                         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
@@ -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
@@ -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
@@ -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
@@ -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 <SecureString> -Device <Object> -PolicyType <PolicyType> [-WhatIf] [-Confirm] [<CommonParameters>]
+```
+
+## 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
@@ -15,7 +15,7 @@ Change properties of a TeamViewer managed device.
 
 ```powershell
 Set-TeamViewerManagedDevice [-ApiToken] <SecureString> [-Device] <Object> [[-Name] <String>]
- [[-Policy] <Object>] [-RemovePolicy] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [[-Policy] <Object>] [-RemovePolicy] [[-ManagedGroup] <Object>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## 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.