Merge pull request #76 from teamviewer/TEAM-59155_Add-TeamViewerSsoIn…

…clusion

Add TeamViewerSsoInclusion script

Cmdlets/Public/Add-TeamViewerSsoInclusion.ps1

@@ -0,0 +1,53 @@
+function Add-TeamViewerSsoInclusion {
+    [CmdletBinding(SupportsShouldProcess = $true)]
+    param(
+        [Parameter(Mandatory = $true)]
+        [securestring]
+        $ApiToken,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateScript( { $_ | Resolve-TeamViewerSsoDomainId } )]
+        [Alias("Domain")]
+        [object]
+        $DomainId,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [string[]]
+        $Email
+    )
+    Begin {
+        $id = $DomainId | Resolve-TeamViewerSsoDomainId
+        $resourceUri = "$(Get-TeamViewerApiUri)/ssoDomain/$id/inclusion"
+        $emailsToAdd = @()
+		$null = $ApiToken
+
+        function Invoke-RequestInternal {
+            $body = @{
+                emails = @($emailsToAdd)
+            }
+			Invoke-TeamViewerRestMethod `
+				-ApiToken $ApiToken `
+                -Uri $resourceUri `
+                -Method Post `
+                -ContentType "application/json; charset=utf-8" `
+                -Body ([System.Text.Encoding]::UTF8.GetBytes(($body | ConvertTo-Json))) `
+                -WriteErrorTo $PSCmdlet `
+                -ErrorAction Stop | `
+                Out-Null
+        }
+    }
+    Process {
+        if ($PSCmdlet.ShouldProcess($Email, "Add SSO inclusion")) {
+            $emailsToAdd += $Email
+        }
+        if ($emailsToAdd.Length -eq 100) {
+            Invoke-RequestInternal
+            $emailsToAdd = @()
+        }
+    }
+    End {
+        if ($emailsToAdd.Length -gt 0) {
+            Invoke-RequestInternal
+        }
+    }
+}

Docs/Help/Add-TeamViewerSsoInclusion.md

@@ -0,0 +1,137 @@
+---
+external help file: TeamViewerPS-help.xml
+Module Name: TeamViewerPS
+online version: https://github.com/teamviewer/TeamViewerPS/blob/main/Docs/Help/Add-TeamViewerSsoInclusion.md
+schema: 2.0.0
+---
+
+# Add-TeamViewerSsoInclusion
+
+## SYNOPSIS
+
+Add emails to the inclusion list of a TeamViewer Single Sign-On domain.
+
+## SYNTAX
+
+```powershell
+Add-TeamViewerSsoInclusion [-ApiToken] <SecureString> [-DomainId] <Object> [-Email] <String[]> [-WhatIf]
+ [-Confirm] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Add emails to the inclusion list of a TeamViewer Single Sign-On domain.
+Only accounts with these email addresses will be able to login via Single
+Sign-On.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+PS /> Add-TeamViewerSsoInclusion -DomainId '45e0d050-15e6-4fcb-91b2-ea4f20fe2085' -Email '[email protected]'
+```
+
+Adds the email address '<[email protected]>' to the inclusion list of the given
+domain.
+
+## 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
+```
+
+### -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
+```
+
+### -DomainId
+
+Object that can be used to identify the SSO domain to add inclusion entries to.
+This can either be the SSO domain ID (as string or GUID) or a SsoDomain
+object that has been received using the `Get-TeamViewerSsoDomain` function.
+
+```yaml
+Type: Object
+Parameter Sets: (All)
+Aliases: Domain
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Email
+
+List of emails addresses to add to the inclusion list.
+The emails must be of the same email domain as the SSO domain, otherwise the
+command will fail.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 2
+Default value: None
+Accept pipeline input: True (ByValue)
+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
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS
+
+[Get-TeamViewerSsoDomain](Get-TeamViewerSsoDomain.md)

Tests/Public/Add-TeamViewerSsoInclusion.Tests.ps1

@@ -0,0 +1,73 @@
+BeforeAll {
+    . "$PSScriptRoot\..\..\Cmdlets\Public\Add-TeamViewerSsoInclusion.ps1"
+
+    @(Get-ChildItem -Path "$PSScriptRoot\..\..\Cmdlets\Private\*.ps1") | `
+        ForEach-Object { . $_.FullName }
+
+    $testApiToken = [securestring]@{}
+    $null = $testApiToken
+    $testDomainId = '45e0d050-15e6-4fcb-91b2-ea4f20fe2085'
+    $null = $testDomainId
+
+    Mock Get-TeamViewerApiUri { '//unit.test' }
+    $mockArgs = @{}
+    Mock Invoke-TeamViewerRestMethod { $mockArgs.Body = $Body }
+}
+
+Describe 'Add-TeamViewerSsoInclusion' {
+    It 'Should call the correct API endpoint' {
+        Add-TeamViewerSsoInclusion `
+            -ApiToken $testApiToken `
+            -DomainId $testDomainId `
+            -Email '[email protected]'
+        Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter {
+            $ApiToken -eq $testApiToken -And `
+                $Uri -eq "//unit.test/ssoDomain/$testDomainId/inclusion" -And `
+                $Method -eq 'Post' }
+    }
+
+    It 'Should add the given emails to the inclusion list' {
+        Add-TeamViewerSsoInclusion `
+            -ApiToken $testApiToken `
+            -DomainId $testDomainId `
+            -Email '[email protected]', '[email protected]'
+        $mockArgs.Body | Should -Not -BeNullOrEmpty
+        $body = [System.Text.Encoding]::UTF8.GetString($mockArgs.Body) | ConvertFrom-Json
+        $body.emails | Should -Contain '[email protected]'
+        $body.emails | Should -Contain '[email protected]'
+    }
+
+    It 'Should accept pipeline input' {
+        @('[email protected]', '[email protected]') | Add-TeamViewerSsoInclusion `
+            -ApiToken $testApiToken `
+            -DomainId $testDomainId
+        $mockArgs.Body | Should -Not -BeNullOrEmpty
+        $body = [System.Text.Encoding]::UTF8.GetString($mockArgs.Body) | ConvertFrom-Json
+        $body.emails | Should -Contain '[email protected]'
+        $body.emails | Should -Contain '[email protected]'
+    }
+
+    It 'Should handle domain objects as input' {
+        $testDomain = @{DomainId = $testDomainId; DomainName = 'test managed group' } | ConvertTo-TeamViewerSsoDomain
+        Add-TeamViewerSsoInclusion `
+            -ApiToken $testApiToken `
+            -Domain $testDomain `
+            -Email '[email protected]'
+        Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter {
+            $ApiToken -eq $testApiToken -And `
+                $Uri -eq "//unit.test/ssoDomain/$testDomainId/inclusion" -And `
+                $Method -eq 'Post' }
+    }
+
+    It 'Should create bulks' {
+        $testAddresses = @()
+        1..250 | ForEach-Object { $testAddresses += "foo$_@example.test" }
+        $testAddresses | Add-TeamViewerSsoInclusion `
+            -ApiToken $testApiToken `
+            -DomainId $testDomainId
+        Assert-MockCalled Invoke-TeamViewerRestMethod -Times 3 -Scope It
+        $mockArgs.Body | Should -Not -BeNullOrEmpty
+        $body = [System.Text.Encoding]::UTF8.GetString($mockArgs.Body) | ConvertFrom-Json
+        $body.emails | Should -HaveCount 50
+    }
+}