Merge pull request #29 from teamviewer/TEAM-59155_Publish_inclusion_list_import_script

add new script Add-SsoInclusionsFromCSV

Author: stefanhubertus

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 }
+    }
+}

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
+}

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
+```

Add-SsoInclusionsFromCSV/example.csv

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