diff --git a/Add-SsoInclusionsFromCSV/Add-SsoInclusionsFromCSV.Tests.ps1 b/Add-SsoInclusionsFromCSV/Add-SsoInclusionsFromCSV.Tests.ps1 new file mode 100644 index 0000000..8d8449d --- /dev/null +++ b/Add-SsoInclusionsFromCSV/Add-SsoInclusionsFromCSV.Tests.ps1 @@ -0,0 +1,61 @@ +# Copyright (c) 2019-2024 TeamViewer Germany GmbH +# See file LICENSE + +BeforeAll { + $testApiToken = [securestring]@{} + . "$PSScriptRoot\Add-SsoInclusionsFromCSV.ps1" -ApiToken $testApiToken -Path 'testPath' -HeaderName 'Email' -InformationAction 'SilentlyContinue' + + Mock Invoke-TeamViewerPing { $true } + Mock Get-TeamViewerSsoDomain { @( + [PSCustomObject]@{Id = '9602c5f4-2779-4f9a-80e8-4829531789fe'; Name = 'example1.org' }, + [PSCustomObject]@{Id = '33ad81bb-e88b-46d0-92e1-b4f1663abf31'; Name = 'example2.org' } + ) + } + Mock Add-TeamViewerSsoInclusion {} + + Mock Import-Csv { ConvertFrom-Csv -InputObject @' + "EMail","Name" + "user1@example1.org","User1" + "user2@example1.org","User2" + "user3@example2.org","User3" + "user4@example2.org","User4" + "user5@example2.org","User5" + "user5@example3.org","User6" +'@ + } + + function Resolve-TeamViewerSsoDomainId { + param( + [Parameter(ValueFromPipeline = $true, Mandatory = $true)] + [object] + $Domain + ) + Process { + if ($Domain.PSObject.TypeNames -contains 'TeamViewerPS.SsoDomain') { + return [guid]$Domain.Id + } + elseif ($Domain -is [string]) { + return [guid]$Domain + } + elseif ($Domain -is [guid]) { + return $Domain + } + else { + throw "Invalid SSO domain identifier '$Domain'. Must be either a [TeamViewerPS.SsoDomain], [guid] or [string]." + } + } + } +} + +Describe 'Add-SsoInclusionsFromCSV' { + + It 'Should blah' { + Add-SsoInclusionsFromCSV -Path 'example.csv' -HeaderName 'Email' + + Assert-MockCalled Get-TeamViewerSsoDomain -Times 1 -Scope It + Assert-MockCalled Add-TeamViewerSsoInclusion -Times 1 -Scope It -ParameterFilter { + $ApiToken -eq $testApiToken -And $DomainId -eq [guid]'9602c5f4-2779-4f9a-80e8-4829531789fe' -And $Email.Count -eq 2 } + Assert-MockCalled Add-TeamViewerSsoInclusion -Times 1 -Scope It -ParameterFilter { + $ApiToken -eq $testApiToken -And $DomainId -eq [guid]'33ad81bb-e88b-46d0-92e1-b4f1663abf31' -And $Email.Count -eq 3 } + } +} \ No newline at end of file diff --git a/Add-SsoInclusionsFromCSV/Add-SsoInclusionsFromCSV.ps1 b/Add-SsoInclusionsFromCSV/Add-SsoInclusionsFromCSV.ps1 new file mode 100644 index 0000000..8944114 --- /dev/null +++ b/Add-SsoInclusionsFromCSV/Add-SsoInclusionsFromCSV.ps1 @@ -0,0 +1,113 @@ +<# + .SYNOPSIS + Adds users from a CSV file to the TeamViewer SSO inclusion list of their respective domain. + + .DESCRIPTION + The script fetches a list of SSO domains you have configured, loads the CSV file, + checks for email addresses for each of your domains in the CSV, and adds them to the inclusion list of their respective domain. + Email addresses not matching any of your domains will be skipped. + + .PARAMETER ApiToken + The TeamViewer API token to use. + Must be a user access token. + The token requires the following access permissions: + `Manage SSO domains > View details about domains, add and remove email inclusions` + + .PARAMETER Path + Path of a csv file that contains the email addresses. + + .PARAMETER HeaderName + Column name where to find email addresses in the imported csv file. + + .EXAMPLE + $apiToken = 'SecretToken123' | ConvertTo-SecureString -AsPlainText -Force + .\Add-SsoInclusionsFromCSV -Path 'c:\Example.csv' -HeaderName 'Email' -WhatIf + + .NOTES + This script requires the TeamViewerPS module to be installed. + This can be done using the following command: + + ``` + Install-Module TeamViewerPS + ``` + + Copyright (c) 2019-2023 TeamViewer Germany GmbH + See file LICENSE + Version 2.0 +#> + +[CmdletBinding(DefaultParameterSetName = 'Path', SupportsShouldProcess = $true)] +param( + [Parameter(Mandatory = $true)] + [securestring] $ApiToken, + + [Parameter(Mandatory = $true)] + [string] $Path, + + [Parameter(Mandatory = $true)] + [string] $HeaderName +) + +if (-Not $MyInvocation.BoundParameters.ContainsKey('ErrorAction')) { + $script:ErrorActionPreference = 'Stop' +} +if (-Not $MyInvocation.BoundParameters.ContainsKey('InformationAction')) { + $script:InformationPreference = 'Continue' +} + +function Install-TeamViewerModule { + if (!(Get-Module TeamViewerPS)) { + Install-Module TeamViewerPS + } +} + +function Add-SsoInclusionsFromCSV { + [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')] + param($Path, $HeaderName) + + # Import email addresses from CSV + $csvRows = Import-Csv -Path $Path + + if ($csvRows.Count -eq 0) { + Write-Information 'No entries found in CSV file!' + exit + } + else { + Write-Information "Found $($csvRows.Count) rows in CSV file." + } + + $emails = $csvRows | Select-Object -ExpandProperty $HeaderName + + if ($emails.Count -eq 0) { + Write-Information 'No valid email addresses found in CSV file!' + exit + } + else { + Write-Information "Found $($emails.Count) email addresses in CSV file." + } + + $domains = Get-TeamViewerSsoDomain -ApiToken $apiToken + + if ($domains.Count -eq 0) { + Write-Information 'No valid SSO domains found!' + exit + } + + foreach ($domain in $domains) { + $domainUsers = $emails | Where-Object -FilterScript { $_.Split('@')[1] -eq $domain.Name } + + Write-Information "Adding $($domainUsers.Count) email inclusions for $($domain.Name)..." + + if ($domainUsers.Count -gt 0 -And -Not $WhatIfPreference) { + Add-TeamViewerSsoInclusion -ApiToken $apiToken -DomainId $domain.Id -Email $domainUsers + + Write-Information "Completed for domain $($domain.Name)." + } + } +} + +if ($MyInvocation.InvocationName -ne '.') { + Install-TeamViewerModule + + Add-SsoInclusionsFromCSV -Path $Path -HeaderName $HeaderName +} \ No newline at end of file diff --git a/Add-SsoInclusionsFromCSV/README.md b/Add-SsoInclusionsFromCSV/README.md new file mode 100644 index 0000000..049d053 --- /dev/null +++ b/Add-SsoInclusionsFromCSV/README.md @@ -0,0 +1,41 @@ +# Add-SsoInclusionsFromCSV + +Adds users from a CSV file to the TeamViewer SSO inclusion list of their respective domain. + +## Prerequisites + +This script requires the `TeamViewerPS` powershell module to be installed. + +```powershell +Install-Module TeamViewerPS +``` + +## Examples + +### Import users from a CSV file + +```powershell +.\Add-SsoInclusionsFromCSV -Path 'c:\Example.csv' -HeaderName 'Email' +``` + +### Import users from a CSV file and use the given API token + +```powershell +$apiToken = 'SecretToken123' | ConvertTo-SecureString -AsPlainText -Force +.\Add-SsoInclusionsFromCSV -Path 'c:\Example.csv' -HeaderName 'Email' +``` + +### Run the import script in "Test Mode" to see the changes that would be made + +```powershell +.\Add-SsoInclusionsFromCSV -Path 'c:\Example.csv' -HeaderName 'Email' -WhatIf +``` + +## More help + +To get further help about the script and its parameters, execute the +`Get-Help` PowerShell cmdlet: + +```powershell +Get-Help -Detailed .\Add-SsoInclusionsFromCSV.ps1 +``` \ No newline at end of file diff --git a/Add-SsoInclusionsFromCSV/example.csv b/Add-SsoInclusionsFromCSV/example.csv new file mode 100644 index 0000000..989c8e8 --- /dev/null +++ b/Add-SsoInclusionsFromCSV/example.csv @@ -0,0 +1,3 @@ +Email,Name +user1@example.test,User1 +user2@example.test,User2 \ No newline at end of file