ScriptRunner Blog
ScriptRunner 2020PS7 – Powershell 7, Powershell Remoting via SSH and new cloud targets
Table of contents
- PowerShell 7 in ScriptRunner
- SSH setup and use with PowerShell 7
- Workflows with Office365 Power Automate
- Selection of the target system at script execution time
- Management of additional Office 365 services
- Azure and other cloud services
- PowerShell Remoting via Management/Jump Hosts
- PowerShell Remoting for Hyper-V, Container and CIM
- Multi-target scenarios with PowerShell PSSession
- Using PowerShell objects in queries
- Notes on the PowerShell Secrets Management Module
- Related links
With the 2020 release, our customers will receive a substantial feature update focusing on PowerShell 7, PowerShell Remoting, and ScriptRunner enhancements in conjunction with infrastructure automation. The following sections provide an overview. For individual topics we refer to separate blog posts, videos and our documentation. For a detailed list of all new features, please have a look at the release notes in the ScriptRunner knowledge base.
PowerShell 7 in ScriptRunner
Available for many platforms, PowerShell 7 enables IT Pros to use a single scripting language to achieve unified management of a heterogeneous infrastructure.
ScriptRunner, the leading all-in-one solution for Powershell management, supports automation and delegation scenarios with PowerShell 7 in parallel with Windows PowerShell 5.1.
If you want to try or use PowerShell 7, you can use the PowerShell7pwsh.zip package from ScriptRunner Setup.
- First install the .NET Core 3.1 Runtime on the ScriptRunner Server
- Unzip the zip file completely and copy the files into the directory
The shipped PowerShell 7 host in ScriptRunner is self-contained. This means that no additional PowerShell 7 installation is required.C:\ProgramFiles\ScriptRunner\Service\Pwsh
- Scripts for PowerShell 7 are executed by ScriptRunner in the SRXPSCoreHost.exe process environment. They are selected in the Action Configuration in the Admin Web App in the PowerShell Options (Figure 1).
No further precautions are required for local execution of scripts in PowerShell 7. If you want to run scripts in PowerShell 7 on a remote system, such as Linux or MacOS, PowerShell 7 must be installed and configured there. You can find the appropriate installation packages on the PowerShell GitHub repository.
SSH setup and use with PowerShell 7
To work with SSH and PowerShell 7 in ScriptRunner, the following steps need to be taken:
- Install the SSH client and SSH server on the respective system. In Windows Server 2019, it is available as an optional feature; for other platforms respective implementations are available.
- Installing PowerShell 7 on the systems (see section PowerShell 7 in ScriptRunner)
- Configuring SSH to use PowerShell 7
- Configuring SSH authentication
More information can be found here:
PowerShell Remoting Over SSH – PowerShell | Microsoft Docs
Enable PowerShell SSH Remoting in PowerShell 7 – Thomas Maurer
To use an SSH connection with ScriptRunner, you need a corresponding target system configuration (Figure 2).
By selecting the appropriate target system type, assigning the stored SSH credentials, and selecting the PowerShell 7 option in the Action Configuration, you are able to manage remote target systems over SSH with PowerShell 7.
To set up SSH authentication on a target system, create a credential for SSH and enter the account of the SSH user (Figure 3). This user must be authorized on the target system.
ScriptRunner either uses existing SSH key files from existing user profiles or manages them on the ScriptRunner server itself.
Existing key files of a user on the ScriptRunner server are located in the user directory by default. You can simply enable the default directory (-/.ssh/.) or alternatively specify a different directory (Figure 4).
If you want to centralize the SSH key files in ScriptRunner instead of the SSH key files in various user directories, use the “SSH Key File content” option (Figure 5).
This option allows you to copy the SSH key file content into the ScriptRunner Credentials configuration. ScriptRunner creates and automatically manages one SSH key file at a time.
This procedure provides more control, security and centralization than the standard.
Workflows with Office365 Power Automate
The integration of ScriptRunner with workflow systems has been a fixed product feature since 2016. The popularity of Office 365 has led many companies to consider using Microsoft Power Automate in various application scenarios.
Especially for IT operations teams the use of Power Automate as a workflow system in combination with ScriptRunner as a platform for PowerShell is attractive. This enables complex processes with approval procedures to be implemented in Power Automate as a workflow. Individual workflow steps, especially tasks with PowerShell, are executed by ScriptRunner as workflow participants and the results are transferred to the workflow.
With the new version ScriptRunner supports the direct deployment of ScriptRunner actions including the parameters in Power Automate. This allows any ScriptRunner action to be used as a building block in the workflow without the need to program complex WebAPI calls and parameter transfers.
The following steps have to be taken:
- Set up Microsoft on-premises data gateway on ScriptRunner
- Configure a ScriptRunner Web Service Connector for O365 Power Automate and assign the ScriptRunner actions available in the workflow
- Exporting an OpenAPI file from ScriptRunner using the Admin Web App
- Create a “Custom Connector” in Power Automate and import the OpenAPI file.
- Re-importing a customized OpenAPI file after changes to a ScriptRunner action
To export the OpenAPI file, select the previously configured connector and execute the export function in the action bar (Figure 6).
Now create a new “Custom Connector” in Power Automate and import the OpenAPI file from ScriptRunner.
If the Custom Connector has been created successfully in Power Automate, you have to set the options to connect to the on-premises gateway and Windows Authentication for security.
After creating a new Power Automate flow with manual trigger the workflow steps can now be created.
The configured custom connector is required for further configuration. This can be found in the section “Custom”.
The Custom Connector is used to select between the different actions. The action – SR INTERNAL – is used for internal communication between Power Automate and ScriptRunner. It can NOT be used in a flow.
After selecting the action, a corresponding connection must be configured. The user name and password for logging on to the ScriptRunner server is stored here. The previously configured gateway must also be selected.
Once the connector has been completely configured, the parameters can now be used directly depending on the selected action and assigned in the workflow.
Selection of the target system at script execution time
This feature enables users of the Delegate App, e.g. in the Service Desk, to select a target system from a previously defined set at the time of script execution on which an action is to be executed. This opens up a multitude of use cases.
Management of additional Office 365 services
An enhancement for the connection to Exchange Online has been implemented. From now on the new PowerShell module Exchange Online V2 (EXOv2) can be used (Figure 7).
To do this, the PowerShell module ExchangeOnline Management must be installed on the ScriptRunner server first. ScriptRunner then automatically establishes, authenticates and closes the connection using the new procedure implemented by Microsoft.
With EXOv2, the module for Azure Active Directory is now also used for Exchange Online. The old MS Online module is thus completely replaced.
The direct management support for the now very popular Microsoft Team was completely newly implemented (Figure 8). The entire connection and authentication handling is now done by ScriptRunner. The PowerShell module Microsoft Teams must be installed on the ScriptRunner server.
To get started with Microsoft Teams PowerShell management, we also provide the free ActionPack for Microsoft Teams on our GitHub repository.
The O365 Service for Microsoft Teams allows certificate-based logon to the Azure AD for connection establishment. To do this, you need a valid certificate on the ScriptRunner Server. The certificate must be stored in the local certificate store on the ScriptRunner Server.
For information on setting up a certificate-based logon to Azure AD, see Microsoft Docs: Azure Active Directory: Certificate-based Authentication.
The Certificate Thumbprint and the Application ID must be entered in the configuration of the target system.
Azure and other cloud services
The Certificate Thumbprint and the Application ID must be entered in the configuration of the target system with Az.
For the management of other cloud services with PowerShell, a new target system type has been implemented, the Generic Cloud Target (Figure 10). This allows you to enter a PowerShell command sequence for connection establishment and disconnection. Additionally, a specific module can be loaded into the connection process.
In the PowerShell code for the connection establishment the variable $Cred can be used. This variable is assigned with the configured access credential for the target system.
PowerShell Remoting via Management/Jump Hosts
In principle, this concept is also suitable for PowerShell in distributed environments. For example, it is possible to build site-specific PowerShell Jump Hosts on which all necessary PowerShell modules are installed and the scripts can be executed.
ScriptRunner extends this concept to use Jump Hosts as “distribution nodes” to other target systems (Figure 11). This bypasses the classic double hop problem in a policy-driven manner.
In addition to the pure “distribution node”, simple mixed-target scenarios can now also be built, e.g. to execute a script on a remote target system and directly access resources of an O365 or Azure client from there.
It is also possible to address a target system via a chain of Jump Hosts.
This feature is also used for PowerShell Direct to manage VMs in Hyper-V host or containers in Windows Container Service Host.
For the practical use of this feature the following requirements must be met:
- The Jump Host(s) are configured as target systems with standard PowerShell Remoting
- The actual target systems are configured. These target systems can also be cloud services, VMs and containers via PowerShell Direct.
- The configuration is performed on the actual target system using the function “Access to this target via management or jump host indirectly” . There the appropriate host must be selected.
- To control the access rights to connect and execute the scripts and to use the “springboard” the credential stored on the respective target system is used.
Tip: The PowerShell report documents the connection via Jump Hosts. If details are to be logged during testing, for example, the Verbose switch in the ScriptRunner action under PowerShell Options must be activated.
PowerShell Remoting for Hyper-V, Container and CIM
PowerShell Direct is a method developed by Microsoft to extend the use of PowerShell in virtualized environments and to reduce the overhead of connecting to virtual machines under Hyper-V or Docker containers under Windows Container Service. It also helps to avoid the double hop problem.
In classic PowerShell Remoting, a direct connection and PowerShell session must be established to each virtual machine or container. When using PowerShell Direct, a remoting session can be established to the Hyper-V host or container host. Then the virtual machines or containers can be addressed directly with their ID or name.
The CIM Sessions option enables you to set up and use connections to standardized CIM endpoints. Windows Management Instrumentation supports CIM.
To set up PowerShell Direct, as in the example, a target system must be set up with standard PowerShell Remoting on the Hyper-V or container host (Figure 12). The virtual machines or containers are set up as additional target systems with the PowerShell Direct option with Hyper-V (for VMs) or Container Service (for Docker Containers).
As in the example the VM name or VM ID can be used for this purpose. The access credential requires the corresponding execution rights of PowerShell in the VM.
To be able to control the VM via the host with PowerShell Direct, the Hyper-V host must be assigned as “via management or jump host indirectly” in the target VM configuration in ScriptRunner (Figure 13). Similarly, container target systems are set up with the container host.
To get the container ID for the configuration you can execute the Get-Container command on the container host once you have loaded the PowerShell Module Container.
Multi-target scenarios with PowerShell PSSession
What these scenarios have in common is that different systems, each with its own system rights, must be accessed at script runtime.
PowerShell natively provides the concept of sessions for this purpose. For example, you can use the New-PSSession cmdlet to create and switch between different sessions on the command line. In addition, the prefix feature allows you to automatically detect in which session a particular command should be run.
You can now use this PowerShell functionality directly in ScriptRunner for multi-target scenarios. You need the definitions of the parameters for the required sessions in the param-block of the PowerShell script.
Param
(
…
# PowerShell Remoting Session Type
[System.Management.Automation.Runspaces.PSSession]
$Session1,
[System.Management.Automation.Runspaces.PSSession]
$Session2,
# PowerShell CIM Session Type
[Microsoft.Management.Infrastructure.CimSession]
$cimsession,
…
)
In the parameter configuration of a ScriptRunner action, the session parameters can be assigned to a target system using drop-down selection (Figure 14).
ScriptRunner establishes the connection to the stored target system at runtime each time before the script is started. The associated PSSession object is passed to the script as a parameter. After the execution of the script, the session is automatically terminated by ScriptRunner.
The session is used in the script itself. Either with a program line
Invoke-Command -Session $Session1 -ScriptBlock { ... }
# or
Import-PSSession -Session $Session1 -Modules ...
This makes the script development easier. On the one hand, the session setup and termination no longer needs to be coded and on the other hand, multi-target scenarios can be implemented very easily in a script. In addition, security is improved when using different administrative credentials, since only the session can be used in the script, but not the user name/password or the credential.
Using PowerShell objects in queries
The basic idea of offering a dropdown menu in the UI for parameter selection has now been extended for scripted queries. In addition to individual string values, PowerShell objects can now also be passed.
Since a Scripted Query and the main script each run in their own PowerShell process, the object values must be passed between two separate PowerShell processes. Both the Hashtable and the PowerShell Custom Object can be used for this purpose. To use them, the hashtable or custom object must be defined in both the query script and the main script. The individual values are passed from the query to the main script as a base64-encoded string.
Instead of a single string, the query script fills the encoded values of a hashtable into the system variable $SRXEnv.ResultList.
The system variable $SRXEnv.ResultList2 stores the name of the object to be passed. The procedure is therefore similar to that already known for scripted queries. The procedure is similar if a custom object is used instead of a hashtable.
# Declaration Hashtable in param block
$hasht = @{ Name = ''; Age = 0 }
# Function code of query with foreach loop
…
$hasht.Name = 'Paul'
$hasht.Age = 31
# Filling the hashtable
if ($SRXEnv) {
$null = $SRXEnv.ResultList.Add($hasht)
$null = $SRXEnv.ResultList2.Add($hasht.Name)
}
When testing the query, the values encoded with the strings are displayed in the table column “Parameter Value”.
In the main script, the hashtable or custom object is also declared in the param block. The declaration must correspond to the form used in the query script. This parameter is linked to the query in the action so that the values of the encoded hashtable or custom object can be passed to the main script at runtime.
When a user starts the action, the query returns a list of named objects in the selection dropdown. The user selects a named object and the encoded values are passed to the main script. ScriptRunner uses the declared parameter type in the main script to decode the transferred string and assigns the individual values to the respective properties in the hashtable or custom object.
The properties can be accessed directly.
….
# from declaration of the hashtable as above
$Age = $hasht.Age
Notes on the PowerShell Secrets Management Module
Due to its architecture, its use is limited to local script execution only.
There is no added value of the module in ScriptRunner environments, on the contrary. The ability to execute scripts remotely, even across Jump Hosts, while maintaining centralized credential management in ScriptRunner and Password Servers is only possible with ScriptRunner.
Related posts
6 min read
Boost your IT automation efficiency with new ScriptRunner release
Sep 30, 2024 by Frank Kresse
We have just released our latest ScriptRunner update, version 7.1, packed with powerful new features aimed at making IT...
8 min read
Scriptember 2024 – Celebration of PowerShell and its community
Aug 16, 2024 by Heiko Brenn
Welcome to Scriptember! We are thrilled to announce the launch of a unique, month-long campaign dedicated to...
10 min read
Five reasons you should be using PSReadLine
Aug 14, 2024 by Jeffery Hicks
I'd like to think that because you are reading this, you are a professional PowerShell user and this article will be a...
About the author:
Frank Kresse is Head of Product and CEO of ScriptRunner. As the inventor of the automation and delegation solution for PowerShell, he advises clients on use case scenarios and develops solutions for the automation and the digitalization of their processes. He is also involved in technology start-ups.
Latest posts:
- Boost your IT automation efficiency with new ScriptRunner release
- Scriptember 2024 – Celebration of PowerShell and its community
- Five reasons you should be using PSReadLine
- Privacy Management with PowerShell – Let's look at the core features of Priva!
- Let's celebrate System Administrator Appreciation Day!