Try Now

ScriptRunner 2020R2

Table of Contents

Post Featured Image

Version 2020R2 marks a new chapter in ScriptRunner’s integration with Azure AD, M365 Services, and Azure Cloud. At the same time, it is the first version to ship with the role-based portal, which will replace the previous web apps. Numerous additional features round off the 2020R2 release.

The Integration of ScriptRunner with Azure AD

Management of O365/M365 and many other cloud services with PowerShell has continued to improve since the 2018 release. With the new 2020R2 release, there is now for the first time the possibility to use ScriptRunner to not only manage services, but to provide direct integration with Azure AD, M365 and Azure Cloud. This results in the capabilities described in the following sections.

ScriptRunner is registered in Azure using app registration in Azure AD. This involves registering two apps, one for the ScriptRunner Service and one for the new ScriptRunner Portal.

The following functions are subsequently available with the ScriptRunner Service registration:

  • Certificate based authentication of ScriptRunner Server to Azure AD
  • Establishing a service principal with read permissions on the objects in Azure AD to configure roles in ScriptRunner with Azure AD security groups and Azure AD accounts
  • Usage of Azure Queries on Objects in Azure AD

The registration creates the target system “Azure AD Home Tenant” in ScriptRunner.

Registering ScriptRunner Portal in Azure AD allows you to:

  • Log in users in to ScriptRunner with their Azure AD account
  • Authorize on ScriptRunner Server according to role membership
  • Add ScriptRunner Portal to the App Panel in the M365 User Portal

For more on ScriptRunner’s integration with Azure and registration, see the blog post ScriptRunner, Azure and M365 – a perfect trio and the ScriptRunner Settings Manual.

User Login with Azure AD Accounts

Registering ScriptRunner Portal in Azure AD simultaneously enables the switch to logging in to Azure AD accounts. When the URL is called, the Azure AD login window will appear. After successful login, you will see the extension (JWT) on the top right of the account.

Important: after switching user login, you will no longer be able to log in users with their internal AD account. All configuration data in ScriptRunner Server and the web applications will be rewritten.

You can reverse the change by running the command

Unregister-AsrAzureADApp -TenantID -App Portal

on ScriptRunner Server.

For more on registration and login, see the ScriptRunner Settings Manual.

Azure Queries

Starting with this release, direct integration with Azure allows ScriptRunner’s popular query functionality to be extended to Azure AD, Azure resources, and Azure data. With the new Query Type Azure (Fig. 1), a very powerful tool is now available to design use cases for M365, Azure AD and Azure Cloud.
Screenshot of ScriptRunner Admin App, feature to create new queries. In the 'Select Query Type' tab, the 'Azure' option is selected.

Fig. 1: The new Query Type Azure is now available for selection

To simplify usability for many use cases, the following options are available as templates:

  • Azure User Query: Queries user objects of all types
  • Azure Group Query: Queries group objects of all types
  • Azure Group Members Query: Queries group members
  • Azure Member of Query: Queries group memberships

The following can be used for customizable queries:

  • Microsoft Graph Query
  • Azure Resource Graph Query
  • Azure Data Explorer Query

Example: Azure User Query

An Azure query will be used to determine all rooms that can be addressed as resources in Exchange Online. In the use case, ad-hoc statistics on the occupancy of specific rooms are to be made available as an HTML report.

In the following, we will only consider the query for room selection. An Azure user query is used for this, which maps Exchange Online resources such as rooms as user objects. To control the query on room objects, a simple property filter on the Azure AD User Property DisplayName is used here.

Screenshot of Azure settings in ScriptRunner Admin App: Filtering for objects whose DisplayName contains 'room'.

Figure 2: Querying objects whose DisplayName contains ‘room’

Testing the query is done as usual. If “-JSON-” was selected as the Value parameter in the query, the result set will contain a list of rooms as JSON objects. The value of the JSON object can be displayed via mouse-over. Further use of the JSON object is done with the new Feature PowerShell Splatting (see section “PowerShell Splatting feature”).

Example: Azure Group Query

In this example, we want to search for all Azure AD groups that have the ‘mailEnabled’ property. For this case, the example uses an ODATA filter.

Note: Azure AD queries are case-sensitive!

Screenshot of the Azure Configuration in the ScriptRunner Admin App.

Fig. 3: Filtering Azure AD groups with the ‘mailEnabled’ property

Example: Cascadable Query

In this use case, first a selection of an Azure AD group should be made and then the members of the group should be listed to be able to select one or more. The requirement is best solved with a cascaded query.

The Azure Group Query returns a list of all groups (with filters if necessary, as in Fig. 3). As parameter Value, the Object-Ids of the groups are required, since this ID variably controls the subsequent query to resolve the group into members (Fig. 4).

Screenshot of the Azure Configuration in the ScriptRunner Admin App.

Fig. 4: Cascadable Azure Query where first a group is selected and then its members are listed as choices

The Azure Query to resolve the group returns a list of the group members along with the members’ property sets as a JSON object (Fig. 5)

Screenshot of the Azure Configuration in the ScriptRunner Admin App.

Fig. 5: The list of group members of their property sets are delivered as JSON object

The connection of both queries is done in the Action on the parameter page according to the already known scheme.

Screenshot of a ScriptRunner Action: The results of the Azure queries are available as a selection in the input form of the Action.

Fig. 6: In the form of the ScriptRunner Action, the query results are available as a selection

You can read more about Microsoft Graph and Azure resource queries in the blog post ScriptRunner, Azure and M365 – a perfect trio.

Role-based ScriptRunner Portal

We created the new ScriptRunner Portal to improve UX and CX. It unifies the previous ScriptRunner Web Apps for help desk and end users, as well as new features for administrators.

The portal replaces the ScriptRunner Delegate App and the ScriptRunner Self-Service App. Customers can install the new portal as part of the update to this release and switch users to the unified URL to access it.

The portal is divided into functional apps(Fig. 7) and supports logging in with Azure AD user accounts. If MFA is enabled, the second factor of authentication is also requested during login.

Screenshot of the ScriptRunner Portal entry page in Admin View.

Fig. 7: Overview of the apps of the new ScriptRunner Portal in the Admin View

The entry into the portal as well as the available functions depend on the affiliation of a security group or an account to a ScriptRunner role.

Help desk and end users immediately start in the Run App. In addition, a help desk user has access to the Reports App.

Administrators have additional options in both of these apps. For example, the Action tiles can be directly customized in color and icon.

The new Statistics App (Fig. 8) makes it possible to make the benefits of ScriptRunner transparent.

Screenshot of the entry page of the statistics app in the ScriptRunner Portal

Fig. 8: The new Statistics App in ScriptRunner Portal

You can read more information and details about the new portal in the blog post The new role-based ScriptRunner Portal.

ScriptRunner Portal Widget

With the Portal Widget, our customers can seamlessly integrate ScriptRunner Actions into a wide variety of applications and use the full functionality of validation and queries.

This allows “invisible” contextual use of ScriptRunner automated tasks in other applications. Thus, a ScriptRunner Action can be placed in the intranet for end users directly in the place that is related to it in terms of content (Fig. 9).

The widget can be used to expand the functionality of existing self-service portals, to add new functions to business applications and to upgrade ITSM systems.

Because it is so easy to integrate, there are no limits to what you can do, including customizing the styling.

Screenshot of an embedded ScriptRunner Action to create a virtual machine

Fig. 9: Application example of the ScriptRunner Portal Widget

Further information and details on the new Portal Widget can be found in the bog article The new role-based ScriptRunner Portal or on the Portal Widget page.

Extended Role Configuration

With the integration into Azure AD, enhancements and improvements in the role configuration have been implemented. For example, multiple groups and/or individual accounts can now be assigned to a role group in ScriptRunner.

To do this, simply click the + button at My Claims (Fig. 10). You can now add a group or an account.

Also a new feature is the search function for local groups/accounts, for Active Directory groups and accounts as well as Azure AD groups and accounts.

The Basic Auth option is reserved for use with Web Service Connectors.

Screenshot ScriptRunner Portal: Function for adding new groups or accounts

Fig. 10: Function for adding new groups or accounts

Connection test to target systems

Connection problems to target systems or cloud services are part of the everyday life of administrators. The causes can be manifold. The problems may stem from the infrastructure between ScriptRunner Server and the target system, such as firewalls, proxies, etc. Also, the target system may not be configured sufficiently (local firewall, remoting) or authentication fails.

Until now, test scripts had to be written and test Actions had to be set up. From this version on ScriptRunner takes over the connection test directly. This way, errors can be narrowed down and fixed faster. Simply select the target system, click on Test in the Action bar and then start test. The live output shows you what is happening.

Screenshot: Log of a connection test in ScriptRunner

Fig. 11: Live output of a connection test

In the test run, a remote session is established with the stored credential to the target system and $PSVersion of the target system is returned. The connection is then closed again. The results can be viewed at any time as a PowerShell report.

PowerShell Remoting with Certificate-based Authentication

The WinRM service in Windows offers the possibility to authenticate a PowerShell Remoting Session by means of a certificate. To do this, WinRM must be enabled over HTTPS on the target system and a certificate must be stored there. Details can be found in the Microsoft Documentation.

A corresponding credential is then configured in ScriptRunner. Next, you assign the credential to the target system and use the https option in the remoting settings.

Screenshot: Credential Properties in ScriptRunner Admin App

Fig. 12: ScriptRunner Credential for PowerShell Remoting with Certificate-based Authentication using WinRM

PowerShell Splatting Feature

This new feature brings several advantages for the design of use cases in ScriptRunner. With a single query, multiple attributes or properties of an object can be determined and passed to the main script.

In this version, scripted queries and Azure queries can be used for this purpose. Thus, complex query cascades can be omitted, the use case becomes clearer for the user and several attributes can be processed more easily in a use case. The complexity in the PowerShell script is reduced because of the direct access to the content.

Scripted queries use a hashtable in the query script to which the results of the query are assigned. Using Azure Queries, the result set is stored in a JSON object.

Whether hashtable or JSON is used in the query, the results are passed encoded to a parameter in the main script to which the query was assigned.

The parameter in the main script must be of type hashtable. The structure of the hashtable follows the individual parameters to be used in the hashtable. The names of the parameters in the hashtable must match the names of the parameters in the query hashtable or JSON object. This will cause ScriptRunner to automatically map the matching values.

Additionally, a read-only attribute can be used for individual parameters of the hashtable. The following sample code shows the usage in the main Action script.

You can find further information on this feature in our Knowledge Base: Return multiple properties with a single Query.

The parameter attribute [Parameter(HelpMessage=”ASRDisplay(Splatting)”)] turns on the feature for the parameter [hashtable] $Address. This parameter $Address must be assigned the appropriate query in the Action configuration.

The other parameters in the hashtable itself define their structure. The parameter names must correspond to the names in the result set.
If an element is now selected from the result set in the UI (here “Peter Heim”), ScriptRunner automatically maps the values for the subsequent parameters.

With the parameter attribute [Parameter(HelpMessage=”ASRDisplay(Readonly)”)] the parameter [string] $Name is used in the UI as not changeable.

The [string] DateofBirth parameter is not given any values because it either does not exist in the result set or there is no name match for the parameter.

ScriptRunner SRXEnv-System Hashtable

Additional parameters have been added to the system hashtable that can be used in scripts:
  • SRXEnv.ActionID contains the ID of the started action.
  • SRXEnv.StartedReason contains the string, which was entered as reason in the UI
  • SRXEnv.CommandPath contains the path and name of the used script file

PowerShell 7

The optional use of PowerShell 7 has been extended to more elements in ScriptRunner. Besides Actions, scripted queries can now also use PowerShell 7. The connection test also supports target systems with PowerShell 7.
 

scriptrunner-portal-783x447 Webinar Special

ScriptRunner 2020R2 – What’s New?

Our latest ScriptRunner release 2020R2 comes with many new features. In this webinar we will cover the highlights of this version and how they help you with your automation journey.

Watch webinar for free >

 

 

Related links

About the author: