Automating ConnectWise ScreenConnect Launch URLs with PowerShell

Key Takeaways

• Automated Efficiency: Automates ConnectWise ScreenConnect URL generation, enhancing operational efficiency.
• Parameter Flexibility: Supports dynamic configurations through parameters like domain, session group, and instance ID.
• Administrative Requirement: Requires administrative privileges for modifying custom fields and registry access.
• Installation Verification: Checks for ScreenConnect installation using system registry, ensuring targeted script execution.
• Direct URL Construction: Generates direct launch URLs for each ScreenConnect instance, minimizing manual input.
• Integration Potential: Easily integrates into larger IT automation workflows, offering scalability.
• Security Consideration: Emphasizes the need for secure script usage to prevent unauthorized access.
• NinjaOne Synergy: Demonstrates the potential integration and efficiency gains with NinjaOne for remote system management.

In the dynamic field of information technology, the ability to efficiently manage and support remote systems is paramount. A key player in this domain is ConnectWise ScreenConnect, a robust remote support, access, and meeting solution. Automating its deployment and integration through PowerShell scripts enhances efficiency and reliability, a necessity for IT professionals and Managed Service Providers (MSPs).

Background

The script in focus is designed to automate the retrieval of ConnectWise ScreenConnect Launch URLs and save them to a custom field. This automation is crucial for IT environments where quick, seamless remote access to multiple machines is a daily requirement. The script’s ability to identify specific instances of ScreenConnect and generate direct connection URLs saves invaluable time and reduces manual errors, making it a vital tool for IT support and management.

The Script:

<#
.SYNOPSIS
    Get ConnectWise ScreenConnect Launch URL and save to custom field (defaults to screenconnectUrl). Requires the domain used for ScreenConnect and a Session Group the machine is a part of to successfully build URL.
.DESCRIPTION
    Get ConnectWise ScreenConnect Launch URL and save to custom field (defaults to screenconnectUrl). 
    Requires the domain used for ScreenConnect and a Session Group the machine is a part of to successfully build URL.
.EXAMPLE
    -ScreenConnectDomain "replace.me" -InstanceID "1111111111"

    Building Launch URL(s)...
    Launch URL(s) Created


    Instance  : 1111111111
    LaunchURL : https://replace.me/Host#Access/All%20Machines//555555-555-555-5555-55555/Join
    SessionId : 555555-555-555-5555-55555

PARAMETER: -ScreenConnectDomain "ExampleInput"
    The domain used for your Connectwise ScreenConnect Instance.

PARAMETER: -SessionGroup "ExampleInput"
    The Session Group in which the machine would normally be found. Defaults to "All Machines".

PARAMETER: -InstanceID "ExampleInput"
    The Instance ID for your instance of ScreenConnect. Used to differentiate between multiple installed ScreenConnect Instances.
    To get the instance id you can see it in the program's name in Control Panel e.g. ScreenConnect Client (yourinstanceidishere) 
    or in ScreenConnect itself (Admin > Advanced > Server Information > Instance Identifier Fingerprint).

PARAMETER: -CustomField "ReplaceWithAnyMultilineCustomField"
    The custom field you would like to write the results to. Defaults to screenconnectUrl

.OUTPUTS
    None
.NOTES
    Minimum OS Architecture Supported: Windows 7+, Server 2008+
    Release Notes: Initial Release
By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
    Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms. 
    Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party. 
    Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider. 
    Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations. 
    Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks. 
    Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script. 
    EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
#>

[CmdletBinding()]
param (
    [Parameter()]
    [String]$ScreenConnectDomain,
    [Parameter()]
    [String]$SessionGroup = "All Machines",
    [Parameter()]
    [String]$InstanceID,
    [Parameter()]
    [String]$CustomField = "screenconnectUrl"
)

begin {
    if ($env:screenconnectDomain -and $env:screenconnectDomain -notlike "null") { $ScreenConnectDomain = $env:screenconnectDomain }
    if ($env:sessionGroup -and $env:sessionGroup -notlike "null") { $SessionGroup = $env:sessionGroup }
    if ($env:instanceId -and $env:instanceId -notlike "null") { $InstanceID = $env:instanceId }
    if ($env:customFieldName -and $env:customFieldName -notlike "null") { $CustomField = $env:customFieldName }

    # Warn end-user if we're not provided an instance id
    if (-not ($InstanceID)) {
        Write-Warning "Without the instance id we will be unable to tell which ScreenConnect instance is yours if multiple are installed resulting in the wrong URL being displayed."
        Write-Warning "To get the instance id you can see it in the programs name in Control Panel ex. ScreenConnect Client (yourinstanceidishere) or in Control itself (Admin > Advanced > Server Information > Instance Identifier Fingerprint)"
    }

    # These two are actually necessary to build the URL
    if (-not ($ScreenConnectDomain) -or -not ($SessionGroup)) {
        Write-Error "Unable to build URL without the domain or Session Group."
        exit 1
    }

    # Test for elevation
    function Test-IsElevated {
        $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        $p = New-Object System.Security.Principal.WindowsPrincipal($id)
        $p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
    }

    # Checks the two Uninstall registry keys to see if the app is installed. Needs the name as it would appear in Control Panel.
    function Find-UninstallKey {
        [CmdletBinding()]
        param (
            [Parameter(ValueFromPipeline = $True)]
            [String]$DisplayName,
            [Parameter()]
            [Switch]$UninstallString
        )
        process {
            $UninstallList = New-Object System.Collections.Generic.List[Object]

            $Result = Get-ChildItem HKLM:SoftwareWow6432NodeMicrosoftWindowsCurrentVersionUninstall* | Get-ItemProperty | Where-Object { $_.DisplayName -like "*$DisplayName*" }
            if ($Result) { $UninstallList.Add($Result) }

            $Result = Get-ChildItem HKLM:SoftwareMicrosoftWindowsCurrentVersionUninstall* | Get-ItemProperty | Where-Object { $_.DisplayName -like "*$DisplayName*" }
            if ($Result) { $UninstallList.Add($Result) }

            # Programs don't always have an uninstall string listed here so to account for that I made this optional.
            if ($UninstallString) {
                $UninstallList | Select-Object -ExpandProperty UninstallString -ErrorAction SilentlyContinue
            }
            else {
                $UninstallList
            }
        }
    }

    # Define the name of the software we are searching for and look for it in both the 64 bit and 32 bit registry nodes.
    if (-not $InstanceID) { $SoftwareName = "ScreenConnect Client" }else { $SoftwareName = "ScreenConnect Client ($InstanceID)" }
    $ControlInstallation = Find-UninstallKey -DisplayName $SoftwareName

    # If its not installed lets error out.
    if (-not ($ControlInstallation)) {
        Write-Error "Connectwise ScreenConnect is not installed!"
        exit 1
    }

    # Elevation is required to write to custom fields. 
    if (-not (Test-IsElevated)) {
        Write-Error -Message "Access Denied. Please run with Administrator privileges."
        exit 1
    }
}
process {
    # The Image Path Registry Key contains the unique session id needed to generate the URL
    Write-Host "Building Launch URL(s)..."
    $ControlInstances = $ControlInstallation.DisplayName | ForEach-Object {
        $ImagePath = Get-ItemProperty -Path "Registry::HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServices$_" | Select-Object -Property ImagePath -ExpandProperty ImagePath
        $Id = ($ImagePath -split '&' | Where-Object { $_ -match 's=(.*-){4}' }) -replace "s="
        $Instance = ($_ -replace "ScreenConnect Client (" -replace ")").trim()
        New-Object psobject -Property @{
            Instance  = $Instance
            LaunchURL = [URI]::EscapeUriString("https://$ScreenConnectDomain/Host#Access/$SessionGroup//$Id/Join")
            SessionId = $Id
        }
    }

    # Create a Table/List of our results 
    Write-Host "Launch URL(s) Created"
    $ControlInstances | Format-List -Property Instance, LaunchURL, SessionId | Out-String | Write-Host

    # PowerShell 2.0 does not support ninjarmm-cli
    if ($PSVersionTable.PSVersion.Major -gt 2) {
        if ($ControlInstances.LaunchURL.Count -gt 1) {
            Ninja-Property-Set -Name $CustomField -Value ($ControlInstances | Format-List -Property Instance, LaunchURL | Out-String)
        }
        else {
            Ninja-Property-Set -Name $CustomField -Value ($ControlInstances.LaunchURL | Out-String)
        }
    }
    else {
        Write-Host "ninjarmm-cli does not support PowerShell 1 & 2. Refer to https://ninjarmm.zendesk.com/hc/en-us/articles/4405408656013 ."
    }
}
end {
    
    
    
}

 

Detailed Breakdown

• Parameter Initialization: The script begins by defining parameters like ScreenConnectDomain, SessionGroup, InstanceID, and CustomField. These parameters are essential for identifying the specific ScreenConnect instance and the machine group within it.
• Environment Variable Checks: It checks for and uses environment variables if they are set. This flexibility allows for dynamic adaptation to different system configurations.
• Pre-Execution Checks: The script ensures necessary parameters are provided and checks for administrative privileges, as modifying custom fields requires elevated permissions.
• Software Installation Verification: It searches the system registry to verify if ScreenConnect is installed, identifying the correct instance using the provided InstanceID.
• URL Generation: The core functionality where it constructs the ScreenConnect Launch URL using the domain, session group, and a unique session ID extracted from the system’s registry.
• Output Formatting: The generated URLs are formatted into a readable list, providing clear, actionable information for the user.

Potential Use Cases

Imagine an IT professional managing a fleet of machines across multiple sites. They need to quickly connect to any machine for troubleshooting. Using this script, they can generate direct ScreenConnect URLs for each machine and store them in a custom field, allowing instant remote access without manual URL construction.

Comparisons

Traditionally, generating ScreenConnect URLs involves manually identifying each machine’s session ID and constructing the URL. This script automates this process, significantly reducing the time and potential for error. Compared to GUI-based methods, the script offers scalability and integration capabilities with other automation workflows.

FAQs

• How does this script ensure it targets the correct ScreenConnect instance?
  The script uses the InstanceID parameter to identify the correct ScreenConnect instance.
• Can this script be integrated into larger automation workflows?
  Yes, its PowerShell nature makes it easily integrable into broader IT automation systems.
• Is administrative privilege mandatory for running this script?
  Yes, since it involves writing to custom fields and accessing system registries.

Implications

Automating URL generation enhances operational efficiency but also poses a risk if misused. If unauthorized access to the script occurs, it could lead to potential security breaches. Hence, securing the script and the environment where it’s used is crucial.

Recommendations

• Secure the Environment: Run the script in a secure, controlled environment.
• Regular Updates: Keep the ConnectWise ScreenConnect and PowerShell environment updated.
• Access Control: Restrict script access to authorized personnel only.

Final Thoughts

Incorporating such scripts into the NinjaOne platform can streamline remote management tasks, offering a more cohesive and efficient management experience. NinjaOne’s ability to integrate with tools like ConnectWise ScreenConnect, augmented with the power of automation, stands as a testament to its utility in the ever-evolving IT landscape.