add new script Add-SsoExclusionsFromCSV (#24)

add new script Add-SsoExclusionsFromCSV that allows to add emails to SSO exclusion list from given CSV file

Author: skeller-tv

Add-SsoExclusionsFromCSV/Add-SsoExclusionsFromCSV.Tests.ps1

@@ -0,0 +1,69 @@
+# Copyright (c) 2019-2021 TeamViewer GmbH
+# See file LICENSE.txt
+
+BeforeAll {
+    $testApiToken = [securestring]@{}
+    . "$PSScriptRoot\Add-SsoExclusionsFromCSV.ps1" `
+        -ApiToken $testApiToken `
+        -csvPAth "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-TeamViewerSsoExclusion {}
+
+    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-SsoExclusionsFromCSV' {
+
+    It 'Should blah' {
+        Add-SsoExclusionsFromCSV -csvPath "example.csv" -HeaderName "Email"
+
+        Assert-MockCalled Get-TeamViewerSsoDomain -Times 1 -Scope It
+        Assert-MockCalled Add-TeamViewerSsoExclusion -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-TeamViewerSsoExclusion -Times 1 -Scope It -ParameterFilter {
+            $ApiToken -eq $testApiToken -And `
+                $DomainId -eq [guid]'33ad81bb-e88b-46d0-92e1-b4f1663abf31' -And `
+                $Email.Count -eq 3 }
+    }
+}

Add-SsoExclusionsFromCSV/Add-SsoExclusionsFromCSV.ps1

@@ -0,0 +1,101 @@
+<#
+ .SYNOPSIS
+    Adds users from provided CSV file to SSO exclusion list of their respective domain
+
+ .DESCRIPTION
+    The script fetches a list of SSO domains you have configured, loads the CSV file, 
+    will check for email addresses for each of your domains in the CSV and add them to the exclusion list of their repective domain
+    emails not matching to 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 exclusions`
+
+ .PARAMETER CSVPath
+    Path of .csv file that contains the emails
+
+ .PARAMETER HeaderName
+    Column name where to find emails in imported csv file
+
+ .EXAMPLE
+    $apiToken = 'SecretToken123' | ConvertTo-SecureString -AsPlainText -Force
+    .\Add-SsoExclusionsFromCSV -csvPath 'c:\ps playground\test.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 GmbH
+    See file LICENSE.txt
+    Version 2.0
+#>
+
+[CmdletBinding(DefaultParameterSetName = "csvPath", SupportsShouldProcess = $true)]
+param(
+    [Parameter(Mandatory = $true)]
+    [securestring] $ApiToken,
+
+    [Parameter(Mandatory = $true)]
+    [string] $csvPath,
+
+    [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-SsoExclusionsFromCSV {
+    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
+    param($csvPath, $HeaderName)
+
+    #import emails fom csv
+    $csvRows = Import-Csv -Path $csvPath
+	
+    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 emails found in CSV file"
+        exit
+    }
+    else {
+        Write-Information "Found $($emails.Count) emails 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 exclusions for $($domain.Name)"
+        if ($domainUsers.Count -gt 0 -And -Not $WhatIfPreference) {
+            Add-TeamViewerSsoExclusion -ApiToken $apiToken -DomainId $domain.Id -Email $domainUsers
+            Write-Information "Completed for domain $($domain.Name)"
+        }
+    }
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    Install-TeamViewerModule
+    Add-SsoExclusionsFromCSV -csvPath $csvPath -HeaderName $HeaderName
+}

Add-SsoExclusionsFromCSV/README.md

@@ -0,0 +1,41 @@
+# Add-SsoExclusionsFromCSV
+
+Adds users from provided CSV file to SSO exclusion 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-SsoExclusionsFromCSV -csvPath 'c:\ps playground\test.csv' -HeaderName 'Email'
+```
+
+### Import users from a CSV file that uses semi-colon as delimiter. Use the given API token
+
+```powershell
+$apiToken = 'SecretToken123' | ConvertTo-SecureString -AsPlainText -Force
+.\Add-SsoExclusionsFromCSV -csvPath 'c:\ps playground\test.csv' -HeaderName 'Email'
+```
+
+### Run the import script in "Test Mode" to see the changes that would be made.
+
+```powershell
+.\Add-SsoExclusionsFromCSV -csvPath 'c:\ps playground\test.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-SsoExclusionsFromCSV.ps1
+```

Add-SsoExclusionsFromCSV/example.csv

@@ -0,0 +1,3 @@
+Email,Name
+user1@example.test,User1
+user2@example.test,User2