ScriptRunner 2020PS7 – Powershell 7, Powershell Remoting via SSH and new cloud targets

Table of Contents

 

Post Featured Image

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.

scriptrunner-new_release2020

 

PowerShell 7 in ScriptRunner

 The new PowerShell 7 is the platform independent version of the popular automation language. It is based on the platform independent .NET Core Runtime.

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
    C:\ProgramFiles\ScriptRunner\Service\Pwsh
    The shipped PowerShell 7 host in ScriptRunner is self-contained. This means that no additional PowerShell 7 installation is required.
  • 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

With the introduction of PowerShell 7, SSH remoting is now moving into focus. PowerShell SSH Remoting uses the SSH protocol between an SSH client (on ScriptRunner server) and an SSH server (on the target system).

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

ScriptRunner is an important building block in a fully automated IT. The basic prerequisite for this is error-free cooperation with the other building blocks of the overall solution: workflows, monitoring systems, ITSM systems and other specialized automats, e.g. for SAP or in other specialized applications.

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

The increasing number of scenarios from our customers and the feedback we receive are incorporated into our development. A feature for more flexibility for the service desk is the new target selection in the Delegate Web App.

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

The new ScriptRunner version also offers new possibilities for managing Office 365 services with PowerShell.

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

Azure management with the Az module also allows certificate-based login for connection setup (Figure 9). For this you need a valid certificate on the ScriptRunner server. The certificate must be stored in the local certificate store on the ScriptRunner server.
 
Fig. 9: The Azure PowerShell Az module can now be selected as an option in the Cloud Connection Configuration of the ScriptRunner Admin App.
Screenshot Admin App: The "Cloud Connection" tab of the target configuration for a target of the type "Azure PowerShell Az module" is open

 

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

The use of so-called management or jump hosts has a long tradition in infrastructure management. Typically, numerous administration tools were installed on such systems and only selected admins were given access to the machine and tools. The main advantage is that the tools only need to be updated at one location and access to the tools from outside can be controlled.

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 scripts can be executed on a remote target system. ScriptRunner supports this possibility from the very beginning, which has now been extended by additional options. The additional options can be set when creating a new PowerShell Remoting Target.

Screenshot Admin App: The Tab "Select Target Type" of the target configuration is open. The Option "Hyper-V Direct" is selected

 

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

In practical use of PowerShell, especially in automation, access to different systems is required to process the scripts, e.g. to the internal AD and Azure AD, to Exchange on-prem and Exchange Online, to Windows Server and different shares or databases.

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

Queries are a crucial feature in ScriptRunner since version 2018R1. Besides the versatile use of Active Directory Queries, Scripted Queries have established themselves as a very flexible tool for the implementation of use cases.

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

The new PowerShell Secrets Management module supports the use of credentials stored in the Windows Credential Store and credential requests from password servers. The module works only locally, i.e. it must be installed on ScriptRunner Server.

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.

 

About the author: