diff --git a/Cmdlets/Public/Add-TeamViewerSsoInclusion.ps1 b/Cmdlets/Public/Add-TeamViewerSsoInclusion.ps1 new file mode 100644 index 0000000..eb314e0 --- /dev/null +++ b/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 + } + } +} \ No newline at end of file diff --git a/Docs/Help/Add-TeamViewerSsoInclusion.md b/Docs/Help/Add-TeamViewerSsoInclusion.md new file mode 100644 index 0000000..3dd3e2c --- /dev/null +++ b/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] [-DomainId] [-Email] [-WhatIf] + [-Confirm] [] +``` + +## 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 'user@example.test' +``` + +Adds the email address '' 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) \ No newline at end of file diff --git a/Tests/Public/Add-TeamViewerSsoInclusion.Tests.ps1 b/Tests/Public/Add-TeamViewerSsoInclusion.Tests.ps1 new file mode 100644 index 0000000..0df3d83 --- /dev/null +++ b/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 'foo@example.test' + 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 'foo@example.test', 'bar@example.test' + $mockArgs.Body | Should -Not -BeNullOrEmpty + $body = [System.Text.Encoding]::UTF8.GetString($mockArgs.Body) | ConvertFrom-Json + $body.emails | Should -Contain 'foo@example.test' + $body.emails | Should -Contain 'bar@example.test' + } + + It 'Should accept pipeline input' { + @('foo@example.test', 'bar@example.test') | 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 'foo@example.test' + $body.emails | Should -Contain 'bar@example.test' + } + + It 'Should handle domain objects as input' { + $testDomain = @{DomainId = $testDomainId; DomainName = 'test managed group' } | ConvertTo-TeamViewerSsoDomain + Add-TeamViewerSsoInclusion ` + -ApiToken $testApiToken ` + -Domain $testDomain ` + -Email 'foo@example.test' + 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 + } +}